libretto 0.6.24 → 0.6.25

package/dist/shared/workflow/auth-profile-state.js

@@ -0,0 +1,105 @@
+function parseAuthProfileSites(value) {
+  const sites = value.split(",").map((entry) => normalizeAuthProfileSite(entry)).filter((entry) => Boolean(entry));
+  return [...new Set(sites)];
+}
+function normalizeAuthProfileSite(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  try {
+    const url = trimmed.includes("://") ? new URL(trimmed) : new URL(`https://${trimmed}`);
+    return normalizeHost(url.hostname);
+  } catch {
+    const normalized = normalizeHost(trimmed);
+    return normalized || null;
+  }
+}
+async function captureAuthProfileStorageState(context, sites) {
+  const normalizedSites = [...new Set(
+    sites.map((site) => normalizeAuthProfileSite(site)).filter((site) => Boolean(site))
+  )];
+  if (normalizedSites.length === 0) {
+    throw new Error("At least one auth profile site is required.");
+  }
+  const state = await context.storageState({ indexedDB: true });
+  return {
+    sites: normalizedSites,
+    cookies: state.cookies.filter(
+      (cookie) => cookieDomainMatchesSites(cookie.domain, normalizedSites)
+    ),
+    origins: state.origins.filter(
+      (origin) => originMatchesSites(origin.origin, normalizedSites)
+    )
+  };
+}
+function mergeAuthProfileStorageState(existing, latest, sites) {
+  const normalizedSites = [...new Set(
+    sites.map((site) => normalizeAuthProfileSite(site)).filter((site) => Boolean(site))
+  )];
+  if (normalizedSites.length === 0) {
+    return existing;
+  }
+  const existingCookies = existing.cookies ?? [];
+  const latestCookies = latest.cookies ?? [];
+  const existingOrigins = existing.origins ?? [];
+  const latestOrigins = latest.origins ?? [];
+  const mergedSites = [
+    .../* @__PURE__ */ new Set([
+      ...existing.sites ?? [],
+      ...normalizedSites
+    ])
+  ];
+  return {
+    ...existing,
+    sites: mergedSites,
+    cookies: [
+      ...existingCookies.filter(
+        (cookie) => !cookieMatchesSites(cookie, normalizedSites)
+      ),
+      ...latestCookies.filter(
+        (cookie) => cookieMatchesSites(cookie, normalizedSites)
+      )
+    ],
+    origins: [
+      ...existingOrigins.filter(
+        (origin) => !originMatchesSites(origin.origin, normalizedSites)
+      ),
+      ...latestOrigins.filter(
+        (origin) => originMatchesSites(origin.origin, normalizedSites)
+      )
+    ]
+  };
+}
+function normalizeHost(value) {
+  let host = value.trim().toLowerCase();
+  while (host.startsWith(".")) host = host.slice(1);
+  while (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
+function cookieMatchesSites(cookie, sites) {
+  if (!cookie || typeof cookie !== "object" || !("domain" in cookie)) {
+    return false;
+  }
+  const domain = cookie.domain;
+  return typeof domain === "string" && cookieDomainMatchesSites(domain, sites);
+}
+function cookieDomainMatchesSites(cookieDomain, sites) {
+  const domain = normalizeHost(cookieDomain);
+  if (!domain) return false;
+  return sites.some(
+    (site) => domain === site || domain.endsWith(`.${site}`) || site.endsWith(`.${domain}`)
+  );
+}
+function originMatchesSites(origin, sites) {
+  try {
+    const host = normalizeHost(new URL(origin).hostname);
+    return sites.some((site) => host === site || host.endsWith(`.${site}`));
+  } catch {
+    return false;
+  }
+}
+export {
+  captureAuthProfileStorageState,
+  mergeAuthProfileStorageState,
+  normalizeAuthProfileSite,
+  parseAuthProfileSites
+};

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

@@ -0,0 +1,17 @@
+import { LibrettoWorkflowContext } from './workflow.js';
+import 'playwright';
+import 'zod';
+import '../../runtime/recovery/page-fallbacks.js';
+import 'ai';
+
+type LibrettoAuthenticateOptions = {
+    validate: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
+    fallback: (ctx: LibrettoWorkflowContext, credentials: Record<string, string>) => Promise<void> | void;
+    credentials?: Record<string, unknown>;
+    envPrefix?: string;
+};
+declare function librettoAuthenticate(ctx: LibrettoWorkflowContext, options: LibrettoAuthenticateOptions): Promise<{
+    usedProfile: boolean;
+}>;
+
+export { type LibrettoAuthenticateOptions, librettoAuthenticate };

package/dist/shared/workflow/authenticate.js

@@ -0,0 +1,37 @@
+async function librettoAuthenticate(ctx, options) {
+  if (await options.validate(ctx)) {
+    return { usedProfile: true };
+  }
+  const credentials = normalizeCredentials(
+    options.credentials ?? readCredentialsFromEnv(options.envPrefix)
+  );
+  await options.fallback(ctx, credentials);
+  if (!await options.validate(ctx)) {
+    throw new Error("Authentication fallback completed, but validation still failed.");
+  }
+  return { usedProfile: false };
+}
+function normalizeCredentials(credentials) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(credentials)) {
+    if (typeof value === "string") normalized[key] = value;
+  }
+  return normalized;
+}
+function readCredentialsFromEnv(envPrefix = "LIBRETTO_") {
+  const credentials = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(envPrefix) && value !== void 0) {
+      const credentialName = key.slice(envPrefix.length).toLowerCase();
+      if (isLibrettoControlCredential(envPrefix, credentialName)) continue;
+      credentials[credentialName] = value;
+    }
+  }
+  return credentials;
+}
+function isLibrettoControlCredential(envPrefix, credentialName) {
+  return envPrefix === "LIBRETTO_" && ["api_key", "api_url", "timeout_seconds"].includes(credentialName);
+}
+export {
+  librettoAuthenticate
+};

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

@@ -0,0 +1,5 @@
+declare function readCredentialInputsFromEnv(env?: NodeJS.ProcessEnv): Record<string, string>;
+declare function normalizeCredentialNames(names: readonly string[] | undefined): string[];
+declare function mergeCredentialsIntoInput(input: unknown, credentialNames?: readonly string[], env?: NodeJS.ProcessEnv): unknown;
+
+export { mergeCredentialsIntoInput, normalizeCredentialNames, readCredentialInputsFromEnv };

package/dist/shared/workflow/credentials.js

@@ -0,0 +1,68 @@
+function asStringMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const result = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (typeof rawValue === "string") result[key] = rawValue;
+  }
+  return result;
+}
+function readHostedCredentials(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return {};
+  }
+  const record = input;
+  return asStringMap(record.credentials);
+}
+function readCredentialInputsFromEnv(env = process.env) {
+  const credentials = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.startsWith("LIBRETTO_CLOUD_") || value === void 0) continue;
+    if (value.trim().length === 0) continue;
+    const name = key.slice("LIBRETTO_CLOUD_".length).toLowerCase();
+    if (!name || name === "api_key") continue;
+    credentials[name] = value;
+  }
+  return credentials;
+}
+function normalizeCredentialNames(names) {
+  if (!names) return [];
+  const normalized = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const value = name.trim().toLowerCase();
+    if (value.length > 0) normalized.add(value);
+  }
+  return [...normalized];
+}
+function filterCredentialMap(credentials, names) {
+  const result = {};
+  for (const name of names) {
+    if (credentials[name] !== void 0) result[name] = credentials[name];
+  }
+  return result;
+}
+function shouldReadCredentialInputsFromEnv(env) {
+  return (env.LIBRETTO_HOSTED_RUNTIME?.trim().length ?? 0) === 0;
+}
+function mergeCredentialsIntoInput(input, credentialNames, env = process.env) {
+  const normalizedNames = normalizeCredentialNames(credentialNames);
+  if (normalizedNames.length === 0) return input;
+  const existingCredentials = readHostedCredentials(input);
+  const envCredentials = shouldReadCredentialInputsFromEnv(env) ? readCredentialInputsFromEnv(env) : {};
+  const mergedCredentials = {
+    ...filterCredentialMap(envCredentials, normalizedNames),
+    ...filterCredentialMap(existingCredentials, normalizedNames)
+  };
+  if (Object.keys(mergedCredentials).length === 0) return input;
+  const base = input && typeof input === "object" && !Array.isArray(input) ? { ...input } : {};
+  return {
+    ...base,
+    credentials: mergedCredentials
+  };
+}
+export {
+  mergeCredentialsIntoInput,
+  normalizeCredentialNames,
+  readCredentialInputsFromEnv
+};

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

@@ -9,9 +9,15 @@ type LibrettoWorkflowContext = {
     page: Page;
 };
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
+type LibrettoWorkflowAuthProfile = string | {
+    name: string;
+    refresh?: boolean;
+};
 type LibrettoWorkflowDefinition<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> = {
     input?: InputSchema;
     output?: OutputSchema;
+    credentials?: readonly string[];
+    authProfile?: LibrettoWorkflowAuthProfile;
     recoveryAction?: RecoveryAction;
 };
 type LibrettoWorkflowOptions<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> = LibrettoWorkflowDefinition<InputSchema, OutputSchema> & {
@@ -32,11 +38,17 @@ declare class LibrettoWorkflow<InputSchema extends z.ZodType = z.ZodType<unknown
     readonly name: string;
     readonly inputSchema?: InputSchema;
     readonly outputSchema?: OutputSchema;
+    readonly credentialNames: readonly string[];
+    readonly authProfileName?: string;
+    readonly authProfileRefresh?: boolean;
     readonly recoveryAction?: RecoveryAction;
     private readonly handler;
     constructor(name: string, options: {
         inputSchema?: InputSchema;
         outputSchema?: OutputSchema;
+        credentialNames?: readonly string[];
+        authProfileName?: string;
+        authProfileRefresh?: boolean;
         recoveryAction?: RecoveryAction;
     } | undefined, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>);
     run(ctx: LibrettoWorkflowContext, input: unknown): Promise<z.infer<OutputSchema>>;
@@ -46,6 +58,9 @@ type ExportedLibrettoWorkflow = {
     readonly name: string;
     readonly inputSchema?: z.ZodType;
     readonly outputSchema?: z.ZodType;
+    readonly credentialNames: readonly string[];
+    readonly authProfileName?: string;
+    readonly authProfileRefresh?: boolean;
     readonly recoveryAction?: RecoveryAction;
     run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
@@ -58,4 +73,4 @@ declare function workflow<InputSchema extends z.ZodType = z.ZodType<unknown>, Ou
 declare function workflow<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>>(name: string, options: LibrettoWorkflowOptions<InputSchema, OutputSchema>): LibrettoWorkflow<InputSchema, OutputSchema>;
 declare function workflow<Input = unknown, Output = unknown>(name: string, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<z.ZodType<Input>, z.ZodType<Output>>;
 
-export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowDefinition, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowOptions, type WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow };
+export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowAuthProfile, type LibrettoWorkflowContext, type LibrettoWorkflowDefinition, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowOptions, type WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow };

package/dist/shared/workflow/workflow.js

@@ -1,6 +1,11 @@
 import {
   createRecoveryPage
 } from "../../runtime/recovery/page-fallbacks.js";
+import { normalizeProfileName } from "./auth-profile-name.js";
+import {
+  mergeCredentialsIntoInput,
+  normalizeCredentialNames
+} from "./credentials.js";
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
 class LibrettoWorkflowInputError extends Error {
   workflowName;
@@ -25,10 +30,34 @@ function formatZodErrorMessage(workflowName, zodError) {
 function parseWorkflowInput(workflowName, inputSchema, input) {
   if (!inputSchema) return input;
   const result = inputSchema.safeParse(input);
-  if (!result.success) {
-    throw new LibrettoWorkflowInputError(workflowName, result.error);
+  if (result.success) {
+    return reattachCredentialInput(result.data, input);
+  }
+  const stripped = stripCredentialInput(input);
+  if (stripped !== input) {
+    const strippedResult = inputSchema.safeParse(stripped);
+    if (strippedResult.success) {
+      return reattachCredentialInput(strippedResult.data, input);
+    }
   }
-  return result.data;
+  throw new LibrettoWorkflowInputError(workflowName, result.error);
+}
+function stripCredentialInput(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+  const { credentials: _credentials, ...rest } = input;
+  if (!("credentials" in input)) return input;
+  return rest;
+}
+function reattachCredentialInput(parsed, raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return parsed;
+  const rawRecord = raw;
+  const rawCredentials = rawRecord.credentials && typeof rawRecord.credentials === "object" ? rawRecord.credentials : void 0;
+  if (!rawCredentials) return parsed;
+  const parsedRecord = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? { ...parsed } : {};
+  return {
+    ...parsedRecord,
+    credentials: rawCredentials
+  };
 }
 function validateWorkflowInput(workflow2, input) {
   parseWorkflowInput(workflow2.name, workflow2.inputSchema, input);
@@ -44,17 +73,27 @@ class LibrettoWorkflow {
   // this schema to JSON Schema at build time and exposes it via
   // /v1/workflows/get so API consumers know the workflow's output shape.
   outputSchema;
+  credentialNames;
+  authProfileName;
+  authProfileRefresh;
   recoveryAction;
   handler;
   constructor(name, options, handler) {
     this.name = name;
     this.inputSchema = options?.inputSchema;
     this.outputSchema = options?.outputSchema;
+    this.credentialNames = options?.credentialNames ?? [];
+    this.authProfileName = options?.authProfileName;
+    this.authProfileRefresh = options?.authProfileRefresh;
     this.recoveryAction = options?.recoveryAction;
     this.handler = handler;
   }
   async run(ctx, input) {
-    const parsed = parseWorkflowInput(this.name, this.inputSchema, input);
+    const parsed = parseWorkflowInput(
+      this.name,
+      this.inputSchema,
+      mergeCredentialsIntoInput(input, this.credentialNames)
+    );
     const workflowContext = !this.recoveryAction ? ctx : {
       ...ctx,
       page: createRecoveryPage(ctx.page, {
@@ -113,9 +152,13 @@ function getWorkflowFromModuleExports(moduleExports, workflowName) {
   return null;
 }
 function getWorkflowConstructorOptions(options) {
+  const authProfile = normalizeWorkflowAuthProfile(options.authProfile);
   return {
     inputSchema: options.input,
     outputSchema: options.output,
+    credentialNames: normalizeCredentialNames(options.credentials),
+    authProfileName: authProfile?.name,
+    authProfileRefresh: authProfile?.refresh,
     recoveryAction: options.recoveryAction
   };
 }
@@ -141,6 +184,15 @@ function workflow(name, definitionOrHandler, maybeHandler) {
     maybeHandler
   );
 }
+function normalizeWorkflowAuthProfile(value) {
+  if (!value) return void 0;
+  if (typeof value === "string") return { name: normalizeProfileName(value) };
+  const name = normalizeProfileName(value.name);
+  return {
+    name,
+    ...value.refresh === void 0 ? {} : { refresh: value.refresh }
+  };
+}
 export {
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,

package/package.json

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

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.24"
+  version: "0.6.25"
 ---
 
 ## How Libretto Works
@@ -23,7 +23,7 @@ Full documentation is published at [libretto.sh](https://libretto.sh). Available
 - Fundamentals: [core concepts](https://libretto.sh/docs/understand-libretto/core-concepts), [how workflow generation works](https://libretto.sh/docs/understand-libretto/how-workflow-generation-works), [automation and bot detection](https://libretto.sh/docs/understand-libretto/automation-and-bot-detection), [website authentication](https://libretto.sh/docs/understand-libretto/website-authentication)
 - Workflow guides: [one-shot generation](https://libretto.sh/docs/guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/docs/guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/docs/guides/debugging-workflows), [convert to network requests](https://libretto.sh/docs/guides/convert-to-network-requests)
 - CLI reference: [open and connect](https://libretto.sh/docs/reference/cli/open-and-connect), [sessions](https://libretto.sh/docs/reference/cli/sessions), [profiles](https://libretto.sh/docs/reference/cli/profiles), [snapshot](https://libretto.sh/docs/reference/cli/snapshot), [exec](https://libretto.sh/docs/reference/cli/exec), [run and resume](https://libretto.sh/docs/reference/cli/run-and-resume), [session logs](https://libretto.sh/docs/reference/cli/session-logs), [pages](https://libretto.sh/docs/reference/cli/pages)
-- Library API: [workflow](https://libretto.sh/docs/reference/runtime/workflow), [AI extraction](https://libretto.sh/docs/reference/runtime/ai-extraction), [network requests](https://libretto.sh/docs/reference/runtime/network-requests), [file downloads](https://libretto.sh/docs/reference/runtime/file-downloads)
+- Library API: [workflow](https://libretto.sh/docs/reference/runtime/workflow), [network requests](https://libretto.sh/docs/reference/runtime/network-requests), [file downloads](https://libretto.sh/docs/reference/runtime/file-downloads)
 - Libretto Cloud Hosting: [overview](https://libretto.sh/docs/libretto-cloud-hosting/overview), [authentication](https://libretto.sh/docs/libretto-cloud-hosting/authentication), [deployments](https://libretto.sh/docs/libretto-cloud-hosting/deployments), [stealth](https://libretto.sh/docs/libretto-cloud-hosting/stealth)
 - Alternative providers: [overview](https://libretto.sh/docs/alternative-providers/overview), [Kernel](https://libretto.sh/docs/alternative-providers/kernel), [Browserbase](https://libretto.sh/docs/alternative-providers/browserbase), [Steel](https://libretto.sh/docs/alternative-providers/steel), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)
 
@@ -61,7 +61,7 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 - Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
 - Read and follow guidelines in `references/code-generation-rules.md` before generating or editing production workflow code.
 - Validation requires a successful clean `run` 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`, `--headless`, or `--auth-profile` 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`, `--headed`, or `--headless` flags the workflow needs.
 - 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.
@@ -164,7 +164,6 @@ npx libretto exec --session debug-example --page <page-id> "await page.url()"
 npx libretto run ./integration.ts --params '{"status":"open"}'
 npx libretto run ./integration.ts --read-only
 npx libretto run ./integration.ts --stay-open-on-success
-npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
 ### `resume`

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

@@ -1,29 +1,79 @@
 # Auth Profiles
 
-Use this reference only when the user explicitly asks to save or reuse local authenticated browser state.
+Use this reference when generating or maintaining workflows that need a logged-in website session.
 
 ## When to Use This
 
-- The site requires manual login.
-- The user is running workflows locally.
+- The user wants to persist authentication across runs.
+- The workflow should recover when saved login state is stale.
 
 ## Workflow
 
 - Open the site in headed mode.
 - Ask the user to log in manually.
-- Save the current session as a profile.
-- Reopen the site or run the workflow with that profile.
+- Save the current session as a named, site-scoped profile.
+- Run a workflow that declares the profile and includes fallback login logic.
 
 ## Commands
 
 ```bash
-npx libretto open https://app.example.com --headed
-npx libretto save app.example.com
-npx libretto run ./integration.ts --auth-profile app.example.com
+# Save scoped auth state from the current Libretto session.
+npx libretto save example-app --session login --sites app.example.com,auth.example.com
+
+# List or delete hosted auth profile names.
+npx libretto cloud profiles list
+npx libretto cloud profiles delete example-app
+```
+
+## Workflow Definition
+
+Use `authProfile` to reuse a named login profile: local runs load
+`.libretto/profiles/<name>.json`, while hosted runs use provider-native profiles
+that `libretto cloud deploy` registers by name without uploading local files.
+Use `{ name, refresh: true }` when successful runs should persist updated
+browser state back to the profile. Pair profile use with `librettoAuthenticate`
+so stale local or hosted sessions can fall back to login with declared
+credentials before the workflow continues.
+
+```typescript
+import { librettoAuthenticate, workflow } from "libretto";
+
+export default workflow("accountWorkflow", {
+  authProfile: {
+    name: "example-account",
+    refresh: true,
+  },
+  credentials: ["username", "password"],
+  async handler(ctx, input) {
+    const { page } = ctx;
+
+    await page.goto("https://app.example.com/dashboard");
+
+    await librettoAuthenticate(ctx, {
+      credentials: input.credentials,
+      validate: async ({ page }) =>
+        await page.getByRole("heading", { name: "Dashboard" })
+          .isVisible()
+          .catch(() => false),
+      fallback: async ({ page }, credentials) => {
+        await page.goto("https://app.example.com/login");
+        await page.getByLabel("Email").fill(credentials.username);
+        await page.getByLabel("Password").fill(credentials.password);
+        await page.getByRole("button", { name: "Sign in" }).click();
+        await page.getByRole("heading", { name: "Dashboard" }).waitFor();
+      },
+    });
+
+    // Continue with the signed-in workflow steps.
+  },
+});
 ```
 
 ## Notes
 
-- Profiles are local to the current machine.
-- Sessions can expire. If the profile stops working, repeat the login and save flow.
-- Keep auth profiles as a brief operational detail in the main skill, not a full workflow pattern.
+- Saving a profile captures cookies, localStorage, and IndexedDB only for the comma-separated `--sites` list.
+- If the user explicitly wants to import from Chrome, ask which Chrome/profile
+  to launch or attach to and get consent before attaching because disconnecting
+  can close or relaunch that Chrome window. Chrome may require copying the
+  selected profile to a temporary user-data directory before running
+  `npx libretto import-chrome-profiles example-app --cdp-url http://127.0.0.1:9222 --sites app.example.com`.

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

@@ -40,7 +40,7 @@ export default workflow("myWorkflow", {
 
 Key points:
 
-- `workflow(name, { input, output, recoveryAction, handler })` takes a unique workflow name, optional Zod input/output schemas, an optional recovery action, and the async handler. The handler's `input` parameter is inferred from the input schema — do not redeclare it with a separate `type Input = ...`.
+- `workflow(name, { input, output, credentials, authProfile, recoveryAction, handler })` takes a unique workflow name, optional Zod input/output schemas, optional declared credential names, an optional auth profile, an optional recovery action, and the async handler. The handler's `input` parameter is inferred from the input schema — do not redeclare it with a separate `type Input = ...`.
 - At run time, Libretto validates `input` against `inputSchema` before calling the handler. Invalid input throws a clear error listing each failing field; the workflow handler never sees malformed input.
 - `npx libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
 - `ctx` provides `session` and `page`. Use `console.log`/`console.warn`/`console.error` for logging — the runtime wraps these with structured metadata automatically.
@@ -49,6 +49,36 @@ Key points:
 - After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.
 - The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
+## Workflow Credentials And Auth Profiles
+
+Declare `credentials` for runtime secrets instead of putting them in the Zod input schema or `--params`. Only declared names are injected into `input.credentials`; local runs read matching `LIBRETTO_CLOUD_` variables from `.env`, and hosted runs read matching Libretto Cloud credentials. For example, `LIBRETTO_CLOUD_OPENAI_API_KEY` becomes `input.credentials.openai_api_key`.
+
+```typescript
+export default workflow("sentimentWorkflow", {
+  credentials: ["openai_api_key"],
+  input: z.object({
+    pageUrl: z.string().url(),
+  }),
+  output: z.object({
+    sentiment: z.string(),
+  }),
+  async handler(ctx, input) {
+    const apiKey = input.credentials.openai_api_key;
+    // Use apiKey for server-side API calls.
+    return { sentiment: "neutral" };
+  },
+});
+```
+
+For logged-in website workflows, unless the user says otherwise, generate both:
+
+- `authProfile: { name, refresh: true }`
+- `librettoAuthenticate(...)` fallback login logic using declared credentials such as `credentials: ["username", "password"]`
+
+After generating or validating a credentialed workflow, include the local `.env` variable names the user must set, and never print secret values.
+
+The fallback should validate the signed-in state, log in when validation fails, and validate again before continuing. Follow `references/auth-profiles.md` for profile naming, refresh behavior, hosted profile behavior, and the fallback-login pattern.
+
 ## Workflow Error Handling
 
 Do not add runtime recovery by default. Add `recoveryAction` only when exploration shows nondeterministic blockers such as popups, cookie banners, modals, or overlays.

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.24"
+  version: "0.6.25"
 ---
 
 ## How Libretto Read-Only Works