libretto 0.6.3 → 0.6.5

package/dist/cli/cli.js

@@ -16,7 +16,7 @@ function printSetupAudit() {
   const status = resolveAiSetupStatus();
   switch (status.kind) {
     case "ready":
-      console.log(`\u2713 AI model: ${status.model}`);
+      console.log(`\u2713 Snapshot model: ${status.model}`);
       break;
     case "configured-missing-credentials":
       console.log(

package/dist/cli/commands/ai.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import {
-  readAiConfig,
-  writeAiConfig,
-  clearAiConfig
+  readSnapshotModel,
+  writeSnapshotModel,
+  clearSnapshotModel
 } from "../core/config.js";
 import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
 import { DEFAULT_SNAPSHOT_MODELS } from "../core/ai-model.js";
@@ -21,10 +21,9 @@ const CONFIGURE_PROVIDERS = [
 function formatConfigureProviders(separator = " | ") {
   return CONFIGURE_PROVIDERS.join(separator);
 }
-function printAiConfig(config, configPath) {
-  console.log(`Model: ${config.model}`);
+function printSnapshotModelConfig(model, configPath) {
+  console.log(`Snapshot model: ${model}`);
   console.log(`Config file: ${configPath}`);
-  console.log(`Updated at: ${config.updatedAt}`);
 }
 function resolveModelFromInput(input) {
   const trimmed = input.trim();
@@ -38,25 +37,25 @@ function runAiConfigure(input, options = {}) {
   const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
   const presetArg = input.preset?.trim();
   if (!presetArg && !input.clear) {
-    const config2 = readAiConfig(configPath);
-    if (!config2) {
+    const model2 = readSnapshotModel(configPath);
+    if (!model2) {
       console.log(
-        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`
+        `No snapshot model set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`
       );
       console.log(
         "Provider credentials still come from your shell or .env file."
       );
       return;
     }
-    printAiConfig(config2, configPath);
+    printSnapshotModelConfig(model2, configPath);
     return;
   }
   if (input.clear) {
-    const removed = clearAiConfig(configPath);
+    const removed = clearSnapshotModel(configPath);
     if (removed) {
-      console.log(`Cleared AI config: ${configPath}`);
+      console.log(`Cleared snapshot model config: ${configPath}`);
     } else {
-      console.log("No AI config was set.");
+      console.log("No snapshot model was set.");
     }
     return;
   }
@@ -71,9 +70,9 @@ function runAiConfigure(input, options = {}) {
       `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`
     );
   }
-  const config = writeAiConfig(model, configPath);
-  console.log("AI config saved.");
-  printAiConfig(config, configPath);
+  writeSnapshotModel(model, configPath);
+  console.log("Snapshot model saved.");
+  printSnapshotModelConfig(model, configPath);
 }
 const aiConfigureInput = SimpleCLI.input({
   positionals: [

package/dist/cli/commands/setup.js

@@ -1,17 +1,14 @@
 import { createInterface } from "node:readline";
 import {
-  appendFileSync,
   cpSync,
   existsSync,
   readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync
+  rmSync
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { writeAiConfig } from "../core/config.js";
+import { writeSnapshotModel } from "../core/config.js";
 import {
   ensureLibrettoSetup,
   LIBRETTO_CONFIG_PATH,
@@ -19,10 +16,64 @@ import {
 } from "../core/context.js";
 import {
   DEFAULT_SNAPSHOT_MODELS,
-  loadSnapshotEnv,
   resolveAiSetupStatus
 } from "../core/ai-model.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
+const PROVIDER_SDK_PACKAGES = {
+  openai: "@ai-sdk/openai",
+  anthropic: "@ai-sdk/anthropic",
+  google: "@ai-sdk/google",
+  vertex: "@ai-sdk/google-vertex"
+};
+function detectPackageManager() {
+  if (existsSync(join(REPO_ROOT, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(REPO_ROOT, "yarn.lock"))) return "yarn";
+  if (existsSync(join(REPO_ROOT, "bun.lockb"))) return "bun";
+  return "npm";
+}
+function installCommand(pkgManager) {
+  switch (pkgManager) {
+    case "yarn":
+      return "yarn add";
+    case "bun":
+      return "bun add";
+    case "pnpm":
+      return "pnpm add";
+    default:
+      return "npm install";
+  }
+}
+function isSdkInstalled(sdkPackage) {
+  try {
+    const result = spawnSync("node", ["-e", `require.resolve("${sdkPackage}")`], {
+      cwd: REPO_ROOT,
+      stdio: "pipe"
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function installSdkIfNeeded(provider) {
+  const sdkPackage = PROVIDER_SDK_PACKAGES[provider];
+  if (isSdkInstalled(sdkPackage)) return;
+  const pkgManager = detectPackageManager();
+  const cmd = installCommand(pkgManager);
+  console.log(`
+Installing ${sdkPackage}...`);
+  const result = spawnSync(cmd, [sdkPackage], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.status === 0) {
+    console.log(`\u2713 Installed ${sdkPackage}`);
+  } else {
+    console.error(
+      `\u2717 Failed to install ${sdkPackage}. Install it manually: ${cmd} ${sdkPackage}`
+    );
+  }
+}
 const PROVIDER_CHOICES = [
   {
     key: "1",
@@ -70,7 +121,7 @@ function sourceEnvVar(source) {
 }
 function ensurePinnedDefaultModel(status) {
   if (status.source !== "config") {
-    writeAiConfig(status.model);
+    writeSnapshotModel(status.model);
     return { ...status, source: "config" };
   }
   return status;
@@ -103,7 +154,7 @@ function buildRepairPlan(status) {
       provider: status.provider,
       model: status.model,
       envVar: choice?.envVar ?? `${status.provider.toUpperCase()}_API_KEY`,
-      choices: ["enter-matching-credential", "switch-provider", "skip"]
+      choices: ["switch-provider", "skip"]
     };
   }
   if (status.kind === "invalid-config") {
@@ -156,50 +207,7 @@ function printSnapshotApiStatus() {
   );
   return false;
 }
-function writeEnvVar(envVar, value, envPath) {
-  let envContent = "";
-  if (existsSync(envPath)) {
-    envContent = readFileSync(envPath, "utf-8");
-  }
-  const envLine = `${envVar}=${value}`;
-  if (envContent.includes(`${envVar}=`)) {
-    const updated = envContent.replace(
-      new RegExp(`^${envVar}=.*$`, "m"),
-      () => envLine
-    );
-    writeFileSync(envPath, updated);
-    console.log(`
-\u2713 Updated ${envVar} in ${envPath}`);
-  } else {
-    const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
-    appendFileSync(envPath, `${separator}${envLine}
-`);
-    console.log(`
-\u2713 Added ${envVar} to ${envPath}`);
-  }
-  process.env[envVar] = value;
-}
-async function promptForCredential(rl, choice, envPath, modelOverride) {
-  console.log(`
-${choice.label} selected.`);
-  console.log(`${choice.envHint}
-`);
-  const apiKeyValue = await promptUser(rl, `Enter your ${choice.envVar}: `);
-  if (!apiKeyValue) {
-    console.log("\nNo value entered. Skipping API key setup.");
-    return false;
-  }
-  writeEnvVar(choice.envVar, apiKeyValue, envPath);
-  loadSnapshotEnv();
-  const model = modelOverride ?? DEFAULT_SNAPSHOT_MODELS[choice.provider];
-  writeAiConfig(model);
-  console.log(`\u2713 Snapshot API ready: ${model}`);
-  console.log(
-    "To change: npx libretto ai configure openai | anthropic | gemini | vertex"
-  );
-  return true;
-}
-async function promptProviderSelection(rl, envPath) {
+async function promptProviderSelection(rl) {
   console.log(
     "Which model provider would you like to use for snapshot analysis?\n"
   );
@@ -218,7 +226,15 @@ async function promptProviderSelection(rl, envPath) {
 Unknown choice "${answer}". Skipping API setup.`);
     return false;
   }
-  return promptForCredential(rl, selected, envPath);
+  const model = DEFAULT_SNAPSHOT_MODELS[selected.provider];
+  writeSnapshotModel(model);
+  console.log(`
+\u2713 ${selected.label} selected (model: ${model}).`);
+  console.log(`
+Add ${selected.envVar} to your .env file:`);
+  console.log(`  ${selected.envHint}`);
+  installSdkIfNeeded(selected.provider);
+  return true;
 }
 function printSkipMessage() {
   console.log(
@@ -234,7 +250,6 @@ function printSkipMessage() {
 }
 async function runInteractiveApiSetup() {
   const status = resolveAiSetupStatus();
-  const envPath = join(REPO_ROOT, ".env");
   console.log(
     "\nLibretto uses a sub-agent to analyze DOM snapshots. The model is determined by environment variables."
   );
@@ -252,23 +267,15 @@ async function runInteractiveApiSetup() {
   try {
     if (plan.kind === "repair-missing-credentials") {
       console.log(formatMissingCredentialsMessage(plan));
+      console.log(`
+Add ${plan.envVar} to your .env file to fix this.`);
       console.log("");
-      console.log("How would you like to fix this?\n");
-      console.log(`  1) Enter ${plan.envVar}`);
-      console.log("  2) Switch to a different provider");
+      console.log("Or switch to a different provider:\n");
+      console.log("  1) Switch to a different provider");
       console.log("  s) Skip for now\n");
       const answer = await promptUser(rl, "Choice: ");
       if (answer === "1") {
-        const matchingChoice = PROVIDER_CHOICES.find(
-          (c) => c.provider === plan.provider
-        );
-        if (matchingChoice) {
-          await promptForCredential(rl, matchingChoice, envPath, plan.model);
-        }
-        return;
-      }
-      if (answer === "2") {
-        await promptProviderSelection(rl, envPath);
+        await promptProviderSelection(rl);
         return;
       }
       printSkipMessage();
@@ -279,11 +286,11 @@ async function runInteractiveApiSetup() {
       console.log(
         "\nWould you like to reconfigure with a fresh provider selection?\n"
       );
-      await promptProviderSelection(rl, envPath);
+      await promptProviderSelection(rl);
       return;
     }
     console.log("\u2717 No snapshot API credentials detected.\n");
-    await promptProviderSelection(rl, envPath);
+    await promptProviderSelection(rl);
   } finally {
     rl.close();
   }
@@ -322,6 +329,13 @@ function detectAgentDirs(root) {
 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."
+    );
+    console.log(
+      "  Create one of these directories in your repo root and rerun `npx libretto setup` to install skills:"
+    );
+    console.log(`    mkdir ${join(REPO_ROOT, ".claude")}`);
     return;
   }
   let skillsRoot;

package/dist/cli/commands/snapshot.js

@@ -7,7 +7,7 @@ import { readSessionState } from "../core/session.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
 import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
-import { readAiConfig } from "../core/config.js";
+import { readSnapshotModel } from "../core/config.js";
 import { resolveSnapshotApiModelOrThrow } from "../core/ai-model.js";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
@@ -187,8 +187,8 @@ async function captureScreenshot(session, logger, pageId) {
 async function runSnapshot(session, logger, pageId, objective, context) {
   const normalizedObjective = objective.trim();
   const normalizedContext = context.trim();
-  const configuredAi = readAiConfig();
-  resolveSnapshotApiModelOrThrow(configuredAi);
+  const snapshotModel = readSnapshotModel();
+  resolveSnapshotApiModelOrThrow(snapshotModel);
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
     logger,
@@ -206,7 +206,7 @@ async function runSnapshot(session, logger, pageId, objective, context) {
     htmlPath,
     condensedHtmlPath
   };
-  await runApiInterpret(interpretArgs, logger, configuredAi);
+  await runApiInterpret(interpretArgs, logger, snapshotModel);
 }
 const snapshotInput = SimpleCLI.input({
   positionals: [],

package/dist/cli/commands/status.js

@@ -6,7 +6,7 @@ function printAiStatus(status) {
   console.log("AI configuration:");
   switch (status.kind) {
     case "ready":
-      console.log(`  \u2713 Model: ${status.model}`);
+      console.log(`  \u2713 Snapshot model: ${status.model}`);
       if (status.source === "config") {
         console.log(`  Config: ${LIBRETTO_CONFIG_PATH}`);
       } else {

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

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { readAiConfig } from "./config.js";
+import { readSnapshotModel } from "./config.js";
 import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
@@ -155,20 +155,20 @@ function inferAutoSnapshotModel() {
   }
   return null;
 }
-function resolveSnapshotApiModel(config = readAiConfig()) {
+function resolveSnapshotApiModel(snapshotModel = readSnapshotModel()) {
   loadSnapshotEnv();
-  if (config?.model) {
-    const { provider } = parseModel(config.model);
+  if (snapshotModel) {
+    const { provider } = parseModel(snapshotModel);
     return {
-      model: config.model,
+      model: snapshotModel,
       provider,
       source: "config"
     };
   }
   return inferAutoSnapshotModel();
 }
-function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
-  const selection = resolveSnapshotApiModel(config);
+function resolveSnapshotApiModelOrThrow(snapshotModel = readSnapshotModel()) {
+  const selection = resolveSnapshotApiModel(snapshotModel);
   if (!selection) {
     throw new SnapshotApiUnavailableError(noSnapshotApiConfiguredMessage());
   }
@@ -182,9 +182,9 @@ function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
 function isSnapshotApiUnavailableError(error) {
   return error instanceof SnapshotApiUnavailableError;
 }
-function readAiConfigSafely(configPath) {
+function readSnapshotModelSafely(configPath) {
   try {
-    return { ok: true, config: readAiConfig(configPath) };
+    return { ok: true, model: readSnapshotModel(configPath) };
   } catch (err) {
     return {
       ok: false,
@@ -194,14 +194,14 @@ function readAiConfigSafely(configPath) {
 }
 function resolveAiSetupStatus(configPath = LIBRETTO_CONFIG_PATH) {
   loadSnapshotEnv();
-  const configResult = readAiConfigSafely(configPath);
-  if (!configResult.ok) {
-    return { kind: "invalid-config", message: configResult.message };
+  const result = readSnapshotModelSafely(configPath);
+  if (!result.ok) {
+    return { kind: "invalid-config", message: result.message };
   }
-  if (configResult.config) {
+  if (result.model) {
     let selection;
     try {
-      selection = resolveSnapshotApiModel(configResult.config);
+      selection = resolveSnapshotApiModel(result.model);
     } catch (err) {
       return {
         kind: "invalid-config",

package/dist/cli/core/api-snapshot-analyzer.js

@@ -7,10 +7,10 @@ import {
   getMimeType,
   readFileAsBase64
 } from "./snapshot-analyzer.js";
-import { readAiConfig } from "./config.js";
+import { readSnapshotModel } from "./config.js";
 import { resolveSnapshotApiModelOrThrow } from "./ai-model.js";
-async function runApiInterpret(args, logger, configuredAi = readAiConfig()) {
-  const selection = resolveSnapshotApiModelOrThrow(configuredAi);
+async function runApiInterpret(args, logger, snapshotModel = readSnapshotModel()) {
+  const selection = resolveSnapshotApiModelOrThrow(snapshotModel);
   logger.info("api-interpret-start", {
     objective: args.objective,
     pngPath: args.pngPath,

package/dist/cli/core/config.js

@@ -4,10 +4,6 @@ import { z } from "zod";
 import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import { LIBRETTO_CONFIG_PATH } from "./context.js";
 const CURRENT_CONFIG_VERSION = 1;
-const AiConfigSchema = z.object({
-  model: z.string().min(1),
-  updatedAt: z.string()
-});
 const ViewportConfigSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
@@ -18,7 +14,7 @@ const WindowPositionConfigSchema = z.object({
 });
 const LibrettoConfigSchema = z.object({
   version: z.literal(CURRENT_CONFIG_VERSION),
-  ai: AiConfigSchema.optional(),
+  snapshotModel: z.string().min(1).optional(),
   viewport: ViewportConfigSchema.optional(),
   windowPosition: WindowPositionConfigSchema.optional(),
   provider: z.string().optional(),
@@ -31,10 +27,7 @@ function formatExpectedConfigExample() {
   return JSON.stringify(
     {
       version: CURRENT_CONFIG_VERSION,
-      ai: {
-        model: "openai/gpt-5.4",
-        updatedAt: "2026-01-01T00:00:00.000Z"
-      },
+      snapshotModel: "openai/gpt-5.4",
       viewport: {
         width: 1280,
         height: 800
@@ -52,14 +45,14 @@ function formatExpectedConfigExample() {
 function invalidConfigError(configPath, detail) {
   return new Error(
     [
-      `AI config is invalid at ${configPath}.`,
+      `Config is invalid at ${configPath}.`,
       detail ? `Problems:
 ${detail}` : null,
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai", "viewport", "windowPosition", and "sessionMode" are optional.',
-      '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
+      '  - "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`
     ].filter(Boolean).join("\n")
@@ -93,34 +86,30 @@ function writeLibrettoConfig(config, configPath = LIBRETTO_CONFIG_PATH) {
   writeFileSync(configPath, JSON.stringify(parsed, null, 2), "utf-8");
   return parsed;
 }
-function readAiConfig(configPath = LIBRETTO_CONFIG_PATH) {
-  return readLibrettoConfig(configPath).ai ?? null;
+function readSnapshotModel(configPath = LIBRETTO_CONFIG_PATH) {
+  return readLibrettoConfig(configPath).snapshotModel ?? null;
 }
-function writeAiConfig(model, configPath = LIBRETTO_CONFIG_PATH) {
+function writeSnapshotModel(model, configPath = LIBRETTO_CONFIG_PATH) {
   let librettoConfig;
   try {
     librettoConfig = readLibrettoConfig(configPath);
   } catch {
     librettoConfig = { version: CURRENT_CONFIG_VERSION };
   }
-  const ai = AiConfigSchema.parse({
-    model,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
   writeLibrettoConfig(
     {
       ...librettoConfig,
       version: CURRENT_CONFIG_VERSION,
-      ai
+      snapshotModel: model
     },
     configPath
   );
-  return ai;
+  return model;
 }
-function clearAiConfig(configPath = LIBRETTO_CONFIG_PATH) {
+function clearSnapshotModel(configPath = LIBRETTO_CONFIG_PATH) {
   const librettoConfig = readLibrettoConfig(configPath);
-  if (!librettoConfig.ai) return false;
-  const { ai: _ai, ...rest } = librettoConfig;
+  if (!librettoConfig.snapshotModel) return false;
+  const { snapshotModel: _, ...rest } = librettoConfig;
   writeLibrettoConfig(
     {
       ...rest
@@ -130,14 +119,13 @@ function clearAiConfig(configPath = LIBRETTO_CONFIG_PATH) {
   return true;
 }
 export {
-  AiConfigSchema,
   CURRENT_CONFIG_VERSION,
   LibrettoConfigSchema,
   ViewportConfigSchema,
   WindowPositionConfigSchema,
-  clearAiConfig,
-  readAiConfig,
+  clearSnapshotModel,
   readLibrettoConfig,
-  writeAiConfig,
-  writeLibrettoConfig
+  readSnapshotModel,
+  writeLibrettoConfig,
+  writeSnapshotModel
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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.2"
+  version: "0.6.4"
 ---
 
 ## How Libretto Works

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

@@ -19,7 +19,7 @@ Libretto reads workspace config from `.libretto/config.json`.
 
 ## Supported Settings
 
-- `ai.model` selects the configured analysis model for `snapshot`.
+- `snapshotModel` selects the configured analysis model for `snapshot`.
 - `viewport` is an optional top-level setting used by `open` and `run` when you do not pass `--viewport`.
 - Viewport precedence is: CLI `--viewport`, then `.libretto/config.json`, then the default `1366x768`.
 - `sessionMode` sets the default session access mode for new sessions created by `open`, `connect`, and `run`. Must be `"read-only"` or `"write-access"`. When omitted, defaults to `"write-access"`. Pass `--read-only` or `--write-access` to `open`, `connect`, or `run` to override when creating a session.
@@ -29,10 +29,7 @@ Example:
 ```json
 {
   "version": 1,
-  "ai": {
-    "model": "openai/gpt-5.4",
-    "updatedAt": "2026-01-01T00:00:00.000Z"
-  },
+  "snapshotModel": "openai/gpt-5.4",
   "viewport": {
     "width": 1280,
     "height": 800
@@ -47,7 +44,7 @@ Example:
 npx libretto setup                                         # first-time onboarding, auto-pins default model
 npx libretto status                                        # inspect AI config and open sessions
 npx libretto ai configure openai                           # explicitly change provider/model
-npx libretto open https://app.example.com --viewport 1440x900
+npx libretto open https://example.com --viewport 1440x900
 npx libretto run ./integration.ts --viewport 1440x900
 ```
 

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

package/src/cli/cli.ts

@@ -19,7 +19,7 @@ function printSetupAudit(): void {
   const status = resolveAiSetupStatus();
   switch (status.kind) {
     case "ready":
-      console.log(`✓ AI model: ${status.model}`);
+      console.log(`✓ Snapshot model: ${status.model}`);
       break;
     case "configured-missing-credentials":
       console.log(

package/src/cli/commands/ai.ts

@@ -1,10 +1,9 @@
 import { z } from "zod";
 import {
   CURRENT_CONFIG_VERSION,
-  readAiConfig,
-  writeAiConfig,
-  clearAiConfig,
-  type AiConfig,
+  readSnapshotModel,
+  writeSnapshotModel,
+  clearSnapshotModel,
 } from "../core/config.js";
 import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
 import { DEFAULT_SNAPSHOT_MODELS } from "../core/ai-model.js";
@@ -27,10 +26,9 @@ function formatConfigureProviders(separator = " | "): string {
   return CONFIGURE_PROVIDERS.join(separator);
 }
 
-function printAiConfig(config: AiConfig, configPath: string): void {
-  console.log(`Model: ${config.model}`);
+function printSnapshotModelConfig(model: string, configPath: string): void {
+  console.log(`Snapshot model: ${model}`);
   console.log(`Config file: ${configPath}`);
-  console.log(`Updated at: ${config.updatedAt}`);
 }
 
 /**
@@ -71,26 +69,26 @@ export function runAiConfigure(
   const presetArg = input.preset?.trim();
 
   if (!presetArg && !input.clear) {
-    const config = readAiConfig(configPath);
-    if (!config) {
+    const model = readSnapshotModel(configPath);
+    if (!model) {
       console.log(
-        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
+        `No snapshot model set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
       );
       console.log(
         "Provider credentials still come from your shell or .env file.",
       );
       return;
     }
-    printAiConfig(config, configPath);
+    printSnapshotModelConfig(model, configPath);
     return;
   }
 
   if (input.clear) {
-    const removed = clearAiConfig(configPath);
+    const removed = clearSnapshotModel(configPath);
     if (removed) {
-      console.log(`Cleared AI config: ${configPath}`);
+      console.log(`Cleared snapshot model config: ${configPath}`);
     } else {
-      console.log("No AI config was set.");
+      console.log("No snapshot model was set.");
     }
     return;
   }
@@ -107,9 +105,9 @@ export function runAiConfigure(
     );
   }
 
-  const config = writeAiConfig(model, configPath);
-  console.log("AI config saved.");
-  printAiConfig(config, configPath);
+  writeSnapshotModel(model, configPath);
+  console.log("Snapshot model saved.");
+  printSnapshotModelConfig(model, configPath);
 }
 
 export const aiConfigureInput = SimpleCLI.input({

package/src/cli/commands/setup.ts

@@ -1,17 +1,14 @@
 import { createInterface } from "node:readline";
 import {
-  appendFileSync,
   cpSync,
   existsSync,
   readdirSync,
-  readFileSync,
   rmSync,
-  writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { writeAiConfig } from "../core/config.js";
+import { writeSnapshotModel } from "../core/config.js";
 import {
   ensureLibrettoSetup,
   LIBRETTO_CONFIG_PATH,
@@ -20,12 +17,71 @@ import {
 import {
   type AiSetupStatus,
   DEFAULT_SNAPSHOT_MODELS,
-  loadSnapshotEnv,
   resolveAiSetupStatus,
 } from "../core/ai-model.js";
 import type { Provider } from "../core/resolve-model.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
+const PROVIDER_SDK_PACKAGES: Record<Provider, string> = {
+  openai: "@ai-sdk/openai",
+  anthropic: "@ai-sdk/anthropic",
+  google: "@ai-sdk/google",
+  vertex: "@ai-sdk/google-vertex",
+};
+
+function detectPackageManager(): string {
+  if (existsSync(join(REPO_ROOT, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(REPO_ROOT, "yarn.lock"))) return "yarn";
+  if (existsSync(join(REPO_ROOT, "bun.lockb"))) return "bun";
+  return "npm";
+}
+
+function installCommand(pkgManager: string): string {
+  switch (pkgManager) {
+    case "yarn":
+      return "yarn add";
+    case "bun":
+      return "bun add";
+    case "pnpm":
+      return "pnpm add";
+    default:
+      return "npm install";
+  }
+}
+
+function isSdkInstalled(sdkPackage: string): boolean {
+  try {
+    const result = spawnSync("node", ["-e", `require.resolve("${sdkPackage}")`], {
+      cwd: REPO_ROOT,
+      stdio: "pipe",
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function installSdkIfNeeded(provider: Provider): void {
+  const sdkPackage = PROVIDER_SDK_PACKAGES[provider];
+  if (isSdkInstalled(sdkPackage)) return;
+
+  const pkgManager = detectPackageManager();
+  const cmd = installCommand(pkgManager);
+  console.log(`\nInstalling ${sdkPackage}...`);
+  const result = spawnSync(cmd, [sdkPackage], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    shell: true,
+  });
+  if (result.status === 0) {
+    console.log(`✓ Installed ${sdkPackage}`);
+  } else {
+    console.error(
+      `✗ Failed to install ${sdkPackage}. Install it manually: ${cmd} ${sdkPackage}`,
+    );
+  }
+}
+
 export type ProviderChoice = {
   key: string;
   label: string;
@@ -97,7 +153,7 @@ function ensurePinnedDefaultModel(
   status: AiSetupStatus & { kind: "ready" },
 ): AiSetupStatus & { kind: "ready" } {
   if (status.source !== "config") {
-    writeAiConfig(status.model);
+    writeSnapshotModel(status.model);
     return { ...status, source: "config" as const };
   }
   return status;
@@ -127,10 +183,7 @@ function printInvalidAiConfigWarning(status: AiSetupStatus): void {
 
 // ── Repair plan helpers (exported for testing) ──────────────────────────────
 
-export type RepairChoice =
-  | "enter-matching-credential"
-  | "switch-provider"
-  | "skip";
+export type RepairChoice = "switch-provider" | "skip";
 
 export type RepairPlan =
   | {
@@ -155,7 +208,7 @@ export function buildRepairPlan(status: AiSetupStatus): RepairPlan {
       provider: status.provider,
       model: status.model,
       envVar: choice?.envVar ?? `${status.provider.toUpperCase()}_API_KEY`,
-      choices: ["enter-matching-credential", "switch-provider", "skip"],
+      choices: ["switch-provider", "skip"],
     };
   }
   if (status.kind === "invalid-config") {
@@ -223,72 +276,13 @@ function printSnapshotApiStatus(): boolean {
 }
 
 /**
- * Write an env var to the .env file and update process.env.
- */
-function writeEnvVar(envVar: string, value: string, envPath: string): void {
-  let envContent = "";
-  if (existsSync(envPath)) {
-    envContent = readFileSync(envPath, "utf-8");
-  }
-
-  const envLine = `${envVar}=${value}`;
-  if (envContent.includes(`${envVar}=`)) {
-    const updated = envContent.replace(
-      new RegExp(`^${envVar}=.*$`, "m"),
-      () => envLine,
-    );
-    writeFileSync(envPath, updated);
-    console.log(`\n✓ Updated ${envVar} in ${envPath}`);
-  } else {
-    const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
-    appendFileSync(envPath, `${separator}${envLine}\n`);
-    console.log(`\n✓ Added ${envVar} to ${envPath}`);
-  }
-
-  process.env[envVar] = value;
-}
-
-/**
- * Prompt the user to enter a credential for a specific provider and pin its model.
- * When modelOverride is provided (e.g. during repair), preserves the existing model
- * instead of resetting to the provider default.
- * Returns true if credential was entered successfully.
- */
-async function promptForCredential(
-  rl: ReturnType<typeof createInterface>,
-  choice: ProviderChoice,
-  envPath: string,
-  modelOverride?: string,
-): Promise<boolean> {
-  console.log(`\n${choice.label} selected.`);
-  console.log(`${choice.envHint}\n`);
-
-  const apiKeyValue = await promptUser(rl, `Enter your ${choice.envVar}: `);
-
-  if (!apiKeyValue) {
-    console.log("\nNo value entered. Skipping API key setup.");
-    return false;
-  }
-
-  writeEnvVar(choice.envVar, apiKeyValue, envPath);
-  loadSnapshotEnv();
-
-  const model = modelOverride ?? DEFAULT_SNAPSHOT_MODELS[choice.provider];
-  writeAiConfig(model);
-  console.log(`✓ Snapshot API ready: ${model}`);
-  console.log(
-    "To change: npx libretto ai configure openai | anthropic | gemini | vertex",
-  );
-  return true;
-}
-
-/**
- * Run the full provider selection menu and credential entry.
+ * Run the full provider selection menu.
+ * Pins the selected provider's default model to config and prints
+ * instructions for the user to add the credential to .env themselves.
  * Returns true if a provider was successfully configured.
  */
 async function promptProviderSelection(
   rl: ReturnType<typeof createInterface>,
-  envPath: string,
 ): Promise<boolean> {
   console.log(
     "Which model provider would you like to use for snapshot analysis?\n",
@@ -311,7 +305,13 @@ async function promptProviderSelection(
     return false;
   }
 
-  return promptForCredential(rl, selected, envPath);
+  const model = DEFAULT_SNAPSHOT_MODELS[selected.provider];
+  writeSnapshotModel(model);
+  console.log(`\n✓ ${selected.label} selected (model: ${model}).`);
+  console.log(`\nAdd ${selected.envVar} to your .env file:`);
+  console.log(`  ${selected.envHint}`);
+  installSdkIfNeeded(selected.provider);
+  return true;
 }
 
 function printSkipMessage(): void {
@@ -329,7 +329,6 @@ function printSkipMessage(): void {
 
 async function runInteractiveApiSetup(): Promise<void> {
   const status = resolveAiSetupStatus();
-  const envPath = join(REPO_ROOT, ".env");
 
   console.log(
     "\nLibretto uses a sub-agent to analyze DOM snapshots. The model is determined by environment variables.",
@@ -353,26 +352,16 @@ async function runInteractiveApiSetup(): Promise<void> {
     // ── Repair: configured provider with missing credentials ──
     if (plan.kind === "repair-missing-credentials") {
       console.log(formatMissingCredentialsMessage(plan));
+      console.log(`\nAdd ${plan.envVar} to your .env file to fix this.`);
       console.log("");
-      console.log("How would you like to fix this?\n");
-      console.log(`  1) Enter ${plan.envVar}`);
-      console.log("  2) Switch to a different provider");
+      console.log("Or switch to a different provider:\n");
+      console.log("  1) Switch to a different provider");
       console.log("  s) Skip for now\n");
 
       const answer = await promptUser(rl, "Choice: ");
 
       if (answer === "1") {
-        const matchingChoice = PROVIDER_CHOICES.find(
-          (c) => c.provider === plan.provider,
-        );
-        if (matchingChoice) {
-          await promptForCredential(rl, matchingChoice, envPath, plan.model);
-        }
-        return;
-      }
-
-      if (answer === "2") {
-        await promptProviderSelection(rl, envPath);
+        await promptProviderSelection(rl);
         return;
       }
 
@@ -387,13 +376,13 @@ async function runInteractiveApiSetup(): Promise<void> {
       console.log(
         "\nWould you like to reconfigure with a fresh provider selection?\n",
       );
-      await promptProviderSelection(rl, envPath);
+      await promptProviderSelection(rl);
       return;
     }
 
     // ── Unconfigured: standard first-run flow ──
     console.log("✗ No snapshot API credentials detected.\n");
-    await promptProviderSelection(rl, envPath);
+    await promptProviderSelection(rl);
   } finally {
     rl.close();
   }
@@ -441,6 +430,13 @@ function copySkills(): void {
   const agentDirs = detectAgentDirs(REPO_ROOT);
 
   if (agentDirs.length === 0) {
+    console.log(
+      "\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:",
+    );
+    console.log(`    mkdir ${join(REPO_ROOT, ".claude")}`);
     return;
   }
 

package/src/cli/commands/snapshot.ts

@@ -12,7 +12,7 @@ import {
 import { SimpleCLI } from "../framework/simple-cli.js";
 import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
 import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
-import { readAiConfig } from "../core/config.js";
+import { readSnapshotModel } from "../core/config.js";
 import { resolveSnapshotApiModelOrThrow } from "../core/ai-model.js";
 
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 } as const;
@@ -256,8 +256,8 @@ async function runSnapshot(
   const normalizedObjective = objective.trim();
   const normalizedContext = context.trim();
 
-  const configuredAi = readAiConfig();
-  resolveSnapshotApiModelOrThrow(configuredAi);
+  const snapshotModel = readSnapshotModel();
+  resolveSnapshotApiModelOrThrow(snapshotModel);
 
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
@@ -283,7 +283,7 @@ async function runSnapshot(
   // The legacy CLI-agent path (spawning codex/claude/gemini as a subprocess) is preserved
   // in snapshot-analyzer.ts — to switch back, replace this call with:
   //   await runInterpret(interpretArgs, logger);
-  await runApiInterpret(interpretArgs, logger, configuredAi);
+  await runApiInterpret(interpretArgs, logger, snapshotModel);
 }
 
 export const snapshotInput = SimpleCLI.input({

package/src/cli/commands/status.ts

@@ -10,7 +10,7 @@ function printAiStatus(status: AiSetupStatus): void {
 
   switch (status.kind) {
     case "ready":
-      console.log(`  ✓ Model: ${status.model}`);
+      console.log(`  ✓ Snapshot model: ${status.model}`);
       if (status.source === "config") {
         console.log(`  Config: ${LIBRETTO_CONFIG_PATH}`);
       } else {

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

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { type AiConfig, readAiConfig } from "./config.js";
+import { readSnapshotModel } from "./config.js";
 import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
@@ -221,18 +221,18 @@ function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
  * Resolve which API model to use for snapshot analysis.
  *
  * Priority:
- * 1. Model from .libretto/config.json ai.model field (set via `ai configure`)
+ * 1. snapshotModel from .libretto/config.json (set via `ai configure`)
  * 2. Auto-detect from available API credentials in env
  */
 export function resolveSnapshotApiModel(
-  config: AiConfig | null = readAiConfig(),
+  snapshotModel: string | null = readSnapshotModel(),
 ): SnapshotApiModelSelection | null {
   loadSnapshotEnv();
 
-  if (config?.model) {
-    const { provider } = parseModel(config.model);
+  if (snapshotModel) {
+    const { provider } = parseModel(snapshotModel);
     return {
-      model: config.model,
+      model: snapshotModel,
       provider,
       source: "config",
     };
@@ -242,9 +242,9 @@ export function resolveSnapshotApiModel(
 }
 
 export function resolveSnapshotApiModelOrThrow(
-  config: AiConfig | null = readAiConfig(),
+  snapshotModel: string | null = readSnapshotModel(),
 ): SnapshotApiModelSelection {
-  const selection = resolveSnapshotApiModel(config);
+  const selection = resolveSnapshotApiModel(snapshotModel);
   if (!selection) {
     throw new SnapshotApiUnavailableError(noSnapshotApiConfiguredMessage());
   }
@@ -288,14 +288,14 @@ export type AiSetupStatus =
   | { kind: "unconfigured" };
 
 /**
- * Read AI config without throwing on invalid files.
- * Returns the config or an error message.
+ * Read snapshot model without throwing on invalid files.
+ * Returns the model string or an error message.
  */
-function readAiConfigSafely(
+function readSnapshotModelSafely(
   configPath: string,
-): { ok: true; config: AiConfig | null } | { ok: false; message: string } {
+): { ok: true; model: string | null } | { ok: false; message: string } {
   try {
-    return { ok: true, config: readAiConfig(configPath) };
+    return { ok: true, model: readSnapshotModel(configPath) };
   } catch (err) {
     return {
       ok: false,
@@ -312,25 +312,25 @@ function readAiConfigSafely(
  * that the throwing APIs collapse into errors.
  *
  * 1. If config read throws → `invalid-config`.
- * 2. If config has an `ai` block → check credentials for that provider.
- * 3. If no config or no `ai` block → auto-detect from env via existing resolver.
+ * 2. If config has a `snapshotModel` → check credentials for that provider.
+ * 3. If no `snapshotModel` → auto-detect from env via existing resolver.
  */
 export function resolveAiSetupStatus(
   configPath: string = LIBRETTO_CONFIG_PATH,
 ): AiSetupStatus {
   loadSnapshotEnv();
 
-  const configResult = readAiConfigSafely(configPath);
+  const result = readSnapshotModelSafely(configPath);
 
-  if (!configResult.ok) {
-    return { kind: "invalid-config", message: configResult.message };
+  if (!result.ok) {
+    return { kind: "invalid-config", message: result.message };
   }
 
-  // Config exists with an ai block — use it directly to check credentials
-  if (configResult.config) {
+  // Config has a snapshotModel — use it directly to check credentials
+  if (result.model) {
     let selection: SnapshotApiModelSelection | null;
     try {
-      selection = resolveSnapshotApiModel(configResult.config);
+      selection = resolveSnapshotApiModel(result.model);
     } catch (err) {
       return {
         kind: "invalid-config",
@@ -356,7 +356,7 @@ export function resolveAiSetupStatus(
     };
   }
 
-  // No ai config — fall back to env auto-detect via existing resolver
+  // No snapshotModel — fall back to env auto-detect via existing resolver
   const envSelection = resolveSnapshotApiModel(null);
   if (envSelection && hasProviderCredentials(envSelection.provider)) {
     return {

package/src/cli/core/api-snapshot-analyzer.ts

@@ -18,15 +18,15 @@ import {
   type InterpretResult,
   type InterpretArgs,
 } from "./snapshot-analyzer.js";
-import { readAiConfig, type AiConfig } from "./config.js";
+import { readSnapshotModel } from "./config.js";
 import { resolveSnapshotApiModelOrThrow } from "./ai-model.js";
 
 export async function runApiInterpret(
   args: InterpretArgs,
   logger: LoggerApi,
-  configuredAi: AiConfig | null = readAiConfig(),
+  snapshotModel: string | null = readSnapshotModel(),
 ): Promise<void> {
-  const selection = resolveSnapshotApiModelOrThrow(configuredAi);
+  const selection = resolveSnapshotApiModelOrThrow(snapshotModel);
 
   logger.info("api-interpret-start", {
     objective: args.objective,

package/src/cli/core/config.ts

@@ -6,24 +6,6 @@ import { LIBRETTO_CONFIG_PATH } from "./context.js";
 
 export const CURRENT_CONFIG_VERSION = 1;
 
-/**
- * AI configuration schema.
- *
- * The `model` field is a provider/model-id string (e.g. "openai/gpt-5.4",
- * "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview", "vertex/gemini-2.5-pro").
- *
- * Legacy note: earlier versions stored a `preset` (codex|claude|gemini) and
- * `commandPrefix` (CLI args to spawn a sub-agent process). That approach has
- * been replaced by direct API calls via the Vercel AI SDK. The legacy CLI-agent
- * code is preserved in snapshot-analyzer.ts but is not wired into the snapshot
- * command.
- */
-export const AiConfigSchema = z.object({
-  model: z.string().min(1),
-  updatedAt: z.string(),
-});
-export type AiConfig = z.infer<typeof AiConfigSchema>;
-
 export const ViewportConfigSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1),
@@ -39,7 +21,7 @@ export type WindowPositionConfig = z.infer<typeof WindowPositionConfigSchema>;
 export const LibrettoConfigSchema = z
   .object({
     version: z.literal(CURRENT_CONFIG_VERSION),
-    ai: AiConfigSchema.optional(),
+    snapshotModel: z.string().min(1).optional(),
     viewport: ViewportConfigSchema.optional(),
     windowPosition: WindowPositionConfigSchema.optional(),
     provider: z.string().optional(),
@@ -58,10 +40,7 @@ function formatExpectedConfigExample(): string {
   return JSON.stringify(
     {
       version: CURRENT_CONFIG_VERSION,
-      ai: {
-        model: "openai/gpt-5.4",
-        updatedAt: "2026-01-01T00:00:00.000Z",
-      },
+      snapshotModel: "openai/gpt-5.4",
       viewport: {
         width: 1280,
         height: 800,
@@ -80,13 +59,13 @@ function formatExpectedConfigExample(): string {
 function invalidConfigError(configPath: string, detail?: string): Error {
   return new Error(
     [
-      `AI config is invalid at ${configPath}.`,
+      `Config is invalid at ${configPath}.`,
       detail ? `Problems:\n${detail}` : null,
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai", "viewport", "windowPosition", and "sessionMode" are optional.',
-      '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
+      '  - "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`,
     ]
@@ -132,16 +111,16 @@ export function writeLibrettoConfig(
   return parsed;
 }
 
-export function readAiConfig(
+export function readSnapshotModel(
   configPath: string = LIBRETTO_CONFIG_PATH,
-): AiConfig | null {
-  return readLibrettoConfig(configPath).ai ?? null;
+): string | null {
+  return readLibrettoConfig(configPath).snapshotModel ?? null;
 }
 
-export function writeAiConfig(
+export function writeSnapshotModel(
   model: string,
   configPath: string = LIBRETTO_CONFIG_PATH,
-): AiConfig {
+): string {
   let librettoConfig: LibrettoConfig;
   try {
     librettoConfig = readLibrettoConfig(configPath);
@@ -150,27 +129,23 @@ export function writeAiConfig(
     // overwrite a broken file instead of throwing.
     librettoConfig = { version: CURRENT_CONFIG_VERSION };
   }
-  const ai = AiConfigSchema.parse({
-    model,
-    updatedAt: new Date().toISOString(),
-  });
   writeLibrettoConfig(
     {
       ...librettoConfig,
       version: CURRENT_CONFIG_VERSION,
-      ai,
+      snapshotModel: model,
     },
     configPath,
   );
-  return ai;
+  return model;
 }
 
-export function clearAiConfig(
+export function clearSnapshotModel(
   configPath: string = LIBRETTO_CONFIG_PATH,
 ): boolean {
   const librettoConfig = readLibrettoConfig(configPath);
-  if (!librettoConfig.ai) return false;
-  const { ai: _ai, ...rest } = librettoConfig;
+  if (!librettoConfig.snapshotModel) return false;
+  const { snapshotModel: _, ...rest } = librettoConfig;
   writeLibrettoConfig(
     {
       ...rest,