libretto 0.6.6 → 0.6.7

package/README.md

@@ -5,6 +5,12 @@
 [![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub Discussions](https://img.shields.io/github/discussions/saffron-health/libretto)](https://github.com/saffron-health/libretto/discussions)
+[![Discord](https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/NYrG56hVDt)
+
+- Website: [libretto.sh](https://libretto.sh)
+- Repository: [github.com/saffron-health/libretto](https://github.com/saffron-health/libretto)
+- Docs: [libretto.sh/docs](https://libretto.sh/docs)
+- Discord: [discord.gg/NYrG56hVDt](https://discord.gg/NYrG56hVDt)
 
 Libretto is a toolkit for building robust web integrations. It gives your coding agent a live browser and a token-efficient CLI to:
 
@@ -117,7 +123,7 @@ To inspect the current configuration without changing anything:
 npx libretto status
 ```
 
-Provider credentials are read from environment variables or a `.env` file at your project root: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex.
+Provider credentials are read from environment variables or a `.env` file at your **repository root** (next to your `.git` directory): `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex. Set `LIBRETTO_DISABLE_DOTENV=1` to skip `.env` loading.
 
 The `viewport` field sets the default browser viewport size. Both fields are optional.
 
@@ -137,7 +143,7 @@ Profiles save browser sessions (cookies, localStorage) so you can reuse authenti
 
 ## Community
 
-Have a question, idea, or want to share what you've built? Join the conversation on [GitHub Discussions](https://github.com/saffron-health/libretto/discussions).
+Have a question, idea, or want to share what you've built? Join the conversation on [Discord](https://discord.gg/NYrG56hVDt) for quick help or [GitHub Discussions](https://github.com/saffron-health/libretto/discussions) for longer-form threads.
 
 - **[Q&A](https://github.com/saffron-health/libretto/discussions/categories/q-a)** — Ask questions and get help
 - **[Ideas](https://github.com/saffron-health/libretto/discussions/categories/ideas)** — Suggest new features or improvements

package/README.template.md

@@ -3,6 +3,12 @@
 [![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub Discussions](https://img.shields.io/github/discussions/saffron-health/libretto)](https://github.com/saffron-health/libretto/discussions)
+[![Discord](https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/NYrG56hVDt)
+
+- Website: [libretto.sh](https://libretto.sh)
+- Repository: [github.com/saffron-health/libretto](https://github.com/saffron-health/libretto)
+- Docs: [libretto.sh/docs](https://libretto.sh/docs)
+- Discord: [discord.gg/NYrG56hVDt](https://discord.gg/NYrG56hVDt)
 
 Libretto is a toolkit for building robust web integrations. It gives your coding agent a live browser and a token-efficient CLI to:
 
@@ -115,7 +121,7 @@ To inspect the current configuration without changing anything:
 npx libretto status
 ```
 
-Provider credentials are read from environment variables or a `.env` file at your project root: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex.
+Provider credentials are read from environment variables or a `.env` file at your **repository root** (next to your `.git` directory): `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex. Set `LIBRETTO_DISABLE_DOTENV=1` to skip `.env` loading.
 
 The `viewport` field sets the default browser viewport size. Both fields are optional.
 
@@ -135,7 +141,7 @@ Profiles save browser sessions (cookies, localStorage) so you can reuse authenti
 
 ## Community
 
-Have a question, idea, or want to share what you've built? Join the conversation on [GitHub Discussions](https://github.com/saffron-health/libretto/discussions).
+Have a question, idea, or want to share what you've built? Join the conversation on [Discord](https://discord.gg/NYrG56hVDt) for quick help or [GitHub Discussions](https://github.com/saffron-health/libretto/discussions) for longer-form threads.
 
 - **[Q&A](https://github.com/saffron-health/libretto/discussions/categories/q-a)** — Ask questions and get help
 - **[Ideas](https://github.com/saffron-health/libretto/discussions/categories/ideas)** — Suggest new features or improvements

package/dist/cli/commands/setup.js

@@ -330,7 +330,7 @@ function copySkills() {
   const agentDirs = detectAgentDirs(REPO_ROOT);
   if (agentDirs.length === 0) {
     console.log(
-      "\n\u26A0 No .agents/ or .claude/ directory found. Libretto skills were not installed."
+      "\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 `npx libretto setup` to install skills:"

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

@@ -1,11 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
 import { readSnapshotModel } from "./config.js";
-import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
+import { LIBRETTO_CONFIG_PATH } from "./context.js";
 import {
   hasProviderCredentials,
   parseModel
 } from "./resolve-model.js";
+import { loadEnv } from "../../shared/env/load-env.js";
+import { parseDotEnvAssignment } from "../../shared/env/load-env.js";
 const DEFAULT_SNAPSHOT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
@@ -77,66 +77,6 @@ function missingProviderSnapshotMessage(selection) {
     "For more info, run `npx libretto setup`."
   ].join(" ");
 }
-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;
-  }
-}
-function loadSnapshotEnv() {
-  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return;
-  const envPathCandidates = [
-    join(REPO_ROOT, ".env"),
-    readWorktreeEnvPath()
-  ].filter((value) => Boolean(value));
-  const envPath = envPathCandidates.find((candidate) => existsSync(candidate));
-  if (!envPath) return;
-  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;
-    }
-  }
-}
-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: "" };
-  }
-  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) };
-    }
-    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 inferAutoSnapshotModel() {
   const providersInPriorityOrder = [
     "openai",
@@ -156,7 +96,7 @@ function inferAutoSnapshotModel() {
   return null;
 }
 function resolveSnapshotApiModel(snapshotModel = readSnapshotModel()) {
-  loadSnapshotEnv();
+  loadEnv();
   if (snapshotModel) {
     const { provider } = parseModel(snapshotModel);
     return {
@@ -193,7 +133,7 @@ function readSnapshotModelSafely(configPath) {
   }
 }
 function resolveAiSetupStatus(configPath = LIBRETTO_CONFIG_PATH) {
-  loadSnapshotEnv();
+  loadEnv();
   const result = readSnapshotModelSafely(configPath);
   if (!result.ok) {
     return { kind: "invalid-config", message: result.message };
@@ -240,7 +180,6 @@ export {
   DEFAULT_SNAPSHOT_MODELS,
   SnapshotApiUnavailableError,
   isSnapshotApiUnavailableError,
-  loadSnapshotEnv,
   parseDotEnvAssignment,
   resolveAiSetupStatus,
   resolveSnapshotApiModel,

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 });
   }

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,42 +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 eqIndex = line.indexOf("=");
-    if (eqIndex === -1) continue;
-    const key = line.slice(0, eqIndex).trim();
-    let value = line.slice(eqIndex + 1).trim();
-    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-      value = value.slice(1, -1);
+  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.6",
+  "version": "0.6.7",
   "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.4"
+  version: "0.6.7"
 ---
 
 ## How Libretto Works

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

package/src/cli/commands/setup.ts

@@ -431,7 +431,7 @@ function copySkills(): void {
 
   if (agentDirs.length === 0) {
     console.log(
-      "\n⚠ No .agents/ or .claude/ directory found. Libretto skills were not installed.",
+      "\n⚠️ No .agents/ or .claude/ directory found. Libretto skills were not installed.",
     );
     console.log(
       "  Create one of these directories in your repo root and rerun `npx libretto setup` to install skills:",

package/src/cli/core/ai-model.ts

@@ -1,12 +1,14 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
 import { readSnapshotModel } from "./config.js";
-import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
+import { LIBRETTO_CONFIG_PATH } from "./context.js";
 import {
   hasProviderCredentials,
   parseModel,
   type Provider,
 } from "./resolve-model.js";
+import { loadEnv } from "../../shared/env/load-env.js";
+
+// Re-export so existing consumers (e.g. tests) don't break.
+export { parseDotEnvAssignment } from "../../shared/env/load-env.js";
 
 // ── Default models ──────────────────────────────────────────────────────────
 
@@ -112,88 +114,6 @@ function missingProviderSnapshotMessage(
   ].join(" ");
 }
 
-// ── Dotenv loading ──────────────────────────────────────────────────────────
-
-function readWorktreeEnvPath(): string | null {
-  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;
-  }
-}
-
-export function loadSnapshotEnv(): void {
-  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return;
-
-  const envPathCandidates = [
-    join(REPO_ROOT, ".env"),
-    readWorktreeEnvPath(),
-  ].filter((value): value is string => Boolean(value));
-
-  const envPath = envPathCandidates.find((candidate) => existsSync(candidate));
-  if (!envPath) return;
-
-  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;
-    }
-  }
-}
-
-export function parseDotEnvAssignment(
-  line: string,
-): { key: string; value: string } | null {
-  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: "" };
-  }
-
-  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) };
-    }
-    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 };
-}
-
 // ── Model resolution ────────────────────────────────────────────────────────
 
 function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
@@ -227,7 +147,7 @@ function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
 export function resolveSnapshotApiModel(
   snapshotModel: string | null = readSnapshotModel(),
 ): SnapshotApiModelSelection | null {
-  loadSnapshotEnv();
+  loadEnv();
 
   if (snapshotModel) {
     const { provider } = parseModel(snapshotModel);
@@ -318,7 +238,7 @@ function readSnapshotModelSafely(
 export function resolveAiSetupStatus(
   configPath: string = LIBRETTO_CONFIG_PATH,
 ): AiSetupStatus {
-  loadSnapshotEnv();
+  loadEnv();
 
   const result = readSnapshotModelSafely(configPath);
 

package/src/cli/workers/run-integration-runtime.ts

@@ -4,7 +4,7 @@ import { mkdir, 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,
@@ -196,7 +196,7 @@ async function runIntegrationInternal(
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
 
-  const envPath = loadProjectEnv(absolutePath);
+  const envPath = loadEnv();
   if (envPath) {
     logger.info("loaded-env", { path: envPath });
   }

package/src/shared/env/load-env.ts

@@ -1,60 +1,91 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { resolveLibrettoRepoRoot } from "../paths/repo-root.js";
 
-/**
- * Walk up from `startDir` until a `.env` file is found.
- * Returns the full path to the `.env`, or `null` if the filesystem root is reached.
- */
-function findNearestEnv(startDir: string): string | null {
-  let dir = startDir;
-  while (true) {
-    const envPath = join(dir, ".env");
-    if (existsSync(envPath)) return envPath;
-    const parent = dirname(dir);
-    if (parent === dir) return null; // filesystem root
-    dir = parent;
+const REPO_ROOT = resolveLibrettoRepoRoot();
+
+export function parseDotEnvAssignment(
+  line: string,
+): { key: string; value: string } | null {
+  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: "" };
   }
-}
 
-/**
- * Parse a `.env` file into key-value pairs.
- * Handles KEY=VALUE, KEY="VALUE", KEY='VALUE', comments (#), and blank lines.
- * Does not support multiline values or variable interpolation.
- */
-function parseEnvFile(content: string): Record<string, string> {
-  const vars: Record<string, string> = {};
-  for (const raw of content.split("\n")) {
-    const line = raw.trim();
-    if (!line || line.startsWith("#")) continue;
-    const eqIndex = line.indexOf("=");
-    if (eqIndex === -1) continue;
-    const key = line.slice(0, eqIndex).trim();
-    let value = line.slice(eqIndex + 1).trim();
-    // Strip matching quotes
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -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) };
+  }
+
+  if (rawValue.startsWith("'")) {
+    const closeIdx = rawValue.indexOf("'", 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    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(): string | null {
+  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;
 }
 
 /**
- * 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.
  */
-export function loadProjectEnv(scriptPath: string): string | null {
-  const envPath = findNearestEnv(dirname(scriptPath));
+export function loadEnv(): string | null {
+  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return null;
+
+  const envPathCandidates = [
+    join(REPO_ROOT, ".env"),
+    readWorktreeEnvPath(),
+  ].filter((value): value is string => 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] === undefined) {
-      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;