@ai-agent-tools/picgen 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/cli.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import "dotenv/config";
 import { Command } from "commander";
 
 // src/commands/create.ts
@@ -218,12 +217,12 @@ function padMilliseconds(value) {
 function slug(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
 }
-function redactProviderImageData(value, key) {
+function redactProviderImageData(value, key2) {
   if (Array.isArray(value)) {
     return value.map((item) => redactProviderImageData(item));
   }
   if (!value || typeof value !== "object") {
-    return shouldRedactImageDataKey(key) && typeof value === "string" ? redactedProviderDataPlaceholder(value) : value;
+    return shouldRedactImageDataKey(key2) && typeof value === "string" ? redactedProviderDataPlaceholder(value) : value;
   }
   return Object.fromEntries(
     Object.entries(value).map(([entryKey, entryValue]) => [
@@ -232,8 +231,8 @@ function redactProviderImageData(value, key) {
     ])
   );
 }
-function shouldRedactImageDataKey(key) {
-  return key === "b64_json" || key === "data" || key === "thoughtSignature" || key === "thought_signature";
+function shouldRedactImageDataKey(key2) {
+  return key2 === "b64_json" || key2 === "data" || key2 === "thoughtSignature" || key2 === "thought_signature";
 }
 function redactedProviderDataPlaceholder(value) {
   return `[redacted provider data: ${value.length} chars]`;
@@ -275,9 +274,9 @@ function mimeTypeFromPath(path) {
 }
 
 // src/config/store.ts
-import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
-import { dirname, join as join2 } from "path";
-import { homedir } from "os";
+import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 import YAML from "yaml";
 
 // src/config/defaults.ts
@@ -363,6 +362,164 @@ var defaultConfig = {
   }
 };
 
+// src/config/env.ts
+import { chmod, mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
+import { existsSync } from "fs";
+import { createHash } from "crypto";
+import { dirname, join as join2, resolve as resolve2 } from "path";
+import { homedir } from "os";
+import { parse } from "dotenv";
+var loadedEnvSources = /* @__PURE__ */ new Map();
+function getManagedEnvPath() {
+  return process.env.PICGEN_ENV_PATH ?? join2(homedir(), ".picgen", ".env");
+}
+async function loadPicgenEnv() {
+  const shellEnv = new Set(Object.keys(process.env));
+  await loadEnvFile(getManagedEnvPath(), shellEnv, false, "managed");
+  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true, "project");
+}
+async function saveManagedEnvVar(name, value) {
+  const path = getManagedEnvPath();
+  const current = await readManagedEnvFile(path);
+  const next = {
+    ...current,
+    [name]: value
+  };
+  await mkdir2(dirname(path), { recursive: true });
+  await writeFile2(path, stringifyEnv(next), "utf8");
+  await chmod(path, 384);
+  process.env[name] = value;
+  loadedEnvSources.set(name, { source: "managed", path });
+  return path;
+}
+async function inspectEnvVar(name) {
+  const shellValue = process.env[name];
+  if (shellValue !== void 0) {
+    const loadedSource = loadedEnvSources.get(name);
+    return describeEnvValue(
+      name,
+      shellValue,
+      loadedSource?.source ?? "shell",
+      loadedSource?.path
+    );
+  }
+  const projectPath = resolve2(process.cwd(), ".env");
+  const project = await readEnvFile(projectPath);
+  if (project[name] !== void 0) {
+    return describeEnvValue(name, project[name], "project", projectPath);
+  }
+  const managedPath = getManagedEnvPath();
+  const managed = await readEnvFile(managedPath);
+  if (managed[name] !== void 0) {
+    return describeEnvValue(name, managed[name], "managed", managedPath);
+  }
+  return {
+    name,
+    set: false
+  };
+}
+async function inspectEnvVars(names) {
+  const uniqueNames = [...new Set(names)];
+  return Promise.all(uniqueNames.map((name) => inspectEnvVar(name)));
+}
+async function readEnvVarValue(name) {
+  if (process.env[name] !== void 0) return process.env[name];
+  const project = await readEnvFile(resolve2(process.cwd(), ".env"));
+  if (project[name] !== void 0) return project[name];
+  const managed = await readEnvFile(getManagedEnvPath());
+  return managed[name];
+}
+async function loadEnvFile(path, shellEnv, overrideManagedValues, source) {
+  if (!existsSync(path)) return;
+  const parsed = parse(await readFile(path, "utf8"));
+  for (const [name, value] of Object.entries(parsed)) {
+    if (shellEnv.has(name)) continue;
+    if (!overrideManagedValues && process.env[name] !== void 0) continue;
+    process.env[name] = value;
+    loadedEnvSources.set(name, { source, path });
+  }
+}
+async function readManagedEnvFile(path) {
+  return readEnvFile(path);
+}
+async function readEnvFile(path) {
+  try {
+    return parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+function stringifyEnv(values) {
+  return `${Object.entries(values).map(([name, value]) => `${name}=${quoteEnvValue(value)}`).join("\n")}
+`;
+}
+function quoteEnvValue(value) {
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+function describeEnvValue(name, value, source, path) {
+  return {
+    name,
+    set: true,
+    source,
+    path,
+    length: value.length,
+    preview: maskSecret(value),
+    fingerprint: createHash("sha256").update(value).digest("hex").slice(0, 12)
+  };
+}
+function maskSecret(value) {
+  if (value.length <= 11) return "*".repeat(value.length);
+  return `${value.slice(0, 7)}...${value.slice(-4)}`;
+}
+
+// src/config/providerKeys.ts
+function nextAvailableProviderApiKeyEnv(config, baseEnv, providerName, existingEnv) {
+  if (existingEnv) return existingEnv;
+  const usedEnvs = new Set(Object.values(config.providers).map((provider2) => provider2.api_key_env));
+  if (!usedEnvs.has(baseEnv)) return baseEnv;
+  const providerEnv = providerNameToApiKeyEnv(providerName);
+  if (!usedEnvs.has(providerEnv)) return providerEnv;
+  let index = 2;
+  while (usedEnvs.has(`${providerEnv}_${index}`)) index += 1;
+  return `${providerEnv}_${index}`;
+}
+function providerNameToApiKeyEnv(providerName) {
+  const safeName = providerName.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return `PICGEN_${safeName || "PROVIDER"}_KEY`;
+}
+
+// src/config/migrations.ts
+async function migrateConfig(config) {
+  const migrated = structuredClone(config);
+  let changed = false;
+  const usedEnvs = /* @__PURE__ */ new Set();
+  for (const [providerName, provider2] of Object.entries(migrated.providers)) {
+    const currentEnv = provider2.api_key_env;
+    if (!usedEnvs.has(currentEnv)) {
+      usedEnvs.add(currentEnv);
+      continue;
+    }
+    const nextEnv = nextUniqueProviderEnv(usedEnvs, providerName);
+    const currentValue = await readEnvVarValue(currentEnv);
+    provider2.api_key_env = nextEnv;
+    usedEnvs.add(nextEnv);
+    changed = true;
+    if (currentValue && !await readEnvVarValue(nextEnv)) {
+      await saveManagedEnvVar(nextEnv, currentValue);
+    }
+  }
+  return { config: migrated, changed };
+}
+function nextUniqueProviderEnv(usedEnvs, providerName) {
+  const baseEnv = providerNameToApiKeyEnv(providerName);
+  if (!usedEnvs.has(baseEnv)) return baseEnv;
+  let index = 2;
+  while (usedEnvs.has(`${baseEnv}_${index}`)) index += 1;
+  return `${baseEnv}_${index}`;
+}
+
 // src/config/schema.ts
 import { z } from "zod";
 var providerSchema = z.object({
@@ -429,14 +586,19 @@ function defaultCapabilitiesForProtocol(protocol) {
 
 // src/config/store.ts
 function getConfigPath() {
-  return process.env.PICGEN_CONFIG ?? join2(homedir(), ".picgen", "config.yaml");
+  return process.env.PICGEN_CONFIG ?? join3(homedir2(), ".picgen", "config.yaml");
 }
 async function loadConfig() {
   const path = getConfigPath();
   try {
-    const raw = await readFile(path, "utf8");
+    const raw = await readFile2(path, "utf8");
     const parsed = YAML.parse(raw);
-    return picgenConfigSchema.parse(parsed);
+    const config = picgenConfigSchema.parse(parsed);
+    const migrated = await migrateConfig(config);
+    if (migrated.changed) {
+      await writeConfigFile(path, migrated.config);
+    }
+    return migrated.config;
   } catch (error) {
     if (error.code === "ENOENT") {
       return structuredClone(defaultConfig);
@@ -447,8 +609,11 @@ async function loadConfig() {
 async function saveConfig(config) {
   const parsed = picgenConfigSchema.parse(config);
   const path = getConfigPath();
-  await mkdir2(dirname(path), { recursive: true });
-  await writeFile2(path, YAML.stringify(parsed), "utf8");
+  await writeConfigFile(path, parsed);
+}
+async function writeConfigFile(path, config) {
+  await mkdir3(dirname2(path), { recursive: true });
+  await writeFile3(path, YAML.stringify(config), "utf8");
 }
 async function ensureConfig() {
   const config = await loadConfig();
@@ -457,7 +622,54 @@ async function ensureConfig() {
 }
 
 // src/providers/gemini.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
+
+// src/providers/timeout.ts
+var FAST_PROVIDER_TIMEOUT_MS = 12e4;
+var DEFAULT_PROVIDER_TIMEOUT_MS = 18e4;
+var SLOW_PROVIDER_TIMEOUT_MS = 3e5;
+function resolveProviderTimeoutMs(plan) {
+  const override = parseTimeoutOverride(process.env.PICGEN_PROVIDER_TIMEOUT_MS);
+  if (override !== void 0) return override;
+  if (plan.presetName === "fast-draft" || plan.modeName === "fast" || plan.preset.quality === "low") {
+    return FAST_PROVIDER_TIMEOUT_MS;
+  }
+  if (plan.modeName === "premium" || plan.preset.size === "large" || plan.preset.quality === "high") {
+    return SLOW_PROVIDER_TIMEOUT_MS;
+  }
+  return DEFAULT_PROVIDER_TIMEOUT_MS;
+}
+async function fetchWithProviderTimeout(input3, init, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input3, {
+      ...init,
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (isAbortError(error)) {
+      throw new Error(formatProviderTimeoutError(timeoutMs));
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function formatProviderTimeoutError(timeoutMs) {
+  return `Provider request timed out after ${Math.ceil(
+    timeoutMs / 1e3
+  )}s. The provider may still be processing or temporarily unavailable. Try again, use a faster preset, or increase PICGEN_PROVIDER_TIMEOUT_MS.`;
+}
+function parseTimeoutOverride(value) {
+  if (!value) return void 0;
+  const timeoutMs = Number(value);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) return void 0;
+  return timeoutMs;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
 
 // src/providers/urls.ts
 function normalizeProviderBaseUrl(baseUrl) {
@@ -495,15 +707,20 @@ var GeminiAdapter = class {
     const providerImages = [];
     const requestCount = Math.max(1, plan.preset.n);
     const referenceParts = await readReferenceImageParts(plan);
+    const timeoutMs = resolveProviderTimeoutMs(plan);
     for (let index = 0; index < requestCount; index += 1) {
-      const response = await fetch(buildGeminiGenerateContentUrl(plan.provider.base_url, plan.model), {
-        method: "POST",
-        headers: {
-          "x-goog-api-key": apiKey,
-          "Content-Type": "application/json"
+      const response = await fetchWithProviderTimeout(
+        buildGeminiGenerateContentUrl(plan.provider.base_url, plan.model),
+        {
+          method: "POST",
+          headers: {
+            "x-goog-api-key": apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(buildGeminiGenerateContentRequest(plan, referenceParts))
         },
-        body: JSON.stringify(buildGeminiGenerateContentRequest(plan, referenceParts))
-      });
+        timeoutMs
+      );
       const raw = await readJsonResponse(response);
       if (!response.ok) {
         throw new Error(formatGeminiError(response.status, response.statusText, raw));
@@ -545,7 +762,7 @@ async function readReferenceImageParts(plan) {
     plan.referenceImages.map(async (image) => ({
       inlineData: {
         mimeType: image.mime_type,
-        data: (await readFile2(image.path)).toString("base64")
+        data: (await readFile3(image.path)).toString("base64")
       }
     }))
   );
@@ -624,14 +841,18 @@ var OpenAIImagesAdapter = class {
     if (!apiKey) {
       throw new Error(`Missing API key environment variable: ${plan.provider.api_key_env}`);
     }
-    const response = await fetch(buildOpenAIImagesUrl(plan.provider.base_url), {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json"
+    const response = await fetchWithProviderTimeout(
+      buildOpenAIImagesUrl(plan.provider.base_url),
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(buildOpenAIImagesRequest(plan))
       },
-      body: JSON.stringify(buildOpenAIImagesRequest(plan))
-    });
+      resolveProviderTimeoutMs(plan)
+    );
     const raw = await readJsonResponse2(response);
     if (!response.ok) {
       throw new Error(formatOpenAIImagesError(response.status, response.statusText, raw));
@@ -758,7 +979,7 @@ function getAdapter(protocol) {
 }
 
 // src/routing/resolve.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { cwd } from "process";
 function resolveGenerationPlan(config, options) {
   const presetName = options.presetName ?? config.default_preset;
@@ -792,7 +1013,7 @@ function resolveGenerationPlan(config, options) {
       presetName,
       preset,
       modeName,
-      outputDirectory: options.outputDirectory ?? join3(cwd(), "outputs", "picgen"),
+      outputDirectory: options.outputDirectory ?? join4(cwd(), "outputs", "picgen"),
       referenceImages: options.referenceImages ?? []
     };
   }
@@ -992,6 +1213,140 @@ function inspectProviders(config) {
   });
 }
 
+// src/commands/update.ts
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname3, join as join5 } from "path";
+import { homedir as homedir3 } from "os";
+
+// src/version.ts
+var PACKAGE_NAME = "@ai-agent-tools/picgen";
+var VERSION = "0.1.0-alpha.10";
+
+// src/commands/update.ts
+var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+async function runUpdateCheck(options = {}) {
+  const result = await checkForUpdate({ force: true });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const message = formatUpdateMessage(result);
+  console.log(message ?? "PicGen is up to date.");
+}
+async function maybePrintUpdateHint() {
+  const result = await checkForUpdate({ force: false });
+  const message = formatUpdateMessage(result);
+  if (message) {
+    console.log("");
+    console.log(message);
+  }
+}
+async function checkForUpdate(options = {}) {
+  if (process.env.PICGEN_DISABLE_UPDATE_CHECK === "1") {
+    return {
+      checked: false,
+      disabled: true,
+      current_version: VERSION,
+      package_name: PACKAGE_NAME
+    };
+  }
+  try {
+    const cached = options.force ? void 0 : await readFreshCache();
+    const latestVersion = cached?.latest_version ?? await fetchLatestVersion();
+    const checkedAt = cached?.checked_at ?? (/* @__PURE__ */ new Date()).toISOString();
+    if (!cached) {
+      await writeCache({
+        checked_at: checkedAt,
+        latest_version: latestVersion
+      });
+    }
+    return {
+      checked: true,
+      current_version: VERSION,
+      latest_version: latestVersion,
+      update_available: isNewerVersion(latestVersion, VERSION),
+      package_name: PACKAGE_NAME,
+      checked_at: checkedAt
+    };
+  } catch (error) {
+    return {
+      checked: false,
+      current_version: VERSION,
+      package_name: PACKAGE_NAME,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function formatUpdateMessage(result) {
+  if (!result.checked || !result.update_available || !result.latest_version) {
+    return void 0;
+  }
+  return [
+    `PicGen update available: ${result.current_version} -> ${result.latest_version}`,
+    "Upgrade with:",
+    `  npm install -g ${result.package_name}@latest`
+  ].join("\n");
+}
+function isNewerVersion(candidate, current) {
+  const candidateParts = parseVersion(candidate);
+  const currentParts = parseVersion(current);
+  for (let index = 0; index < 3; index += 1) {
+    if (candidateParts.numbers[index] > currentParts.numbers[index]) return true;
+    if (candidateParts.numbers[index] < currentParts.numbers[index]) return false;
+  }
+  if (!candidateParts.prerelease && currentParts.prerelease) return true;
+  if (candidateParts.prerelease && !currentParts.prerelease) return false;
+  if (candidateParts.prerelease && currentParts.prerelease) {
+    return candidateParts.prerelease.localeCompare(currentParts.prerelease) > 0;
+  }
+  return false;
+}
+async function fetchLatestVersion() {
+  const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`);
+  if (!response.ok) {
+    throw new Error(`npm registry returned ${response.status} ${response.statusText}`.trim());
+  }
+  const body = await response.json();
+  const latest = body["dist-tags"]?.latest;
+  if (typeof latest !== "string" || !latest) {
+    throw new Error("npm registry response did not include dist-tags.latest.");
+  }
+  return latest;
+}
+async function readFreshCache() {
+  try {
+    const cache = JSON.parse(await readFile4(getUpdateCachePath(), "utf8"));
+    const checkedAt = Date.parse(cache.checked_at);
+    if (!Number.isFinite(checkedAt)) return void 0;
+    if (Date.now() - checkedAt > UPDATE_CACHE_TTL_MS) return void 0;
+    return cache;
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    return void 0;
+  }
+}
+async function writeCache(cache) {
+  const path = getUpdateCachePath();
+  await mkdir4(dirname3(path), { recursive: true });
+  await writeFile4(path, JSON.stringify(cache, null, 2), "utf8");
+}
+function getUpdateCachePath() {
+  if (process.env.PICGEN_UPDATE_CACHE_PATH) return process.env.PICGEN_UPDATE_CACHE_PATH;
+  return join5(homedir3(), ".picgen", "update-check.json");
+}
+function parseVersion(version) {
+  const [core, prerelease] = version.split("-", 2);
+  const numbers = core.split(".").map((part) => Number.parseInt(part, 10));
+  return {
+    numbers: [
+      Number.isFinite(numbers[0]) ? numbers[0] : 0,
+      Number.isFinite(numbers[1]) ? numbers[1] : 0,
+      Number.isFinite(numbers[2]) ? numbers[2] : 0
+    ],
+    prerelease
+  };
+}
+
 // src/commands/doctor.ts
 async function runDoctor(options) {
   const config = await loadConfig();
@@ -1002,6 +1357,7 @@ async function runDoctor(options) {
       JSON.stringify(
         {
           configured,
+          version: VERSION,
           config_path: getConfigPath(),
           default_preset: config.default_preset,
           default_mode: config.routing.default_mode,
@@ -1016,6 +1372,7 @@ async function runDoctor(options) {
     return;
   }
   console.log(`Config: ${getConfigPath()}`);
+  console.log(`Version: ${VERSION}`);
   console.log(`Default preset: ${config.default_preset}`);
   console.log(`Default mode: ${config.routing.default_mode}`);
   console.log(`Default provider: ${config.routing.default_provider}`);
@@ -1031,8 +1388,87 @@ async function runDoctor(options) {
     console.log("");
     console.log("No usable provider found. Run `picgen setup` or set the API key env vars above.");
   }
+  await maybePrintUpdateHint();
 }
 
+// src/commands/key.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { password } from "@inquirer/prompts";
+var execFileAsync = promisify(execFile);
+async function setApiKey(name, options) {
+  validateEnvName(name);
+  const value = options.clipboard ? await readClipboard() : options.stdin ? await readStdin() : options.value ? options.value : await password({
+    message: `Paste API key for ${name}`,
+    mask: "*"
+  });
+  if (!value.trim()) {
+    throw new Error("API key is empty.");
+  }
+  const path = await saveManagedEnvVar(name, value.trim());
+  console.log(`Saved ${name} to ${path}`);
+}
+async function listApiKeys(options) {
+  const config = await loadConfig();
+  const names = Object.values(config.providers).map((provider2) => provider2.api_key_env);
+  const inspections = await inspectEnvVars(names);
+  if (options.json) {
+    console.log(JSON.stringify(inspections, null, 2));
+    return;
+  }
+  for (const inspection of inspections) {
+    printInspection(inspection);
+  }
+}
+async function showApiKey(name, options) {
+  validateEnvName(name);
+  const inspection = await inspectEnvVar(name);
+  if (options.json) {
+    console.log(JSON.stringify(inspection, null, 2));
+    return;
+  }
+  printInspection(inspection);
+}
+function validateEnvName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid environment variable name: ${name}`);
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readClipboard() {
+  try {
+    const { stdout } = await execFileAsync("pbpaste");
+    return stdout;
+  } catch {
+    throw new Error("Could not read clipboard. Use --stdin or run picgen key set without flags.");
+  }
+}
+function printInspection(inspection) {
+  if (!inspection.set) {
+    console.log(`${inspection.name}: missing`);
+    return;
+  }
+  const location = inspection.path ? ` ${inspection.path}` : "";
+  console.log(
+    `${inspection.name}: set source=${inspection.source}${location} length=${inspection.length} preview=${inspection.preview} fingerprint=${inspection.fingerprint}`
+  );
+}
+
+// src/commands/open.ts
+import { createServer } from "http";
+import { randomBytes } from "crypto";
+import { execFile as execFile2 } from "child_process";
+import { readdir, readFile as readFile5, stat as stat2 } from "fs/promises";
+import { createReadStream } from "fs";
+import { extname as extname3, join as join6, resolve as resolve3 } from "path";
+import { cwd as cwd2 } from "process";
+
 // src/commands/provider.ts
 import { input, select } from "@inquirer/prompts";
 
@@ -1178,6 +1614,32 @@ async function addProvider() {
   await saveConfig(config);
   console.log(`Added provider: ${provider2.name}`);
 }
+async function quickAddProvider(templateName, options) {
+  const config = await loadConfig();
+  const template = quickProviderTemplate(templateName);
+  const name = options.name ?? nextAvailableProviderName(config, template.name);
+  const apiKeyEnv = options.keyEnv ?? nextAvailableProviderApiKeyEnv(config, template.api_key_env, name);
+  const provider2 = {
+    enabled: true,
+    protocol: template.protocol,
+    channel: template.channel,
+    base_url: normalizeProviderBaseUrl(options.host ?? template.base_url),
+    api_key_env: apiKeyEnv,
+    models: parseModels(options.models ?? template.models.join(",")),
+    capabilities: defaultCapabilitiesForProtocol2(template.protocol)
+  };
+  addProviderToConfig(config, name, provider2);
+  if (options.prefer) {
+    setPreferredProvider(config, name);
+  }
+  await saveConfig(config);
+  console.log(`Added provider: ${name}`);
+  console.log(`Protocol: ${provider2.protocol}`);
+  console.log(`Host: ${provider2.base_url}`);
+  console.log(`API key env: ${provider2.api_key_env}`);
+  console.log(`Models: ${provider2.models.join(",")}`);
+  if (options.prefer) console.log(`Preferred provider: ${name}`);
+}
 function addProviderToConfig(config, name, provider2) {
   config.providers[name] = provider2;
   const knownProviders = [config.routing.default_provider, ...config.routing.fallback_providers];
@@ -1274,7 +1736,11 @@ async function promptProvider(config, existingName, existing) {
   });
   const apiKeyEnv = await input({
     message: "API key environment variable",
-    default: existing?.api_key_env ?? (protocol === "openai-images" ? channel === "official" ? "OPENAI_API_KEY" : "PICGEN_OPENAI_PROXY_KEY" : channel === "official" ? "GEMINI_API_KEY" : "PICGEN_GEMINI_PROXY_KEY")
+    default: existing?.api_key_env ?? nextAvailableProviderApiKeyEnv(
+      config,
+      protocol === "openai-images" ? channel === "official" ? "OPENAI_API_KEY" : "PICGEN_OPENAI_PROXY_KEY" : channel === "official" ? "GEMINI_API_KEY" : "PICGEN_GEMINI_PROXY_KEY",
+      name
+    )
   });
   const defaultModels = protocol === "openai-images" ? "gpt-image-2" : "gemini-3.1-flash-image-preview,gemini-3-pro-image-preview";
   const modelsRaw = await input({
@@ -1304,6 +1770,562 @@ function nextAvailableProviderName(config, baseName, existingName) {
 function defaultCapabilitiesForProtocol2(protocol) {
   return protocol === "gemini" ? ["text-to-image", "reference-image"] : ["text-to-image"];
 }
+function quickProviderTemplate(templateName) {
+  switch (templateName.replaceAll("_", "-")) {
+    case "openai-proxy":
+      return {
+        name: "openai_proxy",
+        protocol: "openai-images",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "PICGEN_OPENAI_PROXY_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini-proxy":
+      return {
+        name: "gemini_proxy",
+        protocol: "gemini",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "PICGEN_GEMINI_PROXY_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+    case "openai-official":
+      return {
+        name: "openai_official",
+        protocol: "openai-images",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("openai-images"),
+        api_key_env: "OPENAI_API_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini-official":
+      return {
+        name: "gemini_official",
+        protocol: "gemini",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("gemini"),
+        api_key_env: "GEMINI_API_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+    default:
+      throw new Error(
+        `Unknown provider template: ${templateName}. Use openai-proxy, gemini-proxy, openai-official, or gemini-official.`
+      );
+  }
+}
+function parseModels(raw) {
+  return raw.split(",").map((model) => model.trim()).filter(Boolean);
+}
+
+// src/commands/open.ts
+var DEFAULT_PORT = 8188;
+var MAX_PORT_ATTEMPTS = 30;
+async function runOpen(options) {
+  const token = randomBytes(24).toString("hex");
+  const port = await listenOnAvailablePort(Number(options.port ?? DEFAULT_PORT), token);
+  const url = `http://127.0.0.1:${port}/?token=${token}`;
+  console.log(`PicGen is open: ${url}`);
+  console.log("Keep this terminal running while using PicGen. Press Ctrl+C to close.");
+  if (options.open !== false) {
+    await openBrowser(url);
+  }
+}
+async function listenOnAvailablePort(startPort, token) {
+  for (let offset = 0; offset < MAX_PORT_ATTEMPTS; offset += 1) {
+    const port = startPort + offset;
+    const server = createServer((request, response) => {
+      handleRequest(request, response, token).catch((error) => {
+        sendJson(response, 500, {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    });
+    const result = await tryListen(server, port);
+    if (result) return port;
+  }
+  throw new Error(`Could not find an available port starting at ${startPort}.`);
+}
+function tryListen(server, port) {
+  return new Promise((resolveListen, reject) => {
+    server.once("error", (error) => {
+      if (error.code === "EADDRINUSE") {
+        resolveListen(false);
+        return;
+      }
+      reject(error);
+    });
+    server.listen(port, "127.0.0.1", () => resolveListen(true));
+  });
+}
+async function handleRequest(request, response, token) {
+  const url = new URL(request.url ?? "/", "http://127.0.0.1");
+  if (url.pathname === "/" || url.pathname === "/index.html") {
+    if (url.searchParams.get("token") !== token) {
+      sendText(response, 403, "Invalid PicGen session token.");
+      return;
+    }
+    sendHtml(response, appHtml);
+    return;
+  }
+  if (!isAuthorized(request, url, token)) {
+    sendJson(response, 403, { ok: false, error: "Invalid PicGen session token." });
+    return;
+  }
+  if (request.method === "GET" && url.pathname === "/api/state") {
+    sendJson(response, 200, await buildState());
+    return;
+  }
+  if (request.method === "POST" && url.pathname === "/api/providers") {
+    sendJson(response, 200, await addProviderFromBody(await readJson(request)));
+    return;
+  }
+  const providerTestMatch = /^\/api\/providers\/([^/]+)\/test$/.exec(url.pathname);
+  if (request.method === "POST" && providerTestMatch) {
+    const config = await loadConfig();
+    const name = decodeURIComponent(providerTestMatch[1]);
+    const provider2 = config.providers[name];
+    if (!provider2) throw new Error(`Unknown provider: ${name}`);
+    sendJson(response, 200, await testProvider(name, provider2));
+    return;
+  }
+  const providerDefaultMatch = /^\/api\/providers\/([^/]+)\/default$/.exec(url.pathname);
+  if (request.method === "POST" && providerDefaultMatch) {
+    const config = await loadConfig();
+    const name = decodeURIComponent(providerDefaultMatch[1]);
+    setPreferredProvider(config, name);
+    await saveConfig(config);
+    sendJson(response, 200, await buildState());
+    return;
+  }
+  const providerMatch = /^\/api\/providers\/([^/]+)$/.exec(url.pathname);
+  if (providerMatch) {
+    const name = decodeURIComponent(providerMatch[1]);
+    if (request.method === "PATCH") {
+      sendJson(response, 200, await patchProvider(name, await readJson(request)));
+      return;
+    }
+    if (request.method === "DELETE") {
+      sendJson(response, 200, await deleteProvider(name));
+      return;
+    }
+  }
+  if (request.method === "POST" && url.pathname === "/api/key") {
+    const body = await readJson(request);
+    if (typeof body.name !== "string" || typeof body.value !== "string") {
+      throw new Error("Key name and value are required.");
+    }
+    await saveManagedEnvVar(body.name, body.value);
+    sendJson(response, 200, { ok: true, state: await buildState() });
+    return;
+  }
+  const keyMatch = /^\/api\/key\/([^/]+)$/.exec(url.pathname);
+  if (request.method === "GET" && keyMatch) {
+    const name = decodeURIComponent(keyMatch[1]);
+    sendJson(response, 200, { ok: true, value: await readEnvVarValue(name) });
+    return;
+  }
+  if (request.method === "POST" && url.pathname === "/api/plan") {
+    sendJson(response, 200, await planGeneration(await readJson(request)));
+    return;
+  }
+  if (request.method === "POST" && url.pathname === "/api/generate") {
+    sendJson(response, 200, await generate(await readJson(request)));
+    return;
+  }
+  if (request.method === "GET" && url.pathname === "/api/history") {
+    sendJson(response, 200, { ok: true, runs: await listHistory() });
+    return;
+  }
+  if (request.method === "GET" && url.pathname === "/api/file") {
+    await sendOutputFile(response, url.searchParams.get("path"));
+    return;
+  }
+  sendJson(response, 404, { ok: false, error: "Not found." });
+}
+function isAuthorized(request, url, token) {
+  return request.headers["x-picgen-token"] === token || url.searchParams.get("token") === token;
+}
+async function buildState() {
+  const config = await loadConfig();
+  const keyInspections = await inspectEnvVars(
+    Object.values(config.providers).map((provider2) => provider2.api_key_env)
+  );
+  const keys = Object.fromEntries(keyInspections.map((key2) => [key2.name, key2]));
+  return {
+    ok: true,
+    config_path: getConfigPath(),
+    key_file_path: getManagedEnvPath(),
+    default_provider: config.routing.default_provider,
+    fallback_providers: config.routing.fallback_providers,
+    default_preset: config.default_preset,
+    default_mode: config.routing.default_mode,
+    providers: Object.entries(config.providers).map(([name, provider2]) => ({
+      name,
+      ...provider2,
+      key: keys[provider2.api_key_env],
+      preference: name === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(name) ? "fallback" : "manual"
+    })),
+    presets: config.presets,
+    modes: config.modes
+  };
+}
+async function addProviderFromBody(body) {
+  const config = await loadConfig();
+  const protocol = body.protocol === "gemini" ? "gemini" : "openai-images";
+  const channel = body.channel === "official" ? "official" : "third_party";
+  const template = defaultProviderTemplate(protocol, channel);
+  const name = typeof body.name === "string" && body.name.trim() ? body.name.trim() : nextAvailableProviderName(config, template.name);
+  const apiKeyEnv = typeof body.api_key_env === "string" && body.api_key_env.trim() ? body.api_key_env.trim() : nextAvailableProviderApiKeyEnv(config, template.api_key_env, name);
+  const models = typeof body.models === "string" && body.models.trim() ? parseModels2(body.models) : template.models;
+  const provider2 = {
+    enabled: true,
+    protocol,
+    channel,
+    base_url: normalizeProviderBaseUrl(String(body.base_url ?? template.base_url)),
+    api_key_env: apiKeyEnv,
+    models,
+    capabilities: defaultCapabilitiesForProtocol2(protocol)
+  };
+  addProviderToConfig(config, name, provider2);
+  if (body.prefer === true || !config.providers[config.routing.default_provider]) {
+    setPreferredProvider(config, name);
+  }
+  await saveConfig(config);
+  if (typeof body.api_key === "string" && body.api_key.trim()) {
+    await saveManagedEnvVar(apiKeyEnv, body.api_key.trim());
+  }
+  return { ok: true, state: await buildState() };
+}
+async function patchProvider(name, body) {
+  const config = await loadConfig();
+  const provider2 = config.providers[name];
+  if (!provider2) throw new Error(`Unknown provider: ${name}`);
+  if (typeof body.enabled === "boolean") provider2.enabled = body.enabled;
+  if (typeof body.base_url === "string") provider2.base_url = normalizeProviderBaseUrl(body.base_url);
+  if (typeof body.models === "string") provider2.models = parseModels2(body.models);
+  if (typeof body.api_key === "string" && body.api_key.trim()) {
+    await saveManagedEnvVar(provider2.api_key_env, body.api_key.trim());
+  }
+  await saveConfig(config);
+  return { ok: true, state: await buildState() };
+}
+async function deleteProvider(name) {
+  const config = await loadConfig();
+  if (!config.providers[name]) throw new Error(`Unknown provider: ${name}`);
+  delete config.providers[name];
+  config.routing.fallback_providers = config.routing.fallback_providers.filter((item) => item !== name);
+  if (config.routing.default_provider === name) {
+    const nextDefault = config.routing.fallback_providers[0] ?? Object.keys(config.providers)[0];
+    if (nextDefault) {
+      config.routing.default_provider = nextDefault;
+      config.routing.fallback_providers = config.routing.fallback_providers.filter(
+        (item) => item !== nextDefault
+      );
+    }
+  }
+  await saveConfig(config);
+  return { ok: true, state: await buildState() };
+}
+async function planGeneration(body) {
+  const config = await loadConfig();
+  const plan = resolveGenerationPlan(config, {
+    prompt: String(body.prompt ?? "").trim(),
+    presetName: asOptionalString(body.preset),
+    providerName: asOptionalString(body.provider),
+    modeName: asOptionalString(body.mode),
+    model: asOptionalString(body.model),
+    outputDirectory: asOptionalString(body.output_directory)
+  });
+  return {
+    ok: true,
+    dry_run: true,
+    provider_called: false,
+    plan: toPlanOutput(plan)
+  };
+}
+async function generate(body) {
+  const config = await loadConfig();
+  const plan = resolveGenerationPlan(config, {
+    prompt: String(body.prompt ?? "").trim(),
+    presetName: asOptionalString(body.preset),
+    providerName: asOptionalString(body.provider),
+    modeName: asOptionalString(body.mode),
+    model: asOptionalString(body.model),
+    outputDirectory: asOptionalString(body.output_directory)
+  });
+  const run = await createGenerationRun(plan);
+  const runtimePlan = { ...plan, outputDirectory: run.outputDirectory };
+  const runtimePlanOutput = toPlanOutput(runtimePlan);
+  await writeGenerationMetadata(run, {
+    plan: runtimePlanOutput,
+    run: {
+      id: run.id,
+      output_directory: run.outputDirectory,
+      metadata_path: run.metadataPath,
+      prompt_path: run.promptPath
+    }
+  });
+  const adapter = getAdapter(plan.provider.protocol);
+  try {
+    const result = await adapter.generate(runtimePlan, run);
+    await writeGenerationMetadata(run, {
+      plan: runtimePlanOutput,
+      run: {
+        id: run.id,
+        output_directory: run.outputDirectory,
+        metadata_path: run.metadataPath,
+        prompt_path: run.promptPath
+      },
+      provider_response: result.provider_response,
+      images: result.images
+    });
+    return {
+      ok: true,
+      output_dir: run.outputDirectory,
+      metadata_path: run.metadataPath,
+      images: result.images
+    };
+  } catch (error) {
+    await writeGenerationMetadata(run, {
+      plan: runtimePlanOutput,
+      run: {
+        id: run.id,
+        output_directory: run.outputDirectory,
+        metadata_path: run.metadataPath,
+        prompt_path: run.promptPath
+      },
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+        name: error instanceof Error ? error.name : void 0
+      }
+    });
+    throw error;
+  }
+}
+async function listHistory() {
+  const baseDir = resolve3(cwd2(), "outputs", "picgen");
+  const dates = await safeReaddir(baseDir);
+  const runs = [];
+  for (const date of dates) {
+    const datePath = join6(baseDir, date);
+    if (!await isDirectory(datePath)) continue;
+    for (const runName of await safeReaddir(datePath)) {
+      const runPath = join6(datePath, runName);
+      if (!await isDirectory(runPath)) continue;
+      const metadataPath = join6(runPath, "metadata.json");
+      const promptPath = join6(runPath, "prompt.txt");
+      const metadata = await readJsonFile(metadataPath);
+      const prompt = await readTextFile(promptPath);
+      const images = (metadata?.images ?? []).filter((image) => image.path).map((image) => ({
+        ...image,
+        url: `/api/file?path=${encodeURIComponent(image.path)}`
+      }));
+      const info = await stat2(runPath);
+      runs.push({
+        id: runName,
+        date,
+        created_at: info.mtime.toISOString(),
+        output_dir: runPath,
+        metadata_path: metadataPath,
+        prompt,
+        plan: metadata?.plan,
+        images
+      });
+    }
+  }
+  return runs.sort((a, b) => String(b.created_at).localeCompare(String(a.created_at))).slice(0, 60);
+}
+async function sendOutputFile(response, path) {
+  if (!path) {
+    sendJson(response, 400, { ok: false, error: "Missing file path." });
+    return;
+  }
+  const resolved = resolve3(path);
+  const allowedRoot = resolve3(cwd2(), "outputs", "picgen");
+  if (!resolved.startsWith(`${allowedRoot}/`)) {
+    sendJson(response, 403, { ok: false, error: "File is outside PicGen outputs." });
+    return;
+  }
+  const extension = extname3(resolved).toLowerCase();
+  const mimeType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".webp" ? "image/webp" : extension === ".png" ? "image/png" : "application/octet-stream";
+  response.writeHead(200, {
+    "Content-Type": mimeType,
+    "Cache-Control": "no-store"
+  });
+  createReadStream(resolved).pipe(response);
+}
+function defaultProviderTemplate(protocol, channel) {
+  if (protocol === "gemini") {
+    return {
+      name: channel === "official" ? "gemini_official" : "gemini_proxy",
+      base_url: channel === "official" ? "https://generativelanguage.googleapis.com" : "https://www.pandai.vip",
+      api_key_env: channel === "official" ? "GEMINI_API_KEY" : "PICGEN_GEMINI_PROXY_KEY",
+      models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+    };
+  }
+  return {
+    name: channel === "official" ? "openai_official" : "openai_proxy",
+    base_url: channel === "official" ? "https://api.openai.com" : "https://www.pandai.vip",
+    api_key_env: channel === "official" ? "OPENAI_API_KEY" : "PICGEN_OPENAI_PROXY_KEY",
+    models: ["gpt-image-2"]
+  };
+}
+function parseModels2(raw) {
+  return raw.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function asOptionalString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+async function readJson(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text.trim()) return {};
+  return JSON.parse(text);
+}
+async function safeReaddir(path) {
+  try {
+    return await readdir(path);
+  } catch {
+    return [];
+  }
+}
+async function isDirectory(path) {
+  try {
+    return (await stat2(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function readJsonFile(path) {
+  try {
+    return JSON.parse(await readFile5(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function readTextFile(path) {
+  try {
+    return await readFile5(path, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+function sendJson(response, status, value) {
+  response.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store"
+  });
+  response.end(JSON.stringify(value, null, 2));
+}
+function sendHtml(response, value) {
+  response.writeHead(200, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store"
+  });
+  response.end(value);
+}
+function sendText(response, status, value) {
+  response.writeHead(status, {
+    "Content-Type": "text/plain; charset=utf-8",
+    "Cache-Control": "no-store"
+  });
+  response.end(value);
+}
+async function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  await new Promise((resolveOpen) => {
+    execFile2(command, args, () => resolveOpen());
+  });
+}
+var appHtml = `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>PicGen</title>
+  <style>
+    :root{--bg:#f6f7f9;--panel:#fff;--text:#17202a;--muted:#667085;--border:#d9dee7;--soft:#eef2f6;--accent:#2563eb;--accent2:#0f766e;--danger:#b42318;--ok:#087443;--warn:#b54708;--radius:8px}
+    *{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:14px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}button,input,select,textarea{font:inherit}button{border:1px solid var(--border);background:#fff;color:var(--text);border-radius:7px;padding:7px 10px;cursor:pointer}button.primary{background:var(--accent);border-color:var(--accent);color:#fff}button.ghost{background:transparent}button.danger{color:var(--danger)}button:disabled{opacity:.55;cursor:not-allowed}input,select,textarea{width:100%;border:1px solid var(--border);border-radius:7px;padding:8px 9px;background:#fff;color:var(--text)}textarea{min-height:120px;resize:vertical}.wrap{max-width:1120px;margin:0 auto;padding:22px}.top{display:flex;align-items:flex-start;justify-content:space-between;gap:16px;margin-bottom:12px}.brand h1{font-size:22px;margin:0 0 3px}.brand p,.muted{color:var(--muted);margin:0}.notice{border:1px solid #bfdbfe;background:#eff6ff;color:#1e3a8a;border-radius:var(--radius);padding:10px 12px;margin-bottom:16px}.tabs{display:flex;gap:6px;margin-bottom:16px;border-bottom:1px solid var(--border)}.tab{border:0;border-radius:7px 7px 0 0;background:transparent;padding:9px 12px}.tab.active{background:#fff;border:1px solid var(--border);border-bottom-color:#fff;margin-bottom:-1px}.grid{display:grid;gap:14px}.cols{display:grid;grid-template-columns:1fr 360px;gap:14px}.panel{background:var(--panel);border:1px solid var(--border);border-radius:var(--radius);padding:14px}.panel h2{font-size:15px;margin:0 0 12px}.row{display:grid;grid-template-columns:150px 1fr;gap:10px;align-items:center;margin:9px 0}.actions{display:flex;gap:8px;flex-wrap:wrap}.provider{display:grid;grid-template-columns:1fr auto;gap:12px;border:1px solid var(--border);border-radius:var(--radius);padding:12px;background:#fff}.provider+.provider{margin-top:10px}.title{font-weight:650}.badges{display:flex;gap:6px;flex-wrap:wrap;margin-top:6px}.badge{display:inline-flex;align-items:center;border-radius:999px;background:var(--soft);color:#344054;font-size:12px;padding:2px 8px}.badge.ok{background:#dcfae6;color:var(--ok)}.badge.warn{background:#fef0c7;color:var(--warn)}.badge.default{background:#dbeafe;color:#1d4ed8}.keyline{margin-top:8px;color:var(--muted)}.keyline code,.path{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:#f2f4f7;border-radius:5px;padding:2px 5px}.source{display:inline-flex;align-items:center;border-radius:5px;padding:2px 6px;background:#ecfdf3;color:#067647;font-size:12px;margin-left:4px}.source.project{background:#fff7ed;color:#9a3412}.source.shell{background:#eef4ff;color:#3538cd}.source.missing{background:#fef3f2;color:#b42318}.hint{margin-top:8px;color:var(--muted);font-size:12px}.warning{margin-top:8px;color:var(--warn);font-size:12px}.icon-btn{display:inline-flex;align-items:center;justify-content:center;width:31px;height:31px;padding:0;vertical-align:middle}.icon-btn svg{width:16px;height:16px;stroke:currentColor}.formgrid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:10px}.full{grid-column:1/-1}.plan{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;white-space:pre-wrap;background:#f8fafc;border:1px solid var(--border);border-radius:var(--radius);padding:10px}.gallery{display:grid;grid-template-columns:repeat(auto-fill,minmax(180px,1fr));gap:12px}.run img,.result img{width:100%;height:150px;object-fit:contain;background:#f8fafc;border:1px solid var(--border);border-radius:var(--radius)}.run{background:#fff;border:1px solid var(--border);border-radius:var(--radius);padding:10px}.hidden{display:none}.toast{position:fixed;right:18px;bottom:18px;background:#111827;color:#fff;border-radius:8px;padding:10px 12px;max-width:360px}.small{font-size:12px}.split{display:flex;justify-content:space-between;gap:8px;align-items:center}@media(max-width:860px){.cols{grid-template-columns:1fr}.row{grid-template-columns:1fr}.formgrid{grid-template-columns:1fr}.provider{grid-template-columns:1fr}.top{display:block}.wrap{padding:14px}}
+  </style>
+</head>
+<body>
+  <main class="wrap">
+    <div class="top">
+      <div class="brand"><h1>PicGen</h1><p>\u672C\u5730\u751F\u56FE\u5DE5\u4F5C\u53F0</p></div>
+      <div class="actions"><button id="refresh">\u5237\u65B0</button></div>
+    </div>
+    <div class="notice">\u8FD9\u662F\u672C\u673A\u4E34\u65F6\u9875\u9762\uFF0C\u53EA\u7ED1\u5B9A 127.0.0.1\u3002\u4F7F\u7528\u5B8C\u53EF\u4EE5\u5173\u95ED\u9875\u9762\uFF0C\u5E76\u5728\u542F\u52A8 PicGen \u7684\u7EC8\u7AEF\u6309 Ctrl+C \u9000\u51FA\u670D\u52A1\u3002</div>
+    <nav class="tabs">
+      <button class="tab active" data-tab="settings">\u914D\u7F6E</button>
+      <button class="tab" data-tab="generate">\u751F\u6210</button>
+      <button class="tab" data-tab="history">\u5386\u53F2</button>
+    </nav>
+    <section id="settings" class="grid"></section>
+    <section id="generate" class="hidden"></section>
+    <section id="history" class="hidden grid"></section>
+  </main>
+  <div id="toast" class="toast hidden"></div>
+  <script>
+    const token = new URLSearchParams(location.search).get('token');
+    const headers = {'Content-Type':'application/json','x-picgen-token':token};
+    const state = {data:null,plan:null};
+    const $ = (s,p=document)=>p.querySelector(s);
+    const esc = v => String(v ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+    function toast(msg){const el=$('#toast');el.textContent=msg;el.classList.remove('hidden');setTimeout(()=>el.classList.add('hidden'),3500)}
+    async function api(path, opts={}){const res=await fetch(path,{...opts,headers:{...headers,...opts.headers}});const data=await res.json().catch(()=>({ok:false,error:'Invalid JSON'}));if(!res.ok||data.ok===false)throw new Error(data.error||data.message||res.statusText);return data}
+    async function load(){state.data=await api('/api/state');renderSettings();renderGenerate();await renderHistory()}
+    function tab(name){document.querySelectorAll('.tab').forEach(b=>b.classList.toggle('active',b.dataset.tab===name));['settings','generate','history'].forEach(id=>$('#'+id).classList.toggle('hidden',id!==name))}
+    document.querySelectorAll('.tab').forEach(b=>b.onclick=()=>tab(b.dataset.tab));$('#refresh').onclick=()=>load().then(()=>toast('\u5DF2\u5237\u65B0')).catch(e=>toast(e.message));
+    const labels={default:'\u9ED8\u8BA4',fallback:'\u5907\u7528',manual:'\u624B\u52A8',official:'\u5B98\u65B9',third_party:'\u7B2C\u4E09\u65B9','openai-images':'OpenAI \u517C\u5BB9',gemini:'Gemini',enabled:'\u5DF2\u542F\u7528',disabled:'\u5DF2\u505C\u7528',shell:'\u7EC8\u7AEF\u73AF\u5883\u53D8\u91CF',project:'\u5F53\u524D\u9879\u76EE .env',managed:'PicGen \u7BA1\u7406\u6587\u4EF6',missing:'\u672A\u914D\u7F6E'};
+    const eyeIcon='<svg viewBox="0 0 24 24" fill="none" stroke-width="2"><path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12Z"/><circle cx="12" cy="12" r="3"/></svg>';
+    const eyeOffIcon='<svg viewBox="0 0 24 24" fill="none" stroke-width="2"><path d="m2 2 20 20"/><path d="M10.6 10.6A3 3 0 0 0 13.4 13.4"/><path d="M9.9 4.2A10.4 10.4 0 0 1 12 4.0c6.5 0 10 8 10 8a17.8 17.8 0 0 1-2.3 3.5"/><path d="M6.6 6.6C3.6 8.7 2 12 2 12s3.5 8 10 8c1.6 0 3-.3 4.2-.9"/></svg>';
+    function label(v){return labels[v]||v}
+    function keySource(key){return key?.set?label(key.source):'\u672A\u914D\u7F6E'}
+    function templateDefaults(template){return {gemini_proxy:{protocol:'gemini',channel:'third_party',name:'gemini_proxy',host:'https://www.pandai.vip',models:'gemini-3.1-flash-image-preview, gemini-3-pro-image-preview'},openai_proxy:{protocol:'openai-images',channel:'third_party',name:'openai_proxy',host:'https://www.pandai.vip',models:'gpt-image-2'},gemini_official:{protocol:'gemini',channel:'official',name:'gemini_official',host:'https://generativelanguage.googleapis.com',models:'gemini-3.1-flash-image-preview, gemini-3-pro-image-preview'},openai_official:{protocol:'openai-images',channel:'official',name:'openai_official',host:'https://api.openai.com',models:'gpt-image-2'}}[template]}
+    function renderSettings(){const s=state.data;$('#settings').innerHTML=\`
+      <div class="panel"><h2>\u8DEF\u5F84</h2><div class="row"><div>\u914D\u7F6E\u6587\u4EF6</div><div class="path">\${esc(s.config_path)}</div></div><div class="row"><div>PicGen \u5BC6\u94A5\u6587\u4EF6</div><div class="path">\${esc(s.key_file_path)}</div></div><p class="hint">key \u8BFB\u53D6\u4F18\u5148\u7EA7\uFF1A\u7EC8\u7AEF\u73AF\u5883\u53D8\u91CF &gt; \u5F53\u524D\u9879\u76EE .env &gt; PicGen \u7BA1\u7406\u6587\u4EF6\u3002</p></div>
+      <div class="panel"><div class="split"><h2>\u6E20\u9053</h2><button class="primary" id="addProviderBtn">\u6DFB\u52A0\u6E20\u9053</button></div>
+      <div class="hidden" id="providerForm" style="margin:12px 0 14px"><h2>\u6DFB\u52A0\u6E20\u9053</h2>
+        <div class="formgrid">
+          <label class="full">\u6E20\u9053\u7C7B\u578B<select id="newTemplate"><option value="gemini_proxy">\u7B2C\u4E09\u65B9 Gemini</option><option value="openai_proxy">\u7B2C\u4E09\u65B9 OpenAI \u517C\u5BB9</option><option value="gemini_official">\u5B98\u65B9 Gemini</option><option value="openai_official">\u5B98\u65B9 OpenAI</option></select></label>
+          <label>\u540D\u79F0<input id="newName" placeholder="\u81EA\u52A8"></label>
+          <label>Host<input id="newHost" value="https://www.pandai.vip"></label>
+          <label class="full">API key<input id="newKey" type="password" placeholder="\u4FDD\u5B58\u5728\u672C\u673A\uFF0C\u4E0D\u5199\u5165\u804A\u5929"></label>
+          <p class="hint full">\u6BCF\u4E2A\u65B0\u6E20\u9053\u4F1A\u81EA\u52A8\u5206\u914D\u72EC\u7ACB\u7684 key \u540D\u79F0\uFF0C\u907F\u514D\u591A\u4E2A\u6E20\u9053\u4E92\u76F8\u8986\u76D6\u3002</p>
+          <label class="full">\u6A21\u578B\u5217\u8868<input id="newModels" placeholder="\u4F7F\u7528\u63A8\u8350\u9ED8\u8BA4\u503C"></label>
+          <label><input id="newPrefer" type="checkbox" checked style="width:auto"> \u8BBE\u4E3A\u9ED8\u8BA4\u6E20\u9053</label>
+          <div class="actions"><button class="primary" id="saveProvider">\u4FDD\u5B58\u6E20\u9053</button><button id="cancelProvider">\u53D6\u6D88</button></div>
+        </div>
+      </div><div id="providers"></div></div>\`;
+      $('#addProviderBtn').onclick=()=>{const form=$('#providerForm');form.classList.remove('hidden');form.scrollIntoView({block:'nearest'});};$('#cancelProvider').onclick=()=>$('#providerForm').classList.add('hidden');$('#saveProvider').onclick=saveProvider;$('#newTemplate').onchange=applyProviderTemplate;applyProviderTemplate();
+      $('#providers').innerHTML=s.providers.map(providerCard).join('') || '<p class="muted">\u8FD8\u6CA1\u6709\u914D\u7F6E\u6E20\u9053\u3002</p>';
+      bindProviderActions();
+    }
+    function providerCard(p){const key=p.key||{set:false};const source=key.set?\`<span class="source \${esc(key.source)}">\${esc(keySource(key))}</span>\`:'<span class="source missing">\u672A\u914D\u7F6E</span>';const sourcePath=key.path?\`<div class="keyline small">\u6765\u6E90\u8DEF\u5F84 <span class="path">\${esc(key.path)}</span></div>\`:'';const officialHint=p.channel==='official'?'<div class="warning">\u5B98\u65B9\u6E20\u9053\u901A\u5E38\u9700\u8981\u5B98\u65B9 API key\uFF1B\u5982\u679C\u8FD9\u91CC\u653E\u7684\u662F\u7B2C\u4E09\u65B9\u6E20\u9053 key\uFF0C\u6D4B\u8BD5\u53EF\u80FD\u5931\u8D25\u3002</div>':'';return \`<div class="provider"><div><div class="title">\${esc(p.name)}</div><div class="badges"><span class="badge \${p.preference==='default'?'default':''}">\${esc(label(p.preference))}</span><span class="badge">\${esc(label(p.protocol))}</span><span class="badge">\${esc(label(p.channel))}</span><span class="badge \${p.enabled?'ok':'warn'}">\${p.enabled?'\u5DF2\u542F\u7528':'\u5DF2\u505C\u7528'}</span></div><div class="keyline">\${esc(p.base_url)}</div><div class="keyline">Key <code>\${esc(p.api_key_env)}</code>: \${key.set?\`<code data-key-preview="\${esc(p.api_key_env)}">\${esc(key.preview)}</code> <button class="icon-btn" title="\u663E\u793A\u5B8C\u6574 key" aria-label="\u663E\u793A\u5B8C\u6574 key" data-reveal="\${esc(p.api_key_env)}" data-visible="false">\${eyeIcon}</button>\`:'\u672A\u914D\u7F6E'} \${source} \${key.fingerprint?'<span class="small">fingerprint '+esc(key.fingerprint)+'</span>':''}</div>\${sourcePath}\${officialHint}</div><div class="actions"><button data-test="\${esc(p.name)}">\u6D4B\u8BD5</button><button data-default="\${esc(p.name)}">\u8BBE\u4E3A\u9ED8\u8BA4</button><button data-toggle="\${esc(p.name)}">\${p.enabled?'\u505C\u7528':'\u542F\u7528'}</button><button class="danger" data-delete="\${esc(p.name)}">\u79FB\u9664</button></div></div>\`}
+    function bindProviderActions(){document.querySelectorAll('[data-test]').forEach(b=>b.onclick=()=>testProvider(b.dataset.test));document.querySelectorAll('[data-default]').forEach(b=>b.onclick=()=>post('/api/providers/'+encodeURIComponent(b.dataset.default)+'/default',{}));document.querySelectorAll('[data-toggle]').forEach(b=>{const p=state.data.providers.find(x=>x.name===b.dataset.toggle);b.onclick=()=>patch('/api/providers/'+encodeURIComponent(p.name),{enabled:!p.enabled})});document.querySelectorAll('[data-delete]').forEach(b=>b.onclick=()=>confirm('\u786E\u8BA4\u79FB\u9664\u8FD9\u4E2A\u6E20\u9053\uFF1F')&&del('/api/providers/'+encodeURIComponent(b.dataset.delete)));document.querySelectorAll('[data-reveal]').forEach(b=>b.onclick=()=>toggleKey(b.dataset.reveal,b))}
+    function applyProviderTemplate(){const t=templateDefaults($('#newTemplate').value);$('#newName').placeholder=t.name;$('#newHost').value=t.host;$('#newModels').placeholder=t.models}
+    async function saveProvider(){const t=templateDefaults($('#newTemplate').value);await post('/api/providers',{protocol:t.protocol,channel:t.channel,name:$('#newName').value,base_url:$('#newHost').value,api_key:$('#newKey').value,models:$('#newModels').value,prefer:$('#newPrefer').checked});$('#providerForm').classList.add('hidden');toast('\u6E20\u9053\u5DF2\u4FDD\u5B58')}
+    async function testProvider(name){const r=await api('/api/providers/'+encodeURIComponent(name)+'/test',{method:'POST'});toast((r.ok?'\u6D4B\u8BD5\u901A\u8FC7\uFF1A':'\u6D4B\u8BD5\u5931\u8D25\uFF1A')+r.message)}
+    async function toggleKey(name,btn){const slot=document.querySelector('[data-key-preview="'+CSS.escape(name)+'"]');if(btn.dataset.visible==='true'){const key=state.data.providers.find(p=>p.api_key_env===name)?.key;slot.textContent=key?.preview||'';btn.dataset.visible='false';btn.title='\u663E\u793A\u5B8C\u6574 key';btn.setAttribute('aria-label','\u663E\u793A\u5B8C\u6574 key');btn.innerHTML=eyeIcon;return}const r=await api('/api/key/'+encodeURIComponent(name));slot.textContent=r.value||'';btn.dataset.visible='true';btn.title='\u9690\u85CF key';btn.setAttribute('aria-label','\u9690\u85CF key');btn.innerHTML=eyeOffIcon}
+    async function post(path,body){await api(path,{method:'POST',body:JSON.stringify(body)});await load()}
+    async function patch(path,body){await api(path,{method:'PATCH',body:JSON.stringify(body)});await load()}
+    async function del(path){await api(path,{method:'DELETE'});await load()}
+    function renderGenerate(){const s=state.data;const prefs=JSON.parse(localStorage.getItem('picgen:prefs')||'{}');$('#generate').innerHTML=\`<div class="cols"><div class="panel"><h2>\u751F\u6210\u56FE\u7247</h2><label>\u63D0\u793A\u8BCD<textarea id="prompt">\${esc(prefs.prompt||'\u4E00\u5F20\u7B80\u6D01\u7684 PicGen \u6D4B\u8BD5\u56FE\uFF0C\u767D\u8272\u80CC\u666F\uFF0C\u5C11\u91CF\u84DD\u7EFF\u8272\u79D1\u6280\u611F\u70B9\u7F00')}</textarea></label><div class="formgrid"><label>\u6E20\u9053<select id="genProvider"><option value="">\u81EA\u52A8\u9009\u62E9</option>\${s.providers.map(p=>'<option value="'+esc(p.name)+'" '+(prefs.provider===p.name?'selected':'')+'>'+esc(p.name)+'</option>').join('')}</select></label><label>\u9884\u8BBE<select id="genPreset">\${Object.keys(s.presets).map(p=>'<option '+((prefs.preset||'fast-draft')===p?'selected':'')+'>'+esc(p)+'</option>').join('')}</select></label><label>\u6A21\u578B<input id="genModel" value="\${esc(prefs.model||'')}" placeholder="\u53EF\u9009"></label><label>\u6A21\u5F0F<input id="genMode" value="\${esc(prefs.mode||'')}" placeholder="\u53EF\u9009"></label></div><div class="actions" style="margin-top:12px"><button id="preview" class="primary">\u9884\u89C8\u65B9\u6848</button><button id="generateBtn" disabled>\u5F00\u59CB\u751F\u6210</button></div></div><div class="panel"><h2>\u65B9\u6848 / \u7ED3\u679C</h2><div id="plan" class="plan">\u8FD8\u6CA1\u6709\u9884\u89C8\u3002</div><div id="result" class="result" style="margin-top:12px"></div></div></div>\`;$('#preview').onclick=preview;$('#generateBtn').onclick=generateNow}
+    function genBody(){const body={prompt:$('#prompt').value,preset:$('#genPreset').value,provider:$('#genProvider').value,model:$('#genModel').value,mode:$('#genMode').value};localStorage.setItem('picgen:prefs',JSON.stringify(body));return body}
+    async function preview(){const r=await api('/api/plan',{method:'POST',body:JSON.stringify(genBody())});state.plan=r.plan;$('#plan').textContent=JSON.stringify(r.plan,null,2);$('#generateBtn').disabled=false}
+    async function generateNow(){if(!state.plan&&!confirm('\u8FD8\u6CA1\u6709\u9884\u89C8\u65B9\u6848\uFF0C\u786E\u5B9A\u76F4\u63A5\u751F\u6210\uFF1F'))return;$('#generateBtn').disabled=true;$('#result').innerHTML='<p class="muted">\u6B63\u5728\u751F\u6210...</p>';try{const r=await api('/api/generate',{method:'POST',body:JSON.stringify(genBody())});$('#result').innerHTML='<p>\u5DF2\u4FDD\u5B58\u5230 <span class="path">'+esc(r.output_dir)+'</span></p>'+r.images.map(img=>'<img src="/api/file?path='+encodeURIComponent(img.path)+'&token='+token+'"><div class="path">'+esc(img.path)+'</div>').join('');await renderHistory()}catch(e){$('#result').innerHTML='<p style="color:var(--danger)">'+esc(e.message)+'</p>'}finally{$('#generateBtn').disabled=false}}
+    async function renderHistory(){const h=$('#history');if(!state.data)return;const r=await api('/api/history');h.innerHTML='<div class="panel"><h2>\u5386\u53F2\u8BB0\u5F55</h2><p class="muted">\u627E\u56DE\u6700\u8FD1\u751F\u6210\u7684\u56FE\u7247\u548C\u672C\u5730\u4FDD\u5B58\u8DEF\u5F84\u3002</p></div><div class="gallery">'+r.runs.map(runCard).join('')+'</div>'}
+    function runCard(r){const img=(r.images&&r.images[0])?'<img src="'+r.images[0].url+'&token='+token+'">':'';const plan=r.plan||{};return '<div class="run">'+img+'<div class="title">'+esc((r.prompt||'\u672A\u547D\u540D').slice(0,60))+'</div><div class="muted small">'+esc(new Date(r.created_at).toLocaleString())+' \xB7 '+esc(plan.provider||'')+' \xB7 '+esc(plan.preset||'')+'</div><div class="path small">'+esc(r.output_dir)+'</div><div class="actions" style="margin-top:8px"><button onclick="navigator.clipboard.writeText(\\''+esc(String(r.output_dir)).replaceAll("'","\\\\'")+'\\')">\u590D\u5236\u6587\u4EF6\u5939</button></div></div>'}
+    load().catch(e=>toast(e.message));
+  </script>
+</body>
+</html>`;
 
 // src/commands/preferences.ts
 async function preferMode(name) {
@@ -1320,34 +2342,48 @@ async function preferPreset(name) {
 }
 
 // src/commands/quickstart.ts
-function runQuickstart() {
+async function runQuickstart() {
   console.log(formatQuickstart());
+  await maybePrintUpdateHint();
 }
 function formatQuickstart() {
   return [
     "PicGen quickstart",
     "",
     "Install:",
+    "  node -v",
+    "  npm -v",
     "  npm install -g @ai-agent-tools/picgen",
+    "  npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy",
+    "  picgen skill install codex",
+    "",
+    "Open local web UI:",
+    "  picgen open",
     "",
     "Configure:",
-    "  picgen setup",
+    "  picgen setup  # can save provider API keys for you",
+    "  picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer",
+    "  picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard",
+    "  picgen key set PICGEN_GEMINI_PROXY_KEY --stdin",
+    "  picgen key list --json",
     "  picgen doctor --json",
     "",
     "Preview before spending quota:",
-    '  picgen create --dry-run "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    '  picgen create --dry-run --preset fast-draft "\u4E00\u5F20\u7B80\u6D01\u7684 PicGen \u6D4B\u8BD5\u56FE"',
     "",
     "Generate after confirmation:",
-    '  picgen create --yes "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    '  picgen create --yes --preset fast-draft "\u4E00\u5F20\u7B80\u6D01\u7684 PicGen \u6D4B\u8BD5\u56FE"',
     "",
     "Use a reference image:",
     '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
     "",
     "Agent prompt:",
-    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u914D\u7F6E\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
+    "  \u8BF7\u5E2E\u6211\u5B89\u88C5\u5E76\u914D\u7F6E PicGen \u751F\u56FE\u5DE5\u5177\u3002\u8BF7\u5148\u9605\u8BFB\u5E76\u6309\u8FD9\u4E2A\u6307\u5357\u6267\u884C\uFF1Ahttps://raw.githubusercontent.com/ai-agent-tools/picgen/refs/heads/main/docs/agent-install.md \u3002\u4F60\u8D1F\u8D23\u5224\u65AD\u662F\u5426\u5728\u672C\u673A\u6301\u4E45\u73AF\u5883\u3001\u5B89\u88C5 CLI \u548C skill\u3001\u5F15\u5BFC\u6211\u914D\u7F6E provider/API key\uFF0C\u5E76\u5148\u9884\u89C8\u751F\u6210\u65B9\u6848\uFF0C\u7B49\u6211\u786E\u8BA4\u540E\u518D\u751F\u6210\u6D4B\u8BD5\u56FE\u3002\u4E0D\u8981\u8BA9\u6211\u7406\u89E3\u547D\u4EE4\u7EC6\u8282\uFF0C\u4E5F\u4E0D\u8981\u8BA9\u6211\u628A API key \u53D1\u5230\u804A\u5929\u91CC\u3002",
     "",
     "Notes:",
     "  - Provider host URLs should not include /v1 or /v1beta.",
+    "  - picgen setup can store API keys in ~/.picgen/.env.",
+    "  - picgen open starts a foreground local web UI on 127.0.0.1:8188.",
     "  - Agent workflows should dry-run before real generation.",
     "  - Generated images are saved locally; do not paste base64 into chat.",
     "  - First-user rollout checklist: docs/release-alpha.md"
@@ -1355,7 +2391,7 @@ function formatQuickstart() {
 }
 
 // src/commands/setup.ts
-import { confirm as confirm2, input as input2, select as select2 } from "@inquirer/prompts";
+import { confirm as confirm2, input as input2, password as password2, select as select2 } from "@inquirer/prompts";
 async function runSetup() {
   await ensureConfig();
   console.log(`PicGen config: ${getConfigPath()}`);
@@ -1370,17 +2406,20 @@ async function runSetup() {
         { name: "Quick add a common provider/channel", value: "quick-add" },
         { name: "Choose default provider/channel", value: "provider" },
         { name: "Choose generation preference", value: "mode" },
+        { name: "Configure API key", value: "key" },
         { name: "Test a provider", value: "test" },
         { name: "Advanced: add a custom provider/channel", value: "add" },
         { name: "Finish setup", value: "done" }
       ]
     });
     if (action === "quick-add") {
-      await quickAddProvider();
+      await quickAddProvider2();
     } else if (action === "provider") {
       await chooseDefaultProvider();
     } else if (action === "mode") {
       await chooseDefaultMode();
+    } else if (action === "key") {
+      await chooseProviderKeyToConfigure();
     } else if (action === "test") {
       await chooseProviderToTest();
     } else if (action === "add") {
@@ -1399,7 +2438,7 @@ async function printSetupSummary() {
   for (const [providerName, provider2] of Object.entries(config.providers)) {
     const preference = providerName === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(providerName) ? "fallback" : "manual";
     console.log(
-      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, capabilities=${provider2.capabilities.join(",")}`
+      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, key=${provider2.api_key_env}${process.env[provider2.api_key_env] ? " set" : " missing"}, capabilities=${provider2.capabilities.join(",")}`
     );
   }
 }
@@ -1447,7 +2486,19 @@ async function chooseProviderToTest() {
   if (result.model) console.log(`Model: ${result.model}`);
   if (result.http_status) console.log(`HTTP status: ${result.http_status}`);
 }
-async function quickAddProvider() {
+async function chooseProviderKeyToConfigure() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose the provider key to configure",
+    default: config.routing.default_provider,
+    choices: Object.entries(config.providers).map(([providerName, provider2]) => ({
+      name: `${providerName} (${provider2.api_key_env}${process.env[provider2.api_key_env] ? ", currently set" : ", missing"})`,
+      value: providerName
+    }))
+  });
+  await configureProviderApiKey(config.providers[name]);
+}
+async function quickAddProvider2() {
   const config = await loadConfig();
   const template = await select2({
     message: "Choose the provider/channel you want to add",
@@ -1481,7 +2532,7 @@ async function quickAddProvider() {
   });
   const apiKeyEnv = await input2({
     message: "API key environment variable",
-    default: defaults.api_key_env
+    default: nextAvailableProviderApiKeyEnv(config, defaults.api_key_env, name)
   });
   const modelsRaw = await input2({
     message: "Models (comma separated, press Enter for recommended defaults)",
@@ -1493,7 +2544,7 @@ async function quickAddProvider() {
     channel: defaults.channel,
     base_url: normalizeProviderBaseUrl(baseUrl),
     api_key_env: apiKeyEnv,
-    models: parseModels(modelsRaw),
+    models: parseModels3(modelsRaw),
     capabilities: defaultCapabilitiesForProtocol2(defaults.protocol)
   };
   addProviderToConfig(config, name, provider2);
@@ -1506,7 +2557,27 @@ async function quickAddProvider() {
   }
   await saveConfig(config);
   console.log(`Added provider: ${name}`);
-  console.log(`Set ${apiKeyEnv} in your shell or .env before testing this provider.`);
+  await configureProviderApiKey(provider2);
+}
+async function configureProviderApiKey(provider2) {
+  if (process.env[provider2.api_key_env]) {
+    const replace = await confirm2({
+      message: `${provider2.api_key_env} is already available. Replace the saved PicGen key?`,
+      default: false
+    });
+    if (!replace) return;
+  }
+  const value = await password2({
+    message: `Paste API key for ${provider2.api_key_env} (leave empty to skip)`,
+    mask: "*"
+  });
+  if (!value.trim()) {
+    console.log(`Skipped API key. You can configure it later with picgen setup.`);
+    return;
+  }
+  const path = await saveManagedEnvVar(provider2.api_key_env, value.trim());
+  console.log(`Saved ${provider2.api_key_env} to ${path}`);
+  console.log(`PicGen loads this file automatically. Advanced users can override it with shell env vars or a project .env.`);
 }
 function quickProviderDefaults(template) {
   switch (template) {
@@ -1516,7 +2587,7 @@ function quickProviderDefaults(template) {
         protocol: "openai-images",
         channel: "third_party",
         base_url: "https://www.pandai.vip",
-        api_key_env: "OPENAI_API_KEY",
+        api_key_env: "PICGEN_OPENAI_PROXY_KEY",
         models: ["gpt-image-2"]
       };
     case "gemini_proxy":
@@ -1525,7 +2596,7 @@ function quickProviderDefaults(template) {
         protocol: "gemini",
         channel: "third_party",
         base_url: "https://www.pandai.vip",
-        api_key_env: "GEMINI_API_KEY",
+        api_key_env: "PICGEN_GEMINI_PROXY_KEY",
         models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
       };
     case "openai_official":
@@ -1548,7 +2619,7 @@ function quickProviderDefaults(template) {
       };
   }
 }
-function parseModels(raw) {
+function parseModels3(raw) {
   return raw.split(",").map((model) => model.trim()).filter(Boolean);
 }
 function providerLabel(provider2) {
@@ -1570,11 +2641,54 @@ function modeLabel(modeName) {
   }
 }
 
+// src/commands/skill.ts
+import { access, cp, mkdir as mkdir5 } from "fs/promises";
+import { constants } from "fs";
+import { dirname as dirname4, join as join7, resolve as resolve4 } from "path";
+import { homedir as homedir4 } from "os";
+import { fileURLToPath } from "url";
+async function installSkill(target, options) {
+  if (target !== "codex") {
+    throw new Error(`Unsupported skill target: ${target}. Supported target: codex.`);
+  }
+  const source = await findBundledPicgenSkill();
+  const destination = join7(getCodexHome(), "skills", "picgen");
+  await mkdir5(dirname4(destination), { recursive: true });
+  await cp(source, destination, {
+    recursive: true,
+    force: options.force ?? false,
+    errorOnExist: !(options.force ?? false)
+  });
+  console.log(`Installed PicGen skill for Codex: ${destination}`);
+  console.log("Restart Codex or start a new Codex session if the skill is not visible yet.");
+}
+function getCodexHome() {
+  return process.env.CODEX_HOME ?? join7(homedir4(), ".codex");
+}
+async function findBundledPicgenSkill() {
+  const here = dirname4(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve4(here, "../skills/picgen"),
+    resolve4(here, "../../skills/picgen"),
+    resolve4(process.cwd(), "skills/picgen")
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(join7(candidate, "SKILL.md"), constants.R_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error("Bundled PicGen skill not found. Reinstall @ai-agent-tools/picgen and try again.");
+}
+
 // src/cli.ts
+await loadPicgenEnv();
 var program = new Command();
-program.name("picgen").description("Lightweight image generation connector for AI agents.").version("0.1.0-alpha.0");
+program.name("picgen").description("Lightweight image generation connector for AI agents.").version(VERSION);
 program.command("setup").description("Run the interactive PicGen setup wizard.").action(runSetup);
 program.command("quickstart").description("Print install and first-run guidance.").action(runQuickstart);
+program.command("open").description("Open the local PicGen web interface.").option("--port <port>", "Preferred local port. Defaults to 8188.").option("--no-open", "Print the URL without opening the browser.").action(runOpen);
 program.command("doctor").description("Inspect PicGen configuration and provider readiness.").option("--json", "Print machine-readable JSON.").action(runDoctor);
 program.command("create").description("Create an image generation plan or generate images.").argument("<prompt...>", "Prompt text.").option("--dry-run", "Plan generation without calling a provider.").option("--preset <name>", "Preset name.").option("--provider <name>", "Provider name.").option("--mode <name>", "Mode name.").option("--model <name>", "Model name.").option("--out-dir <path>", "Output directory.").option(
   "--reference <path>",
@@ -1585,14 +2699,21 @@ program.command("create").description("Create an image generation plan or genera
 var provider = program.command("provider").description("Manage providers/channels.");
 provider.command("list").description("List providers.").action(listProviders);
 provider.command("add").description("Add a provider.").action(addProvider);
+provider.command("quick-add").argument("<template>", "openai-proxy, gemini-proxy, openai-official, or gemini-official").description("Add a common provider/channel without interactive prompts.").option("--name <name>", "Provider name.").option("--host <url>", "Provider host URL. Do not include /v1 or /v1beta.").option("--key-env <name>", "API key environment variable.").option("--models <models>", "Comma-separated model list.").option("--prefer", "Use this provider as the default.").action(quickAddProvider);
 provider.command("edit").argument("<name>").description("Edit a provider.").action(editProvider);
 provider.command("test").argument("<name>").description("Test provider connectivity without generating an image.").option("--json", "Print machine-readable JSON.").action(runProviderTest);
 provider.command("prefer").argument("<name>").description("Set the default provider preference.").action(preferProvider);
 provider.command("enable").argument("<name>").description("Enable a provider.").action((name) => setProviderEnabled(name, true));
 provider.command("disable").argument("<name>").description("Disable a provider.").action((name) => setProviderEnabled(name, false));
 provider.command("remove").argument("<name>").description("Remove a provider.").action(removeProvider);
+var key = program.command("key").description("Manage PicGen API keys.");
+key.command("set").argument("<env-name>", "Environment variable name, such as PICGEN_GEMINI_PROXY_KEY.").description("Save an API key to PicGen's managed env file.").option("--stdin", "Read the key value from stdin.").option("--clipboard", "Read the key value from the macOS clipboard.").option("--value <value>", "Set the key value directly. Prefer --stdin for agent workflows.").action(setApiKey);
+key.command("list").description("List configured provider keys without revealing secret values.").option("--json", "Print machine-readable JSON.").action(listApiKeys);
+key.command("show").argument("<env-name>", "Environment variable name.").description("Show one configured key without revealing the secret value.").option("--json", "Print machine-readable JSON.").action(showApiKey);
+program.command("skill").description("Install PicGen agent skills.").command("install").argument("<target>", "Skill target. Currently supported: codex.").description("Install the bundled PicGen skill into an agent skill directory.").option("--force", "Overwrite an existing installed skill.").action(installSkill);
 program.command("mode").description("Manage generation mode preferences.").command("prefer").argument("<name>").description("Set the default mode preference.").action(preferMode);
 program.command("preset").description("Manage generation preset preferences.").command("prefer").argument("<name>").description("Set the default preset preference.").action(preferPreset);
+program.command("update").description("Manage PicGen updates.").command("check").description("Check whether a newer PicGen version is available.").option("--json", "Print machine-readable JSON.").action(runUpdateCheck);
 program.parseAsync().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;