libretto 0.6.32 → 0.6.34

package/dist/cli/core/providers/kernel.js

@@ -49,7 +49,8 @@ function createKernelProvider(options = {}) {
   const enableRecording = options.enableRecording ?? readBooleanEnv("KERNEL_ENABLE_RECORDING", false);
   const replays = /* @__PURE__ */ new Map();
   return {
-    async createSession() {
+    async createSession(sessionOptions) {
+      const sessionHeadless = sessionOptions?.headless ?? headless;
       const json = await kernelFetchJson(
         endpoint,
         apiKey,
@@ -57,7 +58,7 @@ function createKernelProvider(options = {}) {
         {
           method: "POST",
           body: JSON.stringify({
-            headless,
+            headless: sessionHeadless,
             stealth,
             timeout_seconds: timeoutSeconds
           })

package/dist/cli/core/providers/libretto-cloud.js

@@ -25,7 +25,8 @@ function createLibrettoCloudProvider() {
           json: {
             timeout_seconds: browserSessionTimeoutSeconds,
             profile_name: options?.authProfileName,
-            profile_persist: options?.authProfilePersist
+            profile_persist: options?.authProfilePersist,
+            headless: options?.headless
           }
         })
       });

package/dist/cli/core/telemetry.js

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveHostedApiUrl } from "./auth-fetch.js";
+import { readAuthState } from "./auth-storage.js";
 const TELEMETRY_FILE_NAME = "telemetry.json";
 const TELEMETRY_ENDPOINT_PATH = "/v1/telemetry/recordCliEvent";
 const TELEMETRY_TIMEOUT_MS = 250;
@@ -66,7 +67,7 @@ function writeTelemetryNotice() {
   if (!process.stderr.isTTY) return;
   process.stderr.write(
     [
-      "Libretto collects anonymous CLI telemetry: install id, timestamp, command event, error status, package version, and build channel only.",
+      "Libretto collects CLI telemetry: install id, timestamp, command event, error status, package version, build channel, and signed-in cloud user id only.",
       "Set LIBRETTO_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 to disable it, or set enabled:false in ~/.libretto/telemetry.json."
     ].join(" ") + "\n"
   );
@@ -82,15 +83,26 @@ async function recordCliTelemetryEvent(command, error) {
   if (isTelemetryDisabled()) return;
   const installId = await readOrCreateInstallId();
   if (!installId) return;
+  const cloudUserId = await readConfiguredCloudUserId();
   await sendWithTimeout({
     installId,
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     event: `libretto ${command.path.join(" ")}`,
     error,
     packageVersion,
-    buildChannel
+    buildChannel,
+    ...cloudUserId ? { cloudUserId } : {}
   });
 }
+async function readConfiguredCloudUserId() {
+  try {
+    const state = await readAuthState();
+    const cloudUserId = state?.session?.userId;
+    return cloudUserId && cloudUserId.length > 0 ? cloudUserId : null;
+  } catch {
+    return null;
+  }
+}
 async function sendWithTimeout(payload) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { GhostCursorOptions, ensureGhostCursor, ghostClick, hideGhostCursor, mov
 export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight } from './shared/visualization/highlight.js';
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.js';
 export { LibrettoAuthenticateOptions, librettoAuthenticate } from './shared/workflow/authenticate.js';
-export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowOptions, WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow } from './shared/workflow/workflow.js';
+export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowDefinition, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowOptions, WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow } from './shared/workflow/workflow.js';
 export { AuthProfileStorageState, captureAuthProfileStorageState, normalizeAuthProfileSite, parseAuthProfileSites } from './shared/workflow/auth-profile-state.js';
 import 'zod';
 import 'playwright';

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

@@ -3,6 +3,12 @@ import { z } from 'zod';
 import { RecoveryAction } from '../../runtime/recovery/page-fallbacks.js';
 import 'ai';
 
+declare const ViewportConfigSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+type ViewportConfig = z.infer<typeof ViewportConfigSchema>;
+
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
 type LibrettoWorkflowContext = {
     session: string;
@@ -18,6 +24,9 @@ type LibrettoWorkflowDefinition<InputSchema extends z.ZodType = z.ZodType<unknow
     output?: OutputSchema;
     credentials?: readonly string[];
     authProfile?: LibrettoWorkflowAuthProfile;
+    startUrl?: string;
+    gpu?: boolean;
+    viewport?: ViewportConfig;
     recoveryAction?: RecoveryAction;
 };
 type LibrettoWorkflowOptions<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> = LibrettoWorkflowDefinition<InputSchema, OutputSchema> & {
@@ -41,6 +50,9 @@ declare class LibrettoWorkflow<InputSchema extends z.ZodType = z.ZodType<unknown
     readonly credentialNames: readonly string[];
     readonly authProfileName?: string;
     readonly authProfileRefresh?: boolean;
+    readonly startUrl?: string;
+    readonly gpu?: boolean;
+    readonly viewport?: ViewportConfig;
     readonly recoveryAction?: RecoveryAction;
     private readonly handler;
     constructor(name: string, options: {
@@ -49,6 +61,9 @@ declare class LibrettoWorkflow<InputSchema extends z.ZodType = z.ZodType<unknown
         credentialNames?: readonly string[];
         authProfileName?: string;
         authProfileRefresh?: boolean;
+        startUrl?: string;
+        gpu?: boolean;
+        viewport?: ViewportConfig;
         recoveryAction?: RecoveryAction;
     } | undefined, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>);
     run(ctx: LibrettoWorkflowContext, input: unknown): Promise<z.infer<OutputSchema>>;
@@ -61,6 +76,9 @@ type ExportedLibrettoWorkflow = {
     readonly credentialNames: readonly string[];
     readonly authProfileName?: string;
     readonly authProfileRefresh?: boolean;
+    readonly startUrl?: string;
+    readonly gpu?: boolean;
+    readonly viewport?: ViewportConfig;
     readonly recoveryAction?: RecoveryAction;
     run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };

package/dist/shared/workflow/workflow.js

@@ -76,6 +76,9 @@ class LibrettoWorkflow {
   credentialNames;
   authProfileName;
   authProfileRefresh;
+  startUrl;
+  gpu;
+  viewport;
   recoveryAction;
   handler;
   constructor(name, options, handler) {
@@ -85,6 +88,9 @@ class LibrettoWorkflow {
     this.credentialNames = options?.credentialNames ?? [];
     this.authProfileName = options?.authProfileName;
     this.authProfileRefresh = options?.authProfileRefresh;
+    this.startUrl = options?.startUrl;
+    this.gpu = options?.gpu;
+    this.viewport = options?.viewport;
     this.recoveryAction = options?.recoveryAction;
     this.handler = handler;
   }
@@ -159,6 +165,9 @@ function getWorkflowConstructorOptions(options) {
     credentialNames: normalizeCredentialNames(options.credentials),
     authProfileName: authProfile?.name,
     authProfileRefresh: authProfile?.refresh,
+    startUrl: options.startUrl,
+    gpu: options.gpu,
+    viewport: options.viewport,
     recoveryAction: options.recoveryAction
   };
 }

package/docs/releasing.md

@@ -49,7 +49,7 @@ The workflow needs `contents: write` to create the GitHub release and tag, and `
 
 After trusted publishing is working, remove any old npm publish token from the repo secrets. npm recommends restricting token-based publishing after the migration.
 
-GitHub release notes are generated by `packages/libretto/scripts/generate-changelog.ts`. The script finds the previous release, compares that tag to the release commit, and passes only the merged PRs in that range to the release notes agent.
+GitHub release notes are generated by `packages/libretto/scripts/generate-changelog.ts`. The script finds the previous release, compares that tag to the release commit, and passes only the merged PRs in that range to the release notes agent. The release workflow uploads the generated notes and a changelog audit JSON artifact containing the release range, eligible PRs, inspected PR diffs, tool calls, and final model output.
 
 ## Prepare a release PR
 
@@ -108,6 +108,8 @@ The GitHub Releases page is the changelog for this repo.
 
 When the workflow runs `pnpm generate-changelog vX.Y.Z`, the script finds the previous GitHub release, compares that tag to the release commit, and extracts PR numbers from the compare commits. The release notes agent can inspect only those PRs with `gh pr view` and `gh pr diff`.
 
+The generator logs the release range and changelog-eligible PRs to stderr. When `CHANGELOG_AUDIT_FILE` is set, it also writes a JSON audit file with the eligible PR list, inspected diff PRs, tool-call summaries, and raw/final release notes. Generation fails if the agent does not inspect every eligible PR diff, so omissions are easier to diagnose before a GitHub release is created.
+
 To keep release notes readable, use clear PR titles and descriptions before merging. If a PR should not appear in the changelog, add the `skip-changelog` label.
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.32",
+  "version": "0.6.34",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",
@@ -70,7 +70,7 @@
     "playwright": "^1.58.2",
     "tsx": "^4.21.0",
     "zod": "^4.3.6",
-    "affordance": "^0.2.1"
+    "affordance": "^0.2.2"
   },
   "scripts": {
     "sync:mirrors": "node ../dev-tools/scripts/sync-mirrors.mjs",
@@ -78,7 +78,6 @@
     "sync-skills": "pnpm run sync:mirrors",
     "check:skills": "pnpm run check:mirrors",
     "build": "tsup --config tsup.config.ts",
-    "lint": "lintcn lint --tsconfig tsconfig.json",
     "type-check": "tsc --noEmit",
     "test": "turbo run test:vitest --filter=libretto --log-order=grouped",
     "test:vitest": "vitest run",

package/scripts/generate-changelog.ts

@@ -1,4 +1,6 @@
 import { execFileSync } from "node:child_process";
+import { dirname } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { Agent, type AgentTool, type AgentEvent } from "@mariozechner/pi-agent-core";
 import { getModel } from "@mariozechner/pi-ai";
 import { Type, type Static } from "@sinclair/typebox";
@@ -60,6 +62,34 @@ interface ReleaseContext {
   pullRequests: PullRequestDetails[];
 }
 
+interface ToolCallAudit {
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+  isError?: boolean;
+  resultTextBytes?: number;
+  resultTextPreview?: string;
+}
+
+interface ChangelogAudit {
+  tag: string;
+  generatedAt: string;
+  previousTag: string;
+  currentRef: string;
+  eligiblePullRequests: Array<{
+    number: number;
+    title: string;
+    labels: string[];
+    files: string[];
+    url: string;
+  }>;
+  inspectedDiffPullRequests: number[];
+  missingDiffPullRequests: number[];
+  toolCalls: ToolCallAudit[];
+  rawFinalText: string;
+  finalText: string;
+}
+
 function runGh(args: string[]): string {
   return execFileSync("gh", args, {
     encoding: "utf8",
@@ -190,6 +220,7 @@ function buildReleaseContext(currentTag: string): ReleaseContext {
 
 const releaseContext = buildReleaseContext(tag);
 const allowedPullRequestNumbers = new Set(releaseContext.pullRequests.map((pr) => String(pr.number)));
+const auditFilePath = process.env.CHANGELOG_AUDIT_FILE;
 const pullRequestSummary = releaseContext.pullRequests
   .map((pr) => {
     const labels = pr.labels.map((label) => label.name).join(", ") || "none";
@@ -204,6 +235,13 @@ const pullRequestSummary = releaseContext.pullRequests
   })
   .join("\n\n");
 
+console.error(`Changelog release range: ${releaseContext.previousTag}...${releaseContext.currentRef}`);
+console.error("Changelog-eligible PRs:");
+for (const pr of releaseContext.pullRequests) {
+  const labels = pr.labels.map((label) => label.name).join(", ") || "none";
+  console.error(`- #${pr.number} ${pr.title} [${labels}]`);
+}
+
 const GhToolParamsSchema = Type.Object({
   args: Type.String({ description: "Arguments to pass to gh (without the leading 'gh')" }),
 });
@@ -242,6 +280,12 @@ const ghTool: AgentTool = {
           `PR #${number ?? "(missing)"} is outside the ${releaseContext.previousTag}...${releaseContext.currentRef} release range.`,
         );
       }
+
+      // Diff inspection enforcement counts successful 'pr diff NUMBER' calls,
+      // so reject flags like --name-only that would return less than the full diff.
+      if (action === "diff" && parts.length > 3) {
+        throw new Error("'pr diff' accepts only a PR number. Run 'pr diff NUMBER' with no extra arguments.");
+      }
     }
     try {
       const output = runGh(parts);
@@ -277,6 +321,9 @@ const agent = new Agent({
       "- Write concise, user-facing release notes in markdown.",
       "- Group changes into sections like Features, Fixes, and Improvements. Only include sections that have entries.",
       "- Focus on what changed from the user's perspective, not internal implementation details.",
+      "- For feature and improvement entries, include minimal code blocks when they make the change easier to use.",
+      "- Each relevant feature or improvement can have its own snippet.",
+      "- Keep each code block to at most 10 lines, and use at most one comment line inside the block if helpful.",
       "- Do NOT include PR numbers or links.",
       "- Skip PRs labeled 'skip-changelog'.",
       "- Your response must contain ONLY the raw markdown release notes. No preamble like 'Here are the release notes'. No commentary or explanation. No '---' separators. The very first character of your response must be '#'. Example format:",
@@ -291,8 +338,123 @@ const agent = new Agent({
 });
 
 let finalText = "";
+let rawFinalText = "";
+const toolCalls = new Map<string, ToolCallAudit>();
+
+function getObjectProperty(value: unknown, key: string): unknown {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    return undefined;
+  }
+
+  return (value as Record<string, unknown>)[key];
+}
+
+function getTextContent(value: unknown): string {
+  const content = getObjectProperty(value, "content");
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  return content
+    .map((block) => {
+      if (typeof block !== "object" || block === null) {
+        return "";
+      }
+      const type = getObjectProperty(block, "type");
+      const text = getObjectProperty(block, "text");
+      return type === "text" && typeof text === "string" ? text : "";
+    })
+    .filter((text) => text.length > 0)
+    .join("\n");
+}
+
+function getInspectedDiffPullRequests(): number[] {
+  const inspected = new Set<number>();
+  for (const toolCall of toolCalls.values()) {
+    if (toolCall.isError !== false) {
+      // Only count tool calls that completed successfully.
+      continue;
+    }
+
+    const args = getObjectProperty(toolCall.args, "args");
+    if (typeof args !== "string") {
+      continue;
+    }
+
+    const parts = args.trim().split(/\s+/);
+    if (parts[0] !== "pr" || parts[1] !== "diff") {
+      continue;
+    }
+
+    const number = Number(parts[2]);
+    if (Number.isInteger(number)) {
+      inspected.add(number);
+    }
+  }
+
+  return [...inspected].sort((a, b) => a - b);
+}
+
+function buildAudit(): ChangelogAudit {
+  const inspectedDiffPullRequests = getInspectedDiffPullRequests();
+  const inspected = new Set(inspectedDiffPullRequests);
+  const missingDiffPullRequests = releaseContext.pullRequests
+    .map((pr) => pr.number)
+    .filter((number) => !inspected.has(number));
+
+  return {
+    tag,
+    generatedAt: new Date().toISOString(),
+    previousTag: releaseContext.previousTag,
+    currentRef: releaseContext.currentRef,
+    eligiblePullRequests: releaseContext.pullRequests.map((pr) => ({
+      number: pr.number,
+      title: pr.title,
+      labels: pr.labels.map((label) => label.name),
+      files: pr.files.map((file) => file.path),
+      url: pr.url,
+    })),
+    inspectedDiffPullRequests,
+    missingDiffPullRequests,
+    toolCalls: [...toolCalls.values()],
+    rawFinalText,
+    finalText,
+  };
+}
+
+function writeAuditFile(): void {
+  if (!auditFilePath) {
+    return;
+  }
+
+  mkdirSync(dirname(auditFilePath), { recursive: true });
+  writeFileSync(auditFilePath, `${JSON.stringify(buildAudit(), null, 2)}\n`);
+}
 
 agent.subscribe((event: AgentEvent) => {
+  if (event.type === "tool_execution_start") {
+    toolCalls.set(event.toolCallId, {
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      args: event.args,
+    });
+  }
+
+  if (event.type === "tool_execution_end") {
+    const text = getTextContent(event.result);
+    const existing = toolCalls.get(event.toolCallId) ?? {
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      args: undefined,
+    };
+    toolCalls.set(event.toolCallId, {
+      ...existing,
+      isError: event.isError,
+      resultTextBytes: Buffer.byteLength(text, "utf8"),
+      resultTextPreview: text.slice(0, 2000),
+    });
+  }
+
   if (event.type === "agent_end") {
     const messages = event.messages;
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -300,7 +462,8 @@ agent.subscribe((event: AgentEvent) => {
       if (msg.role === "assistant" && Array.isArray(msg.content)) {
         for (const block of msg.content) {
           if (typeof block === "object" && "type" in block && block.type === "text" && "text" in block) {
-            finalText = block.text as string;
+            rawFinalText = block.text as string;
+            finalText = rawFinalText;
             return;
           }
         }
@@ -309,10 +472,18 @@ agent.subscribe((event: AgentEvent) => {
   }
 });
 
-await agent.prompt("Generate the release notes now.");
+try {
+  await agent.prompt("Generate the release notes now.");
+} catch (error) {
+  console.error("Changelog generation failed: agent prompt threw an error.");
+  console.error(error);
+  writeAuditFile();
+  process.exit(1);
+}
 
 if (!finalText) {
   console.error("Changelog generation failed: no text output from agent.");
+  writeAuditFile();
   process.exit(1);
 }
 
@@ -324,7 +495,30 @@ if (headingIndex >= 0) {
   // Already starts with a heading, keep as-is.
 } else {
   console.error("Changelog generation failed: output does not contain markdown headings.");
+  writeAuditFile();
   process.exit(1);
 }
 
+const inspectedDiffPullRequests = getInspectedDiffPullRequests();
+const missingDiffPullRequests = releaseContext.pullRequests
+  .map((pr) => pr.number)
+  .filter((number) => !inspectedDiffPullRequests.includes(number));
+
+console.error(`Inspected PR diffs: ${inspectedDiffPullRequests.map((number) => `#${number}`).join(", ") || "none"}`);
+
+if (missingDiffPullRequests.length > 0) {
+  console.error(
+    `Changelog generation failed: the agent did not inspect diffs for PRs ${missingDiffPullRequests
+      .map((number) => `#${number}`)
+      .join(", ")}.`,
+  );
+  writeAuditFile();
+  process.exit(1);
+}
+
+writeAuditFile();
+if (auditFilePath) {
+  console.error(`Wrote changelog audit: ${auditFilePath}`);
+}
+
 process.stdout.write(finalText);

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.6.32"
+  version: "0.6.34"
 ---
 
 ## How Libretto Works
@@ -44,6 +44,18 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 
 - Use `npx libretto experiments` to list internal feature flags and `npx libretto experiments describe <name>` for usage notes when an experiment is enabled.
 
+## Run Modes
+
+There are three ways to run workflows:
+
+- Local browser run: `npx libretto run ./workflow.ts` runs workflow code and local Chromium on the current machine. This is easy to watch and private, but most likely to hit CAPTCHAs or anti-bot checks.
+- Hosted browser run: `npx libretto run ./workflow.ts --provider libretto-cloud` runs workflow code locally while the browser runs on provider infrastructure with stealth mechanisms. Use this for anti-bot/CAPTCHA issues, provider-specific behavior, and pre-deploy validation. If the user has not specified a provider, prefer `libretto-cloud` because it includes one free allocated browser-hour and does not require a third-party provider API key.
+- Deployed workflow: Libretto Cloud packages the workflow as an API-backed workflow with the same remote-browser anti-bot mechanisms as hosted provider runs. Deploy only after the workflow passes with the target provider.
+
+When editing a deployed workflow, validate changes with `run --provider <deployment-provider>` before redeploying; do not debug by repeatedly deploying and running the deployed job.
+
+If the user prefers a provider for all local CLI runs in a workspace or only deploys workflows to that provider, update `.libretto/config.json` with `provider` instead of repeating `--provider`. Read `references/configuration-file-reference.md` first.
+
 ## Working Rules
 
 - Announce which session you are using and what page you are on.
@@ -56,7 +68,7 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 - Authenticated workflows must implement `librettoAuthenticate` with declared credentials before validation. Use a reusable `*_totp_secret` credential for authenticator-app MFA, not a one-time `otp_code`; text and email verification codes are not supported for fully automated sign-in.
 - Read `references/website-authentication.md` when you need `librettoAuthenticate` examples or auth-profile details.
 - Validation requires a successful clean `run` on a fresh, unauthenticated session with confirmation of the actual returned output, not just process success. Use the same headed or headless mode that the workflow run is already using.
-- After validation, always show the user: (1) the output/results from the validation run, and (2) the same command so they can re-run it themselves. Include any `--params`, `--headed`, or `--headless` flags the workflow needs.
+- After validation, always show the user: (1) the output/results from the validation run, and (2) the same command so they can re-run it themselves. Include any `--params`, `--provider`, `--headed`, or `--headless` flags the workflow needs. Do not add `--auth-profile` to `run`; workflow `authProfile` metadata controls profile use.
 - Treat exploration sessions as disposable unless the user explicitly wants one kept open.
 - Close disposable sessions before your final response once exploration, debugging, or validation is complete. Open browsers keep consuming local or hosted resources.
 - Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
@@ -74,6 +86,7 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 
 ```bash
 npx libretto open https://example.com
+npx libretto open https://example.com --provider libretto-cloud --session provider-debug
 npx libretto open https://example.com --read-only --session readonly-example
 npx libretto open https://example.com --session debug-example
 ```
@@ -150,6 +163,7 @@ npx libretto exec --session debug-example --page <page-id> "await page.url()"
 - Use `run` to verify a workflow file after creating it or editing it. Use the same headed or headless mode for validation that the workflow run is already using. Plain `run` defaults to headed mode.
 - Workflows define their input shape with a Zod schema (see `references/code-generation-rules.md`). `run` validates `--params` against that schema before calling the handler and prints a clear field-by-field error if the input doesn't match.
 - Successful runs close the browser by default. Pass `--stay-open-on-success` when you need to inspect the completed state with `pages`, `snapshot`, or `exec`.
+- Use `--provider <name>` when validating behavior in that provider's browser runtime.
 - 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.
@@ -158,6 +172,7 @@ npx libretto exec --session debug-example --page <page-id> "await page.url()"
 
 ```bash
 npx libretto run ./integration.ts --params '{"status":"open"}'
+npx libretto run ./integration.ts --provider libretto-cloud
 npx libretto run ./integration.ts --read-only
 npx libretto run ./integration.ts --stay-open-on-success
 ```

package/skills/libretto/references/website-authentication.md

@@ -2,7 +2,7 @@
 
 Use this reference when a workflow needs a logged-in website session. The Working Rules in `../SKILL.md` define the required auth workflow; this file explains how to implement sign-in logic with `librettoAuthenticate`, and how auth profiles save signed-in state for later runs.
 
-Build and verify working sign-in logic first. The sign-in code takes priority; an auth profile is added only after the sign-in logic is verified, never as a substitute for it.
+Build and verify working sign-in logic first. Authenticated workflows must use `librettoAuthenticate`; an auth profile is added only after the sign-in logic is verified, never as a substitute for it.
 
 ## Sign-In Logic
 
@@ -44,7 +44,15 @@ export default workflow("accountWorkflow", {
 
 Auth profiles save the signed-in browser state (cookies, localStorage, IndexedDB) so later runs can reuse a logged-in session instead of signing in from scratch. The sign-in logic still takes priority: do not add a profile until the `librettoAuthenticate` sign-in step has been verified from a signed-out browser with no profile present. If you add a profile first, validation passes on the saved session while the untested sign-in logic fails the first time that session expires.
 
-A profile only holds whatever a signed-in session wrote into it, so it does nothing until a run has signed in at least once. With `refresh: true`, a successful run writes updated browser state back to the profile, so a fresh sign-in repairs an expired one. Local runs load `.libretto/profiles/<name>.json`; hosted runs use the provider-native profile with the same name.
+A profile only holds whatever a signed-in session wrote into it, so it does nothing until a run has signed in at least once. With `refresh: true`, a successful run writes updated browser state back to the profile, so a fresh sign-in repairs an expired one.
+
+Auth profiles are browser-runtime-specific:
+
+- Local runs load `.libretto/profiles/<name>.json`.
+- `libretto-cloud` and providers that explicitly support auth profiles use provider-backed profile state; a local profile file is not available to provider browsers.
+- Provider-backed profiles are created or refreshed by workflow-declared `authProfile` metadata. For manual login on a remote provider, run the hosted workflow with a pause/wait, ask the human to sign in through the live URL, use the observed login flow to implement `librettoAuthenticate`, then let the workflow finish so the provider can persist the profile.
+- A plain `open --provider` session does not have workflow auth profile metadata. `libretto save` writes a local profile from an open session; it does not persist provider-backed workflow auth profile state.
+- Revalidate login when switching providers, even if the profile name is the same.
 
 Add the profile to the workflow you already verified:
 
@@ -60,9 +68,15 @@ export default workflow("accountWorkflow", {
 ## Commands
 
 ```bash
+# Open the site in headed mode and ask the user to log in manually.
+npx libretto open https://app.example.com --headed --session login
+
 # Save the current signed-in session as a named, site-scoped profile.
 npx libretto save example-app --session login --sites app.example.com,auth.example.com
 
+# You can now reopen the site locally with that profile.
+npx libretto open https://app.example.com --auth-profile example-app
+
 # List or delete hosted auth profile names.
 npx libretto cloud profiles list
 npx libretto cloud profiles delete example-app
@@ -71,3 +85,5 @@ npx libretto cloud profiles delete example-app
 `save` captures cookies, localStorage, and IndexedDB only for the comma-separated `--sites` list.
 
 To reuse an existing signed-in Chrome profile instead of signing in, use `npx libretto import-chrome-profiles`. Get the user's consent first, since attaching can close or relaunch their Chrome window.
+
+When the user wants to deploy an authenticated workflow, trace the login flow before writing the workflow: open the site with the target provider, inspect behavior while the human signs in, implement `librettoAuthenticate`, then validate the workflow with the auth profile in the target browser runtime.

package/skills/libretto-readonly/SKILL.md

@@ -4,7 +4,7 @@ description: "Read-only Libretto workflow for diagnosing live browser state with
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.32"
+  version: "0.6.34"
 ---
 
 ## How Libretto Read-Only Works