libretto 0.6.16-experimental-zod.0 → 0.6.16

package/README.md

@@ -28,13 +28,17 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ## Installation
 
 ```bash
+# Install the Libretto command once. Requires Node.js and npm.
+curl -fsSL https://libretto.sh/install.sh | bash
+
+# Add Libretto to your project
 npm install libretto
 
 # First-time onboarding: install skills and download Chromium
-npx libretto setup
+libretto setup
 
 # Check workspace readiness at any time
-npx libretto status
+libretto status
 ```
 
 `setup` creates the `.libretto/` directory, installs agent skills, and downloads Chromium unless you pass `--skip-browsers`.
@@ -72,17 +76,17 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-npx libretto open <url>                    # launch browser and open a URL
-npx libretto run ./integration.ts --headless # run a workflow and close on success
-npx libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
-npx libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
-npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page
-npx libretto close                         # close the browser
+libretto open <url>                    # launch browser and open a URL
+libretto run ./integration.ts --headless # run a workflow and close on success
+libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
+libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
+libretto exec "<code>"                 # execute Playwright TypeScript against the open page
+libretto close                         # close the browser
 ```
 
 `run` sessions are inspectable through the same daemon-backed commands as `open` sessions. Successful runs close the browser by default; pass `--stay-open-on-success` to keep the browser open for `pages`, `snapshot`, and `exec`. Failed or paused workflows keep the browser open so you can inspect the exact page state before fixing or resuming the workflow.
 
-Run `npx libretto help` for the full list of commands.
+Run `libretto help` for the full list of commands.
 
 ## Configuration
 

package/README.template.md

@@ -26,13 +26,17 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ## Installation
 
 ```bash
+# Install the Libretto command once. Requires Node.js and npm.
+curl -fsSL https://libretto.sh/install.sh | bash
+
+# Add Libretto to your project
 npm install libretto
 
 # First-time onboarding: install skills and download Chromium
-npx libretto setup
+libretto setup
 
 # Check workspace readiness at any time
-npx libretto status
+libretto status
 ```
 
 `setup` creates the `.libretto/` directory, installs agent skills, and downloads Chromium unless you pass `--skip-browsers`.
@@ -70,17 +74,17 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-npx libretto open <url>                    # launch browser and open a URL
-npx libretto run ./integration.ts --headless # run a workflow and close on success
-npx libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
-npx libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
-npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page
-npx libretto close                         # close the browser
+libretto open <url>                    # launch browser and open a URL
+libretto run ./integration.ts --headless # run a workflow and close on success
+libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
+libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
+libretto exec "<code>"                 # execute Playwright TypeScript against the open page
+libretto close                         # close the browser
 ```
 
 `run` sessions are inspectable through the same daemon-backed commands as `open` sessions. Successful runs close the browser by default; pass `--stay-open-on-success` to keep the browser open for `pages`, `snapshot`, and `exec`. Failed or paused workflows keep the browser open so you can inspect the exact page state before fixing or resuming the workflow.
 
-Run `npx libretto help` for the full list of commands.
+Run `libretto help` for the full list of commands.
 
 ## Configuration
 

package/dist/cli/cli.js

@@ -14,6 +14,19 @@ Docs (agent-friendly): https://libretto.sh/docs
 function printSetupAudit() {
   warnIfInstalledSkillOutOfDate();
 }
+function isPackageManagerExec(env = process.env) {
+  return env.npm_command === "exec";
+}
+function warnIfPackageManagerExec() {
+  if (!isPackageManagerExec()) return;
+  console.error(
+    [
+      "Warning: running Libretto through a package manager is deprecated and will be removed in a future release.",
+      "Install the native command instead:",
+      "  curl -fsSL https://libretto.sh/install.sh | bash"
+    ].join("\n")
+  );
+}
 function isRootHelpRequest(rawArgs) {
   if (rawArgs.length === 0) return true;
   if (rawArgs[0] === "--help" || rawArgs[0] === "-h") return true;
@@ -23,6 +36,7 @@ async function runLibrettoCLI() {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
   loadEnv();
+  warnIfPackageManagerExec();
   ensureLibrettoSetup();
   const app = createCLIApp();
   try {

package/dist/cli/commands/browser.js

@@ -12,7 +12,6 @@ import {
 import { resolveProviderName } from "../core/providers/index.js";
 import { readLibrettoConfig } from "../core/config.js";
 import { createLoggerForSession } from "../core/context.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 import {
   assertSessionAvailableForStart,
   setSessionMode,
@@ -134,7 +133,7 @@ const connectInput = SimpleCLI.input({
   }
 }).refine(
   (input) => Boolean(input.cdpUrl),
-  `Usage: ${librettoCommand("connect <cdp-url> [--read-only|--write-access] --session <name>")}`
+  `Usage: libretto connect <cdp-url> [--read-only|--write-access] --session <name>`
 ).refine(
   (input) => !(input.readOnly && input.writeAccess),
   "Cannot pass both --read-only and --write-access."
@@ -162,7 +161,7 @@ const saveInput = SimpleCLI.input({
   }
 }).refine(
   (input) => Boolean(input.urlOrDomain),
-  `Usage: ${librettoCommand("save <url|domain> --session <name>")}`
+  `Usage: libretto save <url|domain> --session <name>`
 );
 const saveCommand = SimpleCLI.command({
   description: "Save current browser session"
@@ -217,14 +216,14 @@ const closeInput = SimpleCLI.input({
   }
 }).refine(
   (input) => input.all || input.session,
-  `Usage: ${librettoCommand("close <session>")}
-Usage: ${librettoCommand("close --all [--force]")}`
+  `Usage: libretto close <session>
+Usage: libretto close --all [--force]`
 );
 const closeCommand = SimpleCLI.command({
   description: "Close the browser"
 }).input(closeInput).handle(async ({ input }) => {
   if (input.force && !input.all) {
-    throw new Error(`Usage: ${librettoCommand("close --all [--force]")}`);
+    throw new Error(`Usage: libretto close --all [--force]`);
   }
   if (input.all) {
     const logger2 = createLoggerForSession("cli");

package/dist/cli/commands/execution.js

@@ -25,7 +25,6 @@ import {
 } from "../core/session.js";
 import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
 import { readLibrettoConfig } from "../core/config.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 import { renderSnapshotDiff } from "../../shared/snapshot/diff-snapshots.js";
 import {
   getProviderStartupTimeoutMs,
@@ -288,7 +287,7 @@ async function stopExistingFailedRunSession(session, logger) {
       pid: existingState.pid
     });
     throw new Error(
-      `Existing failed workflow process for session "${session}" (pid ${existingState.pid}) is still running. Close it with: ${librettoCommand(`close --session ${session}`)}`
+      `Existing failed workflow process for session "${session}" (pid ${existingState.pid}) is still running. Close it with: libretto close --session ${session}`
     );
   }
   clearSessionState(session, logger);
@@ -373,7 +372,7 @@ async function runResume(session, logger, sessionState) {
     const status = await client.getWorkflowStatus();
     if (status.state !== "paused") {
       throw new Error(
-        `Session "${session}" is not paused. Run "${librettoCommand(`run ... --session ${session}`)}" and call pause("${session}") first.`
+        `Session "${session}" is not paused. Run "libretto run ... --session ${session}" and call pause("${session}") first.`
       );
     }
     await client.resumeWorkflow();
@@ -427,9 +426,9 @@ async function runIntegrationFromFile(args, logger) {
           `Local auth profile not found for domain "${normalizedDomain}".`,
           `Expected profile file: ${profilePath}`,
           "To create it:",
-          `  1. ${librettoCommand(`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. ${librettoCommand(`save ${normalizedDomain} --session ${args.session}`)}`
+          `  3. libretto save ${normalizedDomain} --session ${args.session}`
         ].join("\n")
       );
     }
@@ -546,8 +545,8 @@ const execInput = SimpleCLI.input({
   }
 }).refine(
   (input) => input.code !== void 0,
-  `Usage: ${librettoCommand("exec <code|-> [--session <name>] [--visualize]")}
-       echo '<code>' | ${librettoCommand("exec - [--session <name>] [--visualize]")}`
+  `Usage: libretto exec <code|-> [--session <name>] [--visualize]
+       echo '<code>' | libretto exec - [--session <name>] [--visualize]`
 );
 const execCommand = SimpleCLI.command({
   description: "Execute Playwright TypeScript code"
@@ -583,8 +582,8 @@ const readonlyExecInput = SimpleCLI.input({
   }
 }).refine(
   (input) => input.code !== void 0,
-  `Usage: ${librettoCommand("readonly-exec <code|-> [--session <name>] [--page <id>]")}
-       echo '<code>' | ${librettoCommand("readonly-exec - [--session <name>] [--page <id>]")}`
+  `Usage: libretto readonly-exec <code|-> [--session <name>] [--page <id>]
+       echo '<code>' | libretto readonly-exec - [--session <name>] [--page <id>]`
 );
 const readonlyExecCommand = SimpleCLI.command({
   description: "Execute read-only Playwright inspection code"
@@ -601,7 +600,7 @@ const readonlyExecCommand = SimpleCLI.command({
     mode: "readonly-exec"
   });
 });
-const runUsage = `Usage: ${librettoCommand("run <integrationFile> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--read-only|--write-access] [--no-visualize] [--stay-open-on-success] [--viewport WxH] [--provider <provider>]")}`;
+const runUsage = `Usage: libretto run <integrationFile> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--read-only|--write-access] [--no-visualize] [--stay-open-on-success] [--viewport WxH] [--provider <provider>]`;
 const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {

package/dist/cli/commands/experiments.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { librettoCommand } from "../../shared/package-manager.js";
 import {
   EXPERIMENTS,
   isExperimentName,
@@ -10,10 +9,10 @@ import { SimpleCLI } from "affordance";
 const experimentNames = Object.keys(EXPERIMENTS);
 const experimentsUsage = [
   "Usage:",
-  `  ${librettoCommand("experiments")}`,
-  `  ${librettoCommand("experiments describe <experiment>")}`,
-  `  ${librettoCommand("experiments enable <experiment>")}`,
-  `  ${librettoCommand("experiments disable <experiment>")}`
+  `  libretto experiments`,
+  `  libretto experiments describe <experiment>`,
+  `  libretto experiments enable <experiment>`,
+  `  libretto experiments disable <experiment>`
 ].join("\n");
 const experimentsInput = SimpleCLI.input({
   positionals: [

package/dist/cli/commands/setup.js

@@ -7,7 +7,6 @@ import {
   LIBRETTO_CONFIG_PATH,
   REPO_ROOT
 } from "../core/context.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 import { SimpleCLI } from "affordance";
 function installBrowsers() {
   console.log("Installing Playwright Chromium...");
@@ -47,7 +46,7 @@ function copySkills() {
       "\n\u26A0\uFE0F No .agents/ or .claude/ directory found. Libretto skills were not installed."
     );
     console.log(
-      `  Create one of these directories in your repo root and rerun \`${librettoCommand("setup")}\` to install skills:`
+      `  Create one of these directories in your repo root and rerun \`libretto setup\` to install skills:`
     );
     console.log(`    mkdir ${join(REPO_ROOT, ".claude")}`);
     return;

package/dist/cli/commands/snapshot.js

@@ -7,7 +7,6 @@ import {
   withRequiredSession
 } from "./shared.js";
 import { DaemonClient } from "../core/daemon/ipc.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 import { renderSnapshot } from "../../shared/snapshot/render-snapshot.js";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function isZeroViewport(value) {
@@ -67,7 +66,7 @@ async function forceSnapshotViewport(page, viewport, logger, session, pageId, re
 async function runCompactSnapshot(args) {
   if (!args.daemonSocketPath) {
     throw new Error(
-      `Session "${args.session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: ${librettoCommand(`close --session ${args.session}`)}`
+      `Session "${args.session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: libretto close --session ${args.session}`
     );
   }
   args.logger.info("compact-snapshot-via-daemon", {
@@ -88,7 +87,7 @@ async function runCompactSnapshot(args) {
   console.log(`Screenshot at ${result.pngPath}`);
   console.log(renderSnapshot(result.snapshot, args.ref));
   console.log(
-    `Hint: Use ${librettoCommand(`snapshot <ref> --session ${args.session}`)} to inspect a subtree.`
+    `Hint: Use libretto snapshot <ref> --session ${args.session} to inspect a subtree.`
   );
 }
 const snapshotInput = SimpleCLI.input({

package/dist/cli/core/browser.js

@@ -8,7 +8,6 @@ import { createServer } from "node:net";
 import { isWindowsNamedPipePath } from "../../shared/ipc/socket-transport.js";
 import { getSessionProviderClosePath, PROFILES_DIR } from "./context.js";
 import { readLibrettoConfig } from "./config.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 import {
   getCloudProviderApi,
   getProviderStartupTimeoutMs
@@ -161,13 +160,13 @@ async function connect(session, logger, timeoutMs = 1e4, options) {
     });
     if (state.provider) {
       throw new Error(
-        `Could not connect to ${state.provider.name} session for "${session}" at ${endpoint}. The remote session may still be active. Try again, or close with: ${librettoCommand(`close --session ${session}`)}`
+        `Could not connect to ${state.provider.name} session for "${session}" at ${endpoint}. The remote session may still be active. Try again, or close with: libretto close --session ${session}`
       );
     }
     if (state.pid == null || !isPidRunning(state.pid)) {
       clearSessionState(session, logger);
       throw new Error(
-        `No browser running for session "${session}". Run '${librettoCommand(`open <url> --session ${session}`)}' first.`
+        `No browser running for session "${session}". Run 'libretto open <url> --session ${session}' first.`
       );
     }
     throw new Error(
@@ -197,14 +196,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 "${librettoCommand(`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 "${librettoCommand(`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;
@@ -237,7 +236,7 @@ async function runPages(session, logger) {
   let pageSummaries;
   if (!state.daemonSocketPath) {
     throw new Error(
-      `Session "${session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: ${librettoCommand(`close --session ${session}`)}`
+      `Session "${session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: libretto close --session ${session}`
     );
   }
   const client = await DaemonClient.connect(state.daemonSocketPath);
@@ -310,7 +309,7 @@ async function runOpen(rawUrl, headed, session, logger, options) {
     const authProfilePath = getProfilePath(authDomain);
     if (!existsSync(authProfilePath)) {
       throw new Error(
-        `No saved auth profile for "${authDomain}". Save one first: ${librettoCommand(`open https://${authDomain} --headed --session <name>`)}, log in, then run: ${librettoCommand(`save ${authDomain} --session <name>`)}`
+        `No saved auth profile for "${authDomain}". Save one first: libretto open https://${authDomain} --headed --session <name>, log in, then run: libretto save ${authDomain} --session <name>`
       );
     }
   }
@@ -565,7 +564,7 @@ async function runClose(session, logger) {
       } else {
         writeSessionState({ ...state, status: "cleanup-failed" }, logger);
         throw new Error(
-          `Failed to confirm remote ${state.provider.name} session cleanup for session "${session}". State preserved with status "cleanup-failed". Retry with: ${librettoCommand(`close --session ${session}`)}`
+          `Failed to confirm remote ${state.provider.name} session cleanup for session "${session}". State preserved with status "cleanup-failed". Retry with: libretto close --session ${session}`
         );
       }
     } else {
@@ -623,7 +622,7 @@ function formatDaemonCloseFailure(session, providerName, error) {
   const message = error instanceof Error ? error.message : String(error);
   const cleanupWarning = providerName ? ` State preserved with status "cleanup-failed" because remote ${providerName} cleanup could not be confirmed.` : " State preserved so you can retry or inspect the session.";
   return new Error(
-    `Failed to close session "${session}" gracefully over daemon IPC: ${message}.${cleanupWarning} Retry with: ${librettoCommand(`close --session ${session}`)}`
+    `Failed to close session "${session}" gracefully over daemon IPC: ${message}.${cleanupWarning} Retry with: libretto close --session ${session}`
   );
 }
 function waitForCloseSignalWindow(ms) {
@@ -667,7 +666,7 @@ async function closeProviderSessionDirectly(session, providerState, logger) {
       error
     });
     throw new Error(
-      `Failed to close remote ${providerState.name} session "${providerState.sessionId}" for session "${session}". State preserved with status "cleanup-failed". Retry with: ${librettoCommand(`close --session ${session}`)}`
+      `Failed to close remote ${providerState.name} session "${providerState.sessionId}" for session "${session}". State preserved with status "cleanup-failed". Retry with: libretto close --session ${session}`
     );
   }
 }
@@ -841,7 +840,7 @@ async function runCloseAll(logger, options) {
       [
         `Failed to close ${failedSessions.length} session(s) gracefully: ${formatSessionList(failedSessions)}.`,
         `Closed ${closed} session(s).`,
-        `Retry with: ${librettoCommand("close --all --force")}`
+        `Retry with: libretto close --all --force`
       ].join("\n")
     );
   }
@@ -894,7 +893,7 @@ async function runCloseAll(logger, options) {
   console.log(`Closed ${closedCount} session(s).`);
   if (failedProviderSessions.size > 0) {
     console.warn(
-      `Failed to confirm remote cleanup for ${failedProviderSessions.size} provider-backed session(s). State preserved with status "cleanup-failed". Retry with: ${librettoCommand("close --all")}`
+      `Failed to confirm remote cleanup for ${failedProviderSessions.size} provider-backed session(s). State preserved with status "cleanup-failed". Retry with: libretto close --all`
     );
   }
   for (const recording of replayUrls) {
@@ -918,11 +917,11 @@ async function runConnect(cdpUrl, session, logger, accessMode, experiments) {
         `Invalid CDP URL: ${cdpUrl}`,
         ``,
         `Expected an HTTP or WebSocket URL pointing to a Chrome DevTools Protocol endpoint, for example:`,
-        `  ${librettoCommand("connect http://127.0.0.1:9222")}`,
-        `  ${librettoCommand("connect http://remote-host:9222")}`,
-        `  ${librettoCommand("connect http://remote-host:9222/devtools/browser/<id>")}`,
-        `  ${librettoCommand("connect ws://remote-host:9222/devtools/browser/<id>")}`,
-        `  ${librettoCommand("connect wss://remote-host/cdp-endpoint")}`
+        `  libretto connect http://127.0.0.1:9222`,
+        `  libretto connect http://remote-host:9222`,
+        `  libretto connect http://remote-host:9222/devtools/browser/<id>`,
+        `  libretto connect ws://remote-host:9222/devtools/browser/<id>`,
+        `  libretto connect wss://remote-host/cdp-endpoint`
       ].join("\n")
     );
   }

package/dist/cli/core/daemon/daemon.js

@@ -33,7 +33,6 @@ import { handlePages } from "./pages.js";
 import { handleExec, handleReadonlyExec } from "./exec.js";
 import { DaemonExecRepl } from "./exec-repl.js";
 import { handleCompactSnapshot } from "./snapshot.js";
-import { librettoCommand } from "../../../shared/package-manager.js";
 import { snapshot } from "../../../shared/snapshot/capture-snapshot.js";
 import { diffSnapshots } from "../../../shared/snapshot/diff-snapshots.js";
 import {
@@ -446,7 +445,7 @@ class BrowserDaemon {
         const openPages = Array.from(this.pageById.values());
         if (openPages.length === 1) return openPages[0];
         throw new Error(
-          `The primary page for session "${this.session}" is closed. Run "${librettoCommand(`pages --session ${this.session}`)}" to choose a page id.`
+          `The primary page for session "${this.session}" is closed. Run "libretto pages --session ${this.session}" to choose a page id.`
         );
       }
       return this.page;
@@ -454,7 +453,7 @@ class BrowserDaemon {
     const page = this.pageById.get(pageId);
     if (!page) {
       throw new Error(
-        `Page "${pageId}" was not found in session "${this.session}". Run "${librettoCommand(`pages --session ${this.session}`)}" to list ids.`
+        `Page "${pageId}" was not found in session "${this.session}". Run "libretto pages --session ${this.session}" to list ids.`
       );
     }
     return page;

package/dist/cli/core/daemon/snapshot.js

@@ -4,7 +4,6 @@ import {
   snapshot
 } from "../../../shared/snapshot/capture-snapshot.js";
 import { waitForPageStable } from "../../../shared/snapshot/wait-for-page-stable.js";
-import { librettoCommand } from "../../../shared/package-manager.js";
 import {
   resolveSnapshotViewport,
   readSnapshotViewportMetrics,
@@ -17,7 +16,7 @@ async function handleCompactSnapshot(targetPage, session, logger, options = {})
   if (options.useCachedSnapshot) {
     if (!options.cachedSnapshot) {
       throw new Error(
-        `No compact snapshot is cached for session "${session}". Run ${librettoCommand(`snapshot --session ${session}`)} first.`
+        `No compact snapshot is cached for session "${session}". Run libretto snapshot --session ${session} first.`
       );
     }
     const screenshot2 = await captureSnapshotScreenshot(

package/dist/cli/core/session.js

@@ -18,7 +18,6 @@ import {
   parseSessionStateContent,
   serializeSessionState
 } from "../../shared/state/index.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 const SESSION_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
 const SESSION_DEV_SERVER = "dev-server";
 const SESSION_BROWSER_AGENT = "browser-agent";
@@ -120,7 +119,7 @@ function throwSessionNotFoundError(session) {
   }
   lines.push("");
   lines.push("Start one with:");
-  lines.push(`  ${librettoCommand(`open <url> --session ${session}`)}`);
+  lines.push(`  libretto open <url> --session ${session}`);
   throw new Error(lines.join("\n"));
 }
 function assertSessionStateExistsOrThrow(session) {
@@ -177,7 +176,7 @@ function assertSessionAllowsCommand(state, commandName, allowedModes) {
   }
   const supportedModes = [...allowedModes].join(", ");
   throw new Error(
-    `Command "${commandName}" is blocked for session "${state.session}" because it is in ${mode} mode. Allowed modes for this command: ${supportedModes}. Run \`${librettoCommand(`session-mode write-access --session ${state.session}`)}\` to unlock the session.`
+    `Command "${commandName}" is blocked for session "${state.session}" because it is in ${mode} mode. Allowed modes for this command: ${supportedModes}. Run \`libretto session-mode write-access --session ${state.session}\` to unlock the session.`
   );
 }
 function clearSessionState(session, logger) {
@@ -214,7 +213,7 @@ function assertSessionAvailableForStart(session, logger) {
   if (!existingState) return;
   if (existingState.provider && existingState.cdpEndpoint) {
     throw new Error(
-      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: ${librettoCommand(`close --session ${session}`)}`
+      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: libretto close --session ${session}`
     );
   }
   if (existingState.pid == null || !isPidRunning(existingState.pid)) {
@@ -223,7 +222,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: ${librettoCommand(`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/skill-version.js

@@ -2,7 +2,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { REPO_ROOT } from "./context.js";
-import { librettoCommand } from "../../shared/package-manager.js";
 const INSTALLED_SKILL_PATHS = [
   [".agents", "skills", "libretto", "SKILL.md"],
   [".claude", "skills", "libretto", "SKILL.md"]
@@ -64,7 +63,7 @@ function warnIfInstalledSkillOutOfDate() {
       return;
     }
     console.error(
-      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`${librettoCommand("setup")}\` to update your skills to the correct version.`
+      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`libretto setup\` to update your skills to the correct version.`
     );
   } catch {
   }

package/dist/cli/router.js

@@ -7,7 +7,6 @@ import { experimentsCommand } from "./commands/experiments.js";
 import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
-import { librettoCommand } from "../shared/package-manager.js";
 import { SimpleCLI } from "affordance";
 const cliRoutes = {
   ...browserCommands,
@@ -26,7 +25,7 @@ const cliRoutes = {
   snapshot: snapshotCommand
 };
 function createCLIApp() {
-  return SimpleCLI.define(librettoCommand(), cliRoutes);
+  return SimpleCLI.define("libretto", cliRoutes);
 }
 export {
   cliRoutes,

package/dist/shared/debug/pause.js

@@ -1,8 +1,7 @@
 import { getActivePauseHandler } from "./pause-handler.js";
-import { librettoCommand } from "../package-manager.js";
 function throwMissingSessionError() {
   throw new Error(
-    `pause(session) requires a non-empty session ID. Pass ctx.session from inside your workflow: await pause(ctx.session). To list running sessions, run: ${librettoCommand("status")}.`
+    `pause(session) requires a non-empty session ID. Pass ctx.session from inside your workflow: await pause(ctx.session). To list running sessions, run: libretto status.`
   );
 }
 async function pause(session) {
@@ -15,7 +14,7 @@ async function pause(session) {
   const handler = getActivePauseHandler();
   if (!handler) {
     throw new Error(
-      `pause(session) can only suspend an active Libretto workflow. Run the workflow with ${librettoCommand("run <integrationFile>")} and call pause(ctx.session) from inside the workflow.`
+      `pause(session) can only suspend an active Libretto workflow. Run the workflow with libretto run <integrationFile> and call pause(ctx.session) from inside the workflow.`
     );
   }
   await handler({

package/dist/shared/package-manager.d.ts

@@ -2,6 +2,5 @@ type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
 declare function detectPackageManager(root?: string, env?: NodeJS.ProcessEnv): PackageManager;
 declare function detectProjectPackageManager(root?: string): PackageManager;
 declare function installCommand(packageManager?: PackageManager): string;
-declare function librettoCommand(args?: string, packageManager?: PackageManager): string;
 
-export { type PackageManager, detectPackageManager, detectProjectPackageManager, installCommand, librettoCommand };
+export { type PackageManager, detectPackageManager, detectProjectPackageManager, installCommand };

package/dist/shared/package-manager.js

@@ -36,25 +36,8 @@ function installCommand(packageManager = detectProjectPackageManager()) {
       return "npm install";
   }
 }
-function librettoRunner(packageManager = detectPackageManager()) {
-  switch (packageManager) {
-    case "pnpm":
-      return "pnpm exec";
-    case "yarn":
-      return "yarn";
-    case "bun":
-      return "bunx";
-    default:
-      return "npx";
-  }
-}
-function librettoCommand(args = "", packageManager = detectPackageManager()) {
-  const suffix = args.trim();
-  return `${librettoRunner(packageManager)} libretto${suffix ? ` ${suffix}` : ""}`;
-}
 export {
   detectPackageManager,
   detectProjectPackageManager,
-  installCommand,
-  librettoCommand
+  installCommand
 };

package/docs/experiments.md

@@ -35,10 +35,10 @@ Example workspace state:
 `libretto experiments` is the CLI surface for inspecting and changing workspace experiment overrides.
 
 ```bash
-npx libretto experiments
-npx libretto experiments describe <experiment>
-npx libretto experiments enable <experiment>
-npx libretto experiments disable <experiment>
+libretto experiments
+libretto experiments describe <experiment>
+libretto experiments enable <experiment>
+libretto experiments disable <experiment>
 ```
 
 The command is implemented in `packages/libretto/src/cli/commands/experiments.ts` and registered as a top-level command. Listing prints registered experiments in registry order with their enabled/disabled state and description. `describe` prints the experiment status and full instructions. `enable` persists the override to `.libretto/config.json` and prints the full description with a prelude that the enabled experiment changes expected Libretto usage from the skill. `disable` persists the override and prints deterministic success text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.16-experimental-zod.0",
+  "version": "0.6.16",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",