libretto 0.6.7-experimental.0 → 0.6.8

package/dist/cli/core/browser.js

@@ -1,24 +1,13 @@
 import {
   chromium
 } from "playwright";
-import { openSync, existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { openSync, closeSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { spawn } from "node:child_process";
-import {
-  filterSemanticClasses,
-  INTERACTIVE_ROLE_NAMES,
-  INTERACTIVE_TAG_NAMES,
-  isObfuscatedClass,
-  TEST_ATTRIBUTE_NAMES,
-  TRUSTED_ATTRIBUTE_NAMES
-} from "../../shared/dom-semantics.js";
-import {
-  getSessionActionsLogPath,
-  getSessionNetworkLogPath,
-  PROFILES_DIR
-} from "./context.js";
+import { PROFILES_DIR } from "./context.js";
 import { readLibrettoConfig } from "./config.js";
 import {
   assertSessionAvailableForStart,
@@ -31,11 +20,10 @@ import {
   writeSessionState
 } from "./session.js";
 import { getCloudProviderApi } from "./providers/index.js";
-import { installSessionTelemetry } from "./session-telemetry.js";
 const CLOSE_WAIT_MS = 1500;
 const FORCE_CLOSE_WAIT_MS = 300;
 async function pickFreePort() {
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve, reject) => {
     const server = createServer();
     server.listen(0, "127.0.0.1", () => {
       const address = server.address();
@@ -44,7 +32,7 @@ async function pickFreePort() {
         return;
       }
       const port = address.port;
-      server.close(() => resolve2(port));
+      server.close(() => resolve(port));
     });
     server.on("error", reject);
   });
@@ -99,7 +87,7 @@ async function tryConnectToCDP(endpoint, logger, timeoutMs = 5e3) {
   try {
     const connectPromise = chromium.connectOverCDP(endpoint);
     const timeoutPromise = new Promise(
-      (resolve2) => setTimeout(() => resolve2(null), timeoutMs)
+      (resolve) => setTimeout(() => resolve(null), timeoutMs)
     );
     const browser = await Promise.race([connectPromise, timeoutPromise]);
     if (browser) {
@@ -313,8 +301,6 @@ async function runOpen(rawUrl, headed, session, logger, options) {
   assertSessionAvailableForStart(session, logger);
   const port = await pickFreePort();
   const runLogPath = logFileForSession(session);
-  const networkLogPath = getSessionNetworkLogPath(session);
-  const actionsLogPath = getSessionActionsLogPath(session);
   const browserMode = headed ? "headed" : "headless";
   const supportsSavedProfile = parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:";
   const domain = supportsSavedProfile ? normalizeDomain(parsedUrl) : void 0;
@@ -333,162 +319,31 @@ async function runOpen(rawUrl, headed, session, logger, options) {
     console.log(`Loading saved profile for ${domain}`);
   }
   console.log(`Launching ${browserMode} browser (session: ${session})...`);
-  const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const storageStateCode = useProfile ? `storageState: '${profilePath.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}',` : "";
-  const escapedLogPath = runLogPath.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const escapedNetworkLogPath = networkLogPath.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const escapedActionsLogPath = actionsLogPath.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const windowPositionArg = windowPosition ? `, '--window-position=${windowPosition.x},${windowPosition.y}'` : "";
-  const windowBoundsSetupCode = windowPosition ? `
-const requestedWindowBounds = { left: ${windowPosition.x}, top: ${windowPosition.y}, windowState: 'normal' };
-const pageCdp = await context.newCDPSession(page);
-let browserCdp;
-try {
-	const targetInfo = await pageCdp.send('Target.getTargetInfo');
-	const targetId = targetInfo?.targetInfo?.targetId;
-	browserCdp = await browser.newBrowserCDPSession();
-	const windowResult = await browserCdp.send(
-		'Browser.getWindowForTarget',
-		targetId ? { targetId } : {},
-	);
-	await browserCdp.send('Browser.setWindowBounds', {
-		windowId: windowResult.windowId,
-		bounds: requestedWindowBounds,
-	});
-	await new Promise((resolve) => setTimeout(resolve, 250));
-	const actualWindow = await browserCdp.send('Browser.getWindowBounds', {
-		windowId: windowResult.windowId,
-	});
-	childLog('info', 'window-bounds-set', {
-		windowId: windowResult.windowId,
-		requestedBounds: requestedWindowBounds,
-		actualBounds: actualWindow.bounds,
-	});
-} catch (error) {
-	childLog('warn', 'window-bounds-set-failed', {
-		requestedBounds: requestedWindowBounds,
-		message: error instanceof Error ? error.message : String(error),
-		stack: error instanceof Error ? error.stack : undefined,
-	});
-} finally {
-	await pageCdp.detach().catch(() => {});
-	if (browserCdp) {
-		await browserCdp.detach().catch(() => {});
-	}
-}
-` : "";
-  const launcherCode = `
-import { chromium } from 'playwright';
-import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-
-const LOG_FILE = '${escapedLogPath}';
-const NETWORK_LOG = '${escapedNetworkLogPath}';
-const ACTIONS_LOG = '${escapedActionsLogPath}';
-mkdirSync(dirname(NETWORK_LOG), { recursive: true });
-
-// tsx/esbuild may emit __name() wrappers in Function#toString output.
-	const __name = (target, value) =>
-		Object.defineProperty(target, 'name', { value, configurable: true });
-
-	const TEST_ATTRIBUTE_NAMES = ${JSON.stringify([...TEST_ATTRIBUTE_NAMES])};
-	const TRUSTED_ATTRIBUTE_NAMES = ${JSON.stringify([...TRUSTED_ATTRIBUTE_NAMES])};
-	const INTERACTIVE_TAG_NAMES = ${JSON.stringify([...INTERACTIVE_TAG_NAMES])};
-	const INTERACTIVE_ROLE_NAMES = ${JSON.stringify([...INTERACTIVE_ROLE_NAMES])};
-	const filterSemanticClasses = ${filterSemanticClasses.toString()};
-	const isObfuscatedClass = ${isObfuscatedClass.toString()};
-
-	${installSessionTelemetry.toString()}
-
-	function logAction(entry) {
-		appendFileSync(ACTIONS_LOG, JSON.stringify(entry) + '\\n');
-	}
-
-function logNetwork(entry) {
-	appendFileSync(NETWORK_LOG, JSON.stringify(entry) + '\\n');
-}
-
-function childLog(level, event, data = {}) {
-	try {
-		const entry = JSON.stringify({
-			timestamp: new Date().toISOString(),
-			id: Math.random().toString(36).slice(2, 10),
-			level,
-			scope: 'libretto.child',
-			event,
-			data,
-		});
-		appendFileSync(LOG_FILE, entry + '\\n');
-	} catch {}
-}
-
-const browser = await chromium.launch({
-	headless: ${!headed},
-	args: ['--disable-blink-features=AutomationControlled', '--remote-debugging-port=${port}', '--remote-debugging-address=127.0.0.1', '--no-focus-on-check'${windowPositionArg}],
-});
-
-browser.on('disconnected', () => {
-	childLog('warn', 'browser-disconnected', { port: ${port} });
-});
-
-const context = await browser.newContext({
-	${storageStateCode}
-	viewport: { width: ${viewport.width}, height: ${viewport.height} },
-	userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36',
-});
-
-const page = await context.newPage();
-${windowBoundsSetupCode}
-page.setDefaultTimeout(30000);
-page.setDefaultNavigationTimeout(45000);
-
-await installSessionTelemetry({
-	context,
-	initialPage: page,
-	includeUserDomActions: true,
-	logAction,
-	logNetwork,
-});
-
-
-await page.goto('${escapedUrl}');
-
-process.on('SIGTERM', async () => {
-	childLog('info', 'child-sigterm');
-	await browser.close();
-	process.exit(0);
-});
-
-process.on('SIGINT', async () => {
-	childLog('info', 'child-sigint');
-	await browser.close();
-	process.exit(0);
-});
-
-process.on('uncaughtException', (err) => {
-	childLog('error', 'uncaught-exception', { message: err.message, stack: err.stack });
-	process.exit(1);
-});
-
-process.on('unhandledRejection', (reason) => {
-	childLog('warn', 'unhandled-rejection', { reason: String(reason) });
-});
-
-process.on('exit', (code) => {
-	childLog('info', 'child-exit', { code, pid: process.pid, port: ${port} });
-});
-
-childLog('info', 'child-launched', { port: ${port}, pid: process.pid, session: '${session}' });
-
-await new Promise(() => {});
-`;
+  const daemonEntryPath = fileURLToPath(
+    new URL("./browser-daemon.js", import.meta.url)
+  );
+  const require2 = createRequire(import.meta.url);
+  const tsxImportPath = pathToFileURL(require2.resolve("tsx/esm")).href;
+  const daemonConfig = {
+    port,
+    url,
+    session,
+    headed,
+    viewport,
+    storageStatePath: useProfile ? profilePath : void 0,
+    windowPosition
+  };
   const childStderrFd = openSync(runLogPath, "a");
-  const child = spawn("node", ["--input-type=module", "-e", launcherCode], {
-    detached: true,
-    stdio: ["ignore", "ignore", childStderrFd],
-    cwd: resolve(dirname(fileURLToPath(import.meta.url)), "../../..")
-  });
+  const child = spawn(
+    process.execPath,
+    ["--import", tsxImportPath, daemonEntryPath, JSON.stringify(daemonConfig)],
+    {
+      detached: true,
+      stdio: ["ignore", "ignore", childStderrFd]
+    }
+  );
   child.unref();
+  closeSync(childStderrFd);
   logger.info("open-child-spawned", { pid: child.pid, port, session });
   let childSpawnError = null;
   let childEarlyExit = null;

package/dist/cli/core/config.js

@@ -54,7 +54,7 @@ ${detail}` : null,
       '  - "snapshotModel", "viewport", "windowPosition", and "sessionMode" are optional.',
       '  - "snapshotModel" 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 openai | anthropic | gemini | vertex`
+      `  npx libretto ai configure openai | anthropic | gemini | vertex | openrouter`
     ].filter(Boolean).join("\n")
   );
 }

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

@@ -21,7 +21,9 @@ function createLibrettoCloudProvider() {
           "x-api-key": apiKey,
           "Content-Type": "application/json"
         },
-        body: JSON.stringify({ timeout_seconds: timeoutSeconds })
+        body: JSON.stringify({
+          json: { timeout_seconds: timeoutSeconds }
+        })
       });
       if (!resp.ok) {
         const body = await resp.text();
@@ -29,7 +31,7 @@ function createLibrettoCloudProvider() {
           `Libretto Cloud API error (${resp.status}): ${body}`
         );
       }
-      const json = await resp.json();
+      const { json } = await resp.json();
       return {
         sessionId: json.session_id,
         cdpEndpoint: json.cdp_url
@@ -42,7 +44,7 @@ function createLibrettoCloudProvider() {
           "x-api-key": apiKey,
           "Content-Type": "application/json"
         },
-        body: JSON.stringify({ session_id: sessionId })
+        body: JSON.stringify({ json: { session_id: sessionId } })
       });
       if (!resp.ok) {
         const body = await resp.text();

package/dist/cli/core/resolve-model.js

@@ -12,7 +12,8 @@ const SUPPORTED_PROVIDER_ALIASES = {
   vertex: "vertex",
   anthropic: "anthropic",
   codex: "openai",
-  openai: "openai"
+  openai: "openai",
+  openrouter: "openrouter"
 };
 function readFirstEnvValue(env, names) {
   for (const name of names) {
@@ -33,7 +34,7 @@ function parseModel(model) {
   const modelId = model.slice(slashIndex + 1);
   if (!provider) {
     throw new Error(
-      `Unsupported provider "${providerInput}". Supported providers: openai/codex, anthropic, google (Gemini API), and vertex.`
+      `Unsupported provider "${providerInput}". Supported providers: openai/codex, anthropic, google (Gemini API), vertex, and openrouter.`
     );
   }
   return { provider, modelId };
@@ -48,6 +49,8 @@ function hasProviderCredentials(provider, env = process.env) {
       return Boolean(env.ANTHROPIC_API_KEY?.trim());
     case "openai":
       return Boolean(env.OPENAI_API_KEY?.trim());
+    case "openrouter":
+      return Boolean(env.OPENROUTER_API_KEY?.trim());
   }
 }
 function missingProviderCredentialsMessage(provider) {
@@ -62,6 +65,9 @@ function missingProviderCredentialsMessage(provider) {
     case "openai": {
       return "OpenAI API key is missing. Set OPENAI_API_KEY.";
     }
+    case "openrouter": {
+      return "OpenRouter API key is missing. Set OPENROUTER_API_KEY.";
+    }
   }
 }
 async function getProviderModel(provider, modelId) {
@@ -105,6 +111,18 @@ async function getProviderModel(provider, modelId) {
       const openai = createOpenAI({ apiKey });
       return openai(modelId);
     }
+    case "openrouter": {
+      const apiKey = process.env.OPENROUTER_API_KEY?.trim();
+      if (!apiKey) {
+        throw new Error(missingProviderCredentialsMessage(provider));
+      }
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      const openrouter = createOpenAI({
+        apiKey,
+        baseURL: "https://openrouter.ai/api/v1"
+      });
+      return openrouter(modelId);
+    }
   }
 }
 async function resolveModel(model) {

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

@@ -3,7 +3,7 @@ import { writeFile } from "node:fs/promises";
 import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { loadProjectEnv } from "../../shared/env/load-env.js";
+import { loadEnv } from "../../shared/env/load-env.js";
 import {
   getDefaultWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
@@ -127,7 +127,7 @@ async function installHeadedWorkflowVisualization(args) {
 async function runIntegrationInternal(args, options) {
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
-  const envPath = loadProjectEnv(absolutePath);
+  const envPath = loadEnv();
   if (envPath) {
     logger.info("loaded-env", { path: envPath });
   }
@@ -186,6 +186,9 @@ async function runIntegrationInternal(args, options) {
       appendFileSync(networkLogPath, JSON.stringify(entry) + "\n");
     }
   });
+  await browserSession.context.addInitScript(() => {
+    globalThis.__name = (target, value) => Object.defineProperty(target, "name", { value, configurable: true });
+  });
   const workflowContext = {
     session: args.session,
     page: browserSession.page

package/dist/shared/dom-semantics.js

@@ -53,7 +53,6 @@ function isObfuscatedClass(cls) {
   if (cls.length > 80) return true;
   if (/^_?[0-9a-f]{6,}$/i.test(cls)) return true;
   if (/^[a-z]+_[0-9a-f]{4,}$/i.test(cls)) return true;
-  if (/^[a-z]{1,2}[0-9]{2,}$/i.test(cls)) return true;
   const digits = (cls.match(/[0-9]/g) || []).length;
   const letters = (cls.match(/[a-zA-Z]/g) || []).length;
   if (cls.length >= 6 && digits >= letters * 0.5 && digits >= 2) return true;

package/dist/shared/env/load-env.d.ts

@@ -1,8 +1,13 @@
+declare function parseDotEnvAssignment(line: string): {
+    key: string;
+    value: string;
+} | null;
 /**
- * Load the nearest `.env` file above `scriptPath`.
- * Existing `process.env` values are never overridden.
+ * Load the `.env` file at the repository root into `process.env`.
+ * Existing values are never overridden.
+ * Respects `LIBRETTO_DISABLE_DOTENV=1` to skip loading entirely.
  * Returns the path of the loaded `.env`, or `null` if none was found.
  */
-declare function loadProjectEnv(scriptPath: string): string | null;
+declare function loadEnv(): string | null;
 
-export { loadProjectEnv };
+export { loadEnv, parseDotEnvAssignment };

package/dist/shared/env/load-env.js

@@ -1,48 +1,69 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-function findNearestEnv(startDir) {
-  let dir = startDir;
-  while (true) {
-    const envPath = join(dir, ".env");
-    if (existsSync(envPath)) return envPath;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
+import { dirname, join, resolve } from "node:path";
+import { resolveLibrettoRepoRoot } from "../paths/repo-root.js";
+const REPO_ROOT = resolveLibrettoRepoRoot();
+function parseDotEnvAssignment(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  const withoutExport = trimmed.startsWith("export ") ? trimmed.slice("export ".length).trimStart() : trimmed;
+  const eqIdx = withoutExport.indexOf("=");
+  if (eqIdx < 1) return null;
+  const key = withoutExport.slice(0, eqIdx).trim();
+  if (!key) return null;
+  const rawValue = withoutExport.slice(eqIdx + 1).trimStart();
+  if (!rawValue) {
+    return { key, value: "" };
   }
-}
-function parseEnvFile(content) {
-  const vars = {};
-  for (const raw of content.split("\n")) {
-    const line = raw.trim();
-    if (!line || line.startsWith("#")) continue;
-    const withoutExport = line.startsWith("export ") ? line.slice("export ".length).trimStart() : line;
-    const eqIndex = withoutExport.indexOf("=");
-    if (eqIndex === -1) continue;
-    const key = withoutExport.slice(0, eqIndex).trim();
-    let value = withoutExport.slice(eqIndex + 1).trim();
-    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-      value = value.slice(1, -1);
-    } else {
-      const commentIndex = value.search(/\s#/);
-      if (commentIndex >= 0) {
-        value = value.slice(0, commentIndex).trimEnd();
-      }
+  if (rawValue.startsWith('"')) {
+    const closeIdx = rawValue.indexOf('"', 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    return { key, value: rawValue.slice(1) };
+  }
+  if (rawValue.startsWith("'")) {
+    const closeIdx = rawValue.indexOf("'", 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
     }
-    vars[key] = value;
+    return { key, value: rawValue.slice(1) };
+  }
+  const inlineCommentIndex = rawValue.search(/\s#/);
+  const value = inlineCommentIndex >= 0 ? rawValue.slice(0, inlineCommentIndex).trimEnd() : rawValue.trim();
+  return { key, value };
+}
+function readWorktreeEnvPath() {
+  const gitPath = join(REPO_ROOT, ".git");
+  if (!existsSync(gitPath)) return null;
+  try {
+    const gitPointer = readFileSync(gitPath, "utf-8").trim();
+    const match = gitPointer.match(/^gitdir:\s*(.+)$/i);
+    if (!match?.[1]) return null;
+    const worktreeGitDir = resolve(REPO_ROOT, match[1].trim());
+    const commonGitDir = resolve(worktreeGitDir, "..", "..");
+    return join(dirname(commonGitDir), ".env");
+  } catch {
+    return null;
   }
-  return vars;
 }
-function loadProjectEnv(scriptPath) {
-  const envPath = findNearestEnv(dirname(scriptPath));
+function loadEnv() {
+  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return null;
+  const envPathCandidates = [
+    join(REPO_ROOT, ".env"),
+    readWorktreeEnvPath()
+  ].filter((value) => Boolean(value));
+  const envPath = envPathCandidates.find((candidate) => existsSync(candidate));
   if (!envPath) return null;
-  const vars = parseEnvFile(readFileSync(envPath, "utf8"));
-  for (const [key, value] of Object.entries(vars)) {
-    if (process.env[key] === void 0) {
-      process.env[key] = value;
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const parsed = parseDotEnvAssignment(line);
+    if (!parsed) continue;
+    if (!(parsed.key in process.env)) {
+      process.env[parsed.key] = parsed.value;
     }
   }
   return envPath;
 }
 export {
-  loadProjectEnv
+  loadEnv,
+  parseDotEnvAssignment
 };

package/package.json

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

package/scripts/generate-changelog.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { Agent, type AgentTool, type AgentEvent } from "@mariozechner/pi-agent-core";
 import { getModel } from "@mariozechner/pi-ai";
-import { Type } from "@sinclair/typebox";
+import { Type, type Static } from "@sinclair/typebox";
 
 const tag = process.argv[2];
 if (!tag) {
@@ -17,6 +17,11 @@ if (!process.env.ANTHROPIC_API_KEY) {
 
 const ALLOWED_GH_SUBCOMMANDS = new Set(["pr", "release", "repo", "issue"]);
 const ALLOWED_ACTIONS = new Set(["list", "view", "diff", "status", "checks"]);
+const GhToolParamsSchema = Type.Object({
+  args: Type.String({ description: "Arguments to pass to gh (without the leading 'gh')" }),
+});
+
+type GhToolParams = Static<typeof GhToolParamsSchema>;
 
 const ghTool: AgentTool = {
   name: "gh",
@@ -27,11 +32,9 @@ const ghTool: AgentTool = {
     "'pr view 128 --json title,body,files', 'pr diff 128'.",
     "Only read operations are allowed (list, view, diff, etc.). Mutating commands will be rejected.",
   ].join(" "),
-  parameters: Type.Object({
-    args: Type.String({ description: "Arguments to pass to gh (without the leading 'gh')" }),
-  }),
-  execute: async (_toolCallId, rawParams) => {
-    const params = rawParams as { args: string };
+  parameters: GhToolParamsSchema,
+  execute: async (_toolCallId: string, rawParams: unknown) => {
+    const params = rawParams as GhToolParams;
     const args = params.args.trim();
     const parts = args.split(/\s+/);
     const subcommand = parts[0];

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.6"
+  version: "0.6.8"
 ---
 
 ## How Libretto Works
@@ -34,6 +34,7 @@ metadata:
 - 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 --headless` with confirmation of the actual returned output, not just process success. If the user wants to watch the finished workflow, do a final headed `run` after headless validation succeeds.
+- After validation, always show the user: (1) the output/results from the headless validation run, and (2) a headed version of the same command so they can re-run it themselves and watch the browser (e.g. replace `--headless` with `--headed`). Include any `--params` or `--auth-profile` 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.
@@ -214,7 +215,12 @@ Assistant: [Reads `references/site-security-review.md` before choosing between p
 Assistant: [Runs `npx libretto snapshot --objective "Find the next required action" --context "We are starting the workflow from the landing page and need the first meaningful step."`]
 Assistant: [Uses `snapshot` and `exec` as needed to understand the site and decide the implementation path]
 Assistant: [Reads `references/code-generation-rules.md` before writing production workflow code]
-Assistant: I found the working path. I'll now update the workflow file outside Libretto and verify it with `npx libretto run ...`.
+Assistant: I found the working path. I'll now create the workflow file and verify it.
+Assistant: [Creates or edits `target-workflow.ts` following `references/code-generation-rules.md`]
+Assistant: [Runs `npx libretto run ./target-workflow.ts --headless --params '{"status":"open"}'` to validate]
+Assistant: Validation passed. Here are the results:
+[Shows the output/results from the headless run]
+To watch it yourself in a browser, run: npx libretto run ./target-workflow.ts --headed --params '{"status":"open"}'
 </example>
 ```
 
@@ -229,7 +235,12 @@ Assistant: The workflow failed and Libretto kept the browser open. I'll inspect
 Assistant: [Runs `npx libretto snapshot --session debug-flow --objective "Find the blocking error or broken selector target" --context "The workflow just failed after trying to continue from the review step, and I need to identify the visible blocker on the current page."`]
 Assistant: [Runs `npx libretto exec --session debug-flow "...focused inspection or prototype..."`]
 Assistant: [Reads `references/code-generation-rules.md` before patching the workflow file]
-Assistant: I found the issue. I'll patch the workflow code, then rerun `npx libretto run ...` to verify the fix.
+Assistant: I found the issue. I'll patch the workflow code and verify.
+Assistant: [Edits `integration.ts` following `references/code-generation-rules.md`]
+Assistant: [Runs `npx libretto run ./integration.ts --headless` to validate the fix]
+Assistant: Fix verified. Here are the results:
+[Shows the output/results from the headless run]
+To watch it yourself in a browser, run: npx libretto run ./integration.ts --headed
 </example>
 ```
 

package/skills/libretto/references/configuration-file-reference.md

@@ -13,7 +13,7 @@ Use this reference when you need to inspect or change the workspace configuratio
 Libretto reads workspace config from `.libretto/config.json`.
 
 - The file is created by `npx libretto setup` during first-time onboarding (auto-pins the default model for the detected provider) or by `npx libretto ai configure ...` for explicit overrides.
-- API credentials still come from your shell environment or `.env`. The config file stores the selected model, not the secret itself.
+- API credentials come from your shell environment or a `.env` file **at the repository root** (next to your `.git` directory). The config file stores the selected model, not the secret itself. Set `LIBRETTO_DISABLE_DOTENV=1` to skip `.env` loading (useful in CI).
 - Use `npx libretto status` to inspect the current AI configuration and open sessions without changing anything.
 - For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
 

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