@insforge/cli 0.1.76 → 0.1.79

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { join as join17, dirname as dirname3 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { join as join18, dirname as dirname3 } from "path";
 import { fileURLToPath } from "url";
 import { Command } from "commander";
-import * as clack17 from "@clack/prompts";
+import * as clack18 from "@clack/prompts";
 
 // src/lib/prompts.ts
 import * as readline from "readline";
@@ -41,8 +41,8 @@ var LineReader = class {
     this.output.write(prompt);
     if (this.queue.length > 0) return this.queue.shift();
     if (this.closed) return null;
-    return new Promise((resolve8) => {
-      this.waiter = resolve8;
+    return new Promise((resolve9) => {
+      this.waiter = resolve9;
     });
   }
   close() {
@@ -424,8 +424,8 @@ function startCallbackServer() {
   return new Promise((resolveServer) => {
     let resolveResult;
     let rejectResult;
-    const resultPromise = new Promise((resolve8, reject) => {
-      resolveResult = resolve8;
+    const resultPromise = new Promise((resolve9, reject) => {
+      resolveResult = resolve9;
       rejectResult = reject;
     });
     const server = createServer((req, res) => {
@@ -1329,36 +1329,36 @@ function registerBranchCreateCommand(branch) {
         throw new CLIError(`Invalid --mode: ${opts.mode} (must be "full" or "schema-only")`);
       }
       const mode = opts.mode;
-      const spinner10 = !json ? clack5.spinner() : null;
+      const spinner11 = !json ? clack5.spinner() : null;
       let ready;
       let provisioned = false;
       try {
-        spinner10?.start(`Creating branch '${name}'...`);
+        spinner11?.start(`Creating branch '${name}'...`);
         const created = await createBranchApi(project.project_id, { mode, name }, apiUrl);
         captureEvent(project.project_id, "cli_branch_create", {
           mode,
           parent_project_id: project.project_id
         });
-        spinner10?.message(`Branch '${name}' created (appkey: ${created.appkey}). Provisioning...`);
-        ready = await pollUntilReady(created.id, apiUrl, spinner10);
+        spinner11?.message(`Branch '${name}' created (appkey: ${created.appkey}). Provisioning...`);
+        ready = await pollUntilReady(created.id, apiUrl, spinner11);
         provisioned = ready.branch_state === "ready";
         if (provisioned && opts.switch) {
-          spinner10?.message("Branch ready. Switching context...");
+          spinner11?.message("Branch ready. Switching context...");
           await runBranchSwitch({ name, apiUrl, json, silent: true });
-          spinner10?.stop(`Branch '${name}' is ready and active`);
+          spinner11?.stop(`Branch '${name}' is ready and active`);
         } else if (provisioned) {
-          spinner10?.stop(`Branch '${name}' is ready`);
+          spinner11?.stop(`Branch '${name}' is ready`);
         } else {
-          spinner10?.stop(`Branch '${name}' is in '${ready.branch_state}' state`);
+          spinner11?.stop(`Branch '${name}' is in '${ready.branch_state}' state`);
         }
       } catch (err) {
         if (provisioned) {
-          spinner10?.stop(
+          spinner11?.stop(
             `Branch '${name}' is ready, but switching context failed \u2014 run \`insforge branch switch ${name}\` to retry`,
             1
           );
         } else {
-          spinner10?.stop(`Branch '${name}' creation failed`, 1);
+          spinner11?.stop(`Branch '${name}' creation failed`, 1);
         }
         throw err;
       }
@@ -1382,7 +1382,7 @@ function registerBranchCreateCommand(branch) {
     }
   });
 }
-async function pollUntilReady(branchId, apiUrl, spinner10) {
+async function pollUntilReady(branchId, apiUrl, spinner11) {
   const start = Date.now();
   let lastState = "";
   while (Date.now() - start < POLL_TIMEOUT_MS) {
@@ -1391,8 +1391,8 @@ async function pollUntilReady(branchId, apiUrl, spinner10) {
     if (branch2.branch_state === "deleted" || branch2.branch_state === "conflicted") {
       throw new CLIError(`Branch creation failed (state: ${branch2.branch_state})`);
     }
-    if (spinner10 && branch2.branch_state !== lastState) {
-      spinner10.message(`Provisioning branch (state: ${branch2.branch_state})...`);
+    if (spinner11 && branch2.branch_state !== lastState) {
+      spinner11.message(`Provisioning branch (state: ${branch2.branch_state})...`);
       lastState = branch2.branch_state;
     }
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
@@ -1946,6 +1946,9 @@ ${err.nextActions}`;
     if (res.status === 404 && isRouteLevel404 && path6 === "/api/database/migrations") {
       message = "Database migrations are not available on this backend.\nSelf-hosted: upgrade your InsForge instance. Cloud: contact your InsForge admin about database migration support.";
     }
+    if (res.status === 404 && isRouteLevel404 && path6.startsWith("/api/ai")) {
+      message = "AI Model Gateway setup is not available on this backend.\nUpgrade your InsForge project to a version with Model Gateway support, or keep using the legacy @insforge/sdk AI modules for projects that still rely on the older AI API surface.";
+    }
     throw new CLIError(message);
   }
   return res;
@@ -2346,11 +2349,11 @@ async function collectDeploymentFiles(sourceDir) {
   return files;
 }
 async function createZipBuffer(sourceDir) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const archive = archiver("zip", { zlib: { level: 9 } });
     const chunks = [];
     archive.on("data", (chunk) => chunks.push(chunk));
-    archive.on("end", () => resolve8(Buffer.concat(chunks)));
+    archive.on("end", () => resolve9(Buffer.concat(chunks)));
     archive.on("error", (err) => reject(err));
     archive.directory(sourceDir, false, (entry) => {
       if (shouldExclude(entry.name)) return false;
@@ -2427,12 +2430,12 @@ async function startDirectDeployment(deploymentId, startBody) {
   });
   await response.json();
 }
-async function pollDeployment(deploymentId, spinner10, syncBeforeRead) {
-  spinner10?.message("Building and deploying...");
+async function pollDeployment(deploymentId, spinner11, syncBeforeRead) {
+  spinner11?.message("Building and deploying...");
   const startTime = Date.now();
   let deployment = null;
   while (Date.now() - startTime < POLL_TIMEOUT_MS3) {
-    await new Promise((resolve8) => setTimeout(resolve8, POLL_INTERVAL_MS3));
+    await new Promise((resolve9) => setTimeout(resolve9, POLL_INTERVAL_MS3));
     try {
       if (syncBeforeRead) {
         await ossFetch(`/api/deployments/${deploymentId}/sync`, { method: "POST" });
@@ -2444,13 +2447,13 @@ async function pollDeployment(deploymentId, spinner10, syncBeforeRead) {
         break;
       }
       if (status === "ERROR" || status === "CANCELED") {
-        spinner10?.stop("Deployment failed");
+        spinner11?.stop("Deployment failed");
         throw new CLIError(
           getDeploymentError(deployment.metadata) ?? `Deployment failed with status: ${deployment.status}`
         );
       }
       const elapsed = Math.round((Date.now() - startTime) / 1e3);
-      spinner10?.message(`Building and deploying... (${elapsed}s, status: ${deployment.status})`);
+      spinner11?.message(`Building and deploying... (${elapsed}s, status: ${deployment.status})`);
     } catch (err) {
       if (err instanceof CLIError) throw err;
     }
@@ -2460,20 +2463,20 @@ async function pollDeployment(deploymentId, spinner10, syncBeforeRead) {
   return { deploymentId, deployment, isReady, liveUrl };
 }
 async function deployProjectDirect(opts, config) {
-  const { sourceDir, startBody = {}, spinner: spinner10 } = opts;
-  spinner10?.start("Scanning source files...");
+  const { sourceDir, startBody = {}, spinner: spinner11 } = opts;
+  spinner11?.start("Scanning source files...");
   const localFiles = await collectDeploymentFiles(sourceDir);
   if (localFiles.length === 0) {
     throw new CLIError("No deployable files found in the source directory.");
   }
-  spinner10?.message("Creating deployment...");
+  spinner11?.message("Creating deployment...");
   const createResult = await createDirectDeploymentSession(
     config,
     localFiles.map(({ path: relativePath, sha, size }) => ({ path: relativePath, sha, size }))
   );
   const localFileByPath = new Map(localFiles.map((file) => [file.path, file]));
   const pendingFiles = createResult.files.filter((file) => !file.uploadedAt);
-  spinner10?.message(`Uploading ${pendingFiles.length} file${pendingFiles.length === 1 ? "" : "s"}...`);
+  spinner11?.message(`Uploading ${pendingFiles.length} file${pendingFiles.length === 1 ? "" : "s"}...`);
   await runWithConcurrency(pendingFiles, DIRECT_UPLOAD_CONCURRENCY, async (manifestFile) => {
     const localFile = localFileByPath.get(manifestFile.path);
     if (!localFile) {
@@ -2484,18 +2487,18 @@ async function deployProjectDirect(opts, config) {
     }
     await uploadDirectDeploymentFile(createResult.id, manifestFile, localFile);
   });
-  spinner10?.message("Starting deployment...");
+  spinner11?.message("Starting deployment...");
   await startDirectDeployment(createResult.id, startBody);
-  return await pollDeployment(createResult.id, spinner10, !isInsforgeCloudOssHost(config.oss_host));
+  return await pollDeployment(createResult.id, spinner11, !isInsforgeCloudOssHost(config.oss_host));
 }
 async function deployProjectLegacy(opts) {
-  const { sourceDir, startBody = {}, spinner: spinner10 } = opts;
-  spinner10?.message("Creating deployment...");
+  const { sourceDir, startBody = {}, spinner: spinner11 } = opts;
+  spinner11?.message("Creating deployment...");
   const createRes = await ossFetch("/api/deployments", { method: "POST" });
   const { id: deploymentId, uploadUrl, uploadFields } = await createRes.json();
-  spinner10?.message("Compressing source files...");
+  spinner11?.message("Compressing source files...");
   const zipBuffer = await createZipBuffer(sourceDir);
-  spinner10?.message("Uploading...");
+  spinner11?.message("Uploading...");
   const formData = new FormData();
   for (const [key, value] of Object.entries(uploadFields)) {
     formData.append(key, value);
@@ -2506,13 +2509,13 @@ async function deployProjectLegacy(opts) {
     const uploadErr = await uploadRes.text();
     throw new CLIError(`Failed to upload: ${uploadErr}`);
   }
-  spinner10?.message("Starting deployment...");
+  spinner11?.message("Starting deployment...");
   const startRes = await ossFetch(`/api/deployments/${deploymentId}/start`, {
     method: "POST",
     body: JSON.stringify(startBody)
   });
   await startRes.json();
-  return await pollDeployment(deploymentId, spinner10, false);
+  return await pollDeployment(deploymentId, spinner11, false);
 }
 async function deployProject(opts) {
   const config = getProjectConfig();
@@ -2547,7 +2550,7 @@ function registerDeploymentsDeployCommand(deploymentsCmd2) {
           `"${dirName}" is an excluded directory and cannot be used as a deploy source. Please specify your project root or output directory instead.`
         );
       }
-      const spinner10 = !json ? clack11.spinner() : null;
+      const spinner11 = !json ? clack11.spinner() : null;
       const startBody = {};
       if (opts.env) {
         try {
@@ -2573,9 +2576,9 @@ function registerDeploymentsDeployCommand(deploymentsCmd2) {
           throw new CLIError("Invalid --meta JSON.");
         }
       }
-      const result = await deployProject({ sourceDir, startBody, spinner: spinner10 });
+      const result = await deployProject({ sourceDir, startBody, spinner: spinner11 });
       if (result.isReady) {
-        spinner10?.stop("Deployment complete");
+        spinner11?.stop("Deployment complete");
         if (json) {
           outputJson(result.deployment);
         } else {
@@ -2585,7 +2588,7 @@ function registerDeploymentsDeployCommand(deploymentsCmd2) {
           clack11.log.info(`Deployment ID: ${result.deploymentId}`);
         }
       } else {
-        spinner10?.stop("Deployment is still building");
+        spinner11?.stop("Deployment is still building");
         if (json) {
           outputJson({
             id: result.deploymentId,
@@ -3151,13 +3154,13 @@ async function downloadGitHubTemplate(templateName, projectConfig, json) {
 // src/commands/projects/link.ts
 var execAsync3 = promisify4(exec3);
 async function runNpmInstall(startMessage = "Installing dependencies...") {
-  const spinner10 = clack13.spinner();
-  spinner10.start(startMessage);
+  const spinner11 = clack13.spinner();
+  spinner11.start(startMessage);
   try {
     await execAsync3("npm install", { cwd: process.cwd(), maxBuffer: 10 * 1024 * 1024 });
-    spinner10.stop("Dependencies installed");
+    spinner11.stop("Dependencies installed");
   } catch (err) {
-    spinner10.stop("Failed to install dependencies");
+    spinner11.stop("Failed to install dependencies");
     clack13.log.warn(`npm install failed: ${err.message}`);
     clack13.log.info("Run `npm install` manually to install dependencies.");
   }
@@ -3171,13 +3174,13 @@ async function runNpmSetupIfPresent() {
   } catch {
   }
   if (!hasSetup) return;
-  const spinner10 = clack13.spinner();
-  spinner10.start("Running setup (schema + migrations)...");
+  const spinner11 = clack13.spinner();
+  spinner11.start("Running setup (schema + migrations)...");
   try {
     await execAsync3("npm run setup", { cwd: process.cwd(), maxBuffer: 20 * 1024 * 1024 });
-    spinner10.stop("Setup complete");
+    spinner11.stop("Setup complete");
   } catch (err) {
-    spinner10.stop("Setup failed");
+    spinner11.stop("Setup failed");
     clack13.log.warn(`npm run setup failed: ${err.message.split("\n")[0]}`);
     clack13.log.info("Inspect the error, fix DATABASE_URL or network access, then run `npm run setup` manually.");
   }
@@ -3203,7 +3206,7 @@ function registerProjectLinkCommand(program2) {
             outputJson({ success: true, skills_only: true });
           } else {
             clack13.note(
-              `Open your coding agent (Claude Code, Codex, Cursor, etc.) and ask it to build something. It will walk you through provisioning an InsForge project when needed.`,
+              `Open your coding agent (Claude Code, Codex, Cursor, etc.) and ask it to build something. It will walk you through provisioning an InsForge project when needed. If you're not signed in yet, your browser will open for sign-in at that point.`,
               "What's next"
             );
           }
@@ -6017,7 +6020,7 @@ primary_region = "${opts.region}"
   };
 }
 function flyctlBuildAndPush(opts) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const cleanupStub = ensureFlyTomlStub({
       dir: opts.dir,
       appId: opts.appId,
@@ -6073,7 +6076,7 @@ function flyctlBuildAndPush(opts) {
           )
         );
       }
-      resolve8({ imageRef: `registry.fly.io/${opts.appId}@${m[1]}` });
+      resolve9({ imageRef: `registry.fly.io/${opts.appId}@${m[1]}` });
     });
   });
 }
@@ -6958,7 +6961,7 @@ function registerDiagnoseCommands(diagnoseCmd2) {
         const s = !json ? clack15.spinner() : null;
         s?.start("Collecting diagnostic data...");
         const data2 = await collectDiagnosticData(projectId, ossMode, apiUrl);
-        const cliVersion = "0.1.76";
+        const cliVersion = "0.1.79";
         s?.stop("Data collected");
         if (!json) {
           console.log(`
@@ -8472,14 +8475,14 @@ async function startPosthogCliFlow(projectId, jwt, apiUrl) {
   throw new CLIError("PostHog cli-start returned an unexpected response shape.");
 }
 function sleep(ms, signal) {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     if (signal?.aborted) {
       reject(new CLIError("Connection wait cancelled."));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve8();
+      resolve9();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -8782,8 +8785,8 @@ async function runConnectFlow(projectId, token, authorizeUrl, opts) {
     } catch {
     }
   }
-  const spinner10 = !opts.json && isInteractive ? clack16.spinner() : null;
-  spinner10?.start("Waiting for connection... (timeout: 15 minutes)");
+  const spinner11 = !opts.json && isInteractive ? clack16.spinner() : null;
+  spinner11?.start("Waiting for connection... (timeout: 15 minutes)");
   try {
     const conn = await pollPosthogConnection(
       projectId,
@@ -8793,20 +8796,20 @@ async function runConnectFlow(projectId, token, authorizeUrl, opts) {
         timeoutMs: POLL_TIMEOUT_MS4,
         maxTransientRetries: MAX_TRANSIENT_RETRIES,
         onTick: (elapsed) => {
-          if (spinner10) {
+          if (spinner11) {
             const secs = Math.floor(elapsed / 1e3);
             const mins = Math.floor(secs / 60);
             const remaining = `${mins}m ${secs % 60}s elapsed`;
-            spinner10.message(`Waiting for connection... (${remaining})`);
+            spinner11.message(`Waiting for connection... (${remaining})`);
           }
         }
       },
       opts.apiUrl
     );
-    spinner10?.stop("Connection received from PostHog.");
+    spinner11?.stop("Connection received from PostHog.");
     return conn;
   } catch (err) {
-    spinner10?.stop("Connection wait failed.");
+    spinner11?.stop("Connection wait failed.");
     throw err;
   }
 }
@@ -8824,14 +8827,14 @@ function resolveFramework(opts) {
 }
 async function installSdk(pm, cwd, opts) {
   const cmd = installCommand(pm, "posthog-js");
-  const spinner10 = !opts.json && isInteractive ? clack16.spinner() : null;
-  spinner10?.start(`Installing posthog-js (${cmd})...`);
+  const spinner11 = !opts.json && isInteractive ? clack16.spinner() : null;
+  spinner11?.start(`Installing posthog-js (${cmd})...`);
   try {
     await runInstall(pm, "posthog-js", cwd);
-    spinner10?.stop("Installed posthog-js.");
+    spinner11?.stop("Installed posthog-js.");
     return true;
   } catch (err) {
-    spinner10?.stop("Install failed.");
+    spinner11?.stop("Install failed.");
     if (!opts.json) {
       clack16.log.warn(
         `Could not run \`${cmd}\` automatically: ${err.message}
@@ -9060,6 +9063,75 @@ import pc4 from "picocolors";
 // src/lib/config-toml.ts
 import * as smolToml from "smol-toml";
 
+// src/lib/config-secrets.ts
+var ENV_REF_PATTERN = /^env\(([A-Z_][A-Z0-9_]*)\)$/;
+function parseEnvRef(value) {
+  const match = value.match(ENV_REF_PATTERN);
+  return match ? match[1] : null;
+}
+function validateSensitiveString(path6, value, suggestedSecretName) {
+  if (typeof value !== "string") {
+    throw new ConfigValidationError(path6, "must be a string");
+  }
+  if (parseEnvRef(value) !== null) {
+    return value;
+  }
+  throw new ConfigValidationError(
+    path6,
+    `sensitive field must be an env() reference; got literal value.
+  fix:
+    1. insforge secrets add ${suggestedSecretName} "<value>"
+    2. update insforge.toml:
+         ${path6.split(".").pop()} = "env(${suggestedSecretName})"
+    3. insforge config apply`
+  );
+}
+async function resolveEnvRef(envRef, fieldPath) {
+  const secretName = parseEnvRef(envRef);
+  if (!secretName) {
+    throw new ConfigValidationError(
+      fieldPath,
+      `expected env() reference, got "${envRef}"`
+    );
+  }
+  let res;
+  try {
+    res = await ossFetch(`/api/secrets/${encodeURIComponent(secretName)}`);
+  } catch (err) {
+    const message = err.message ?? "";
+    if (/not found/i.test(message)) {
+      throw new CLIError(
+        `${fieldPath} references env(${secretName}) but no such secret exists.
+  fix: insforge secrets add ${secretName} "<value>"`,
+        1,
+        "SECRET_NOT_FOUND"
+      );
+    }
+    throw new CLIError(
+      `failed to resolve env(${secretName}) for ${fieldPath}: ${message}`,
+      1,
+      "SECRET_LOOKUP_FAILED"
+    );
+  }
+  if (!res.ok) {
+    throw new CLIError(
+      `failed to resolve env(${secretName}) for ${fieldPath}: HTTP ${res.status}`,
+      1,
+      "SECRET_LOOKUP_FAILED"
+    );
+  }
+  const body = await res.json();
+  if (typeof body.value !== "string" || body.value.length === 0) {
+    throw new CLIError(
+      `env(${secretName}) resolved to an empty value (secret may be inactive).
+  fix: insforge secrets update ${secretName} --active true`,
+      1,
+      "SECRET_EMPTY"
+    );
+  }
+  return body.value;
+}
+
 // src/lib/config-schema.ts
 var ConfigValidationError = class extends Error {
   constructor(path6, message) {
@@ -9081,6 +9153,25 @@ function validateConfig(input) {
     out.project_id = obj.project_id;
   }
   if ("auth" in obj) out.auth = validateAuth(obj.auth);
+  if ("deployments" in obj) out.deployments = validateDeployments(obj.deployments);
+  return out;
+}
+function validateDeployments(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new ConfigValidationError("deployments", "must be an object");
+  }
+  const obj = input;
+  const out = {};
+  if ("subdomain" in obj) {
+    const v = obj.subdomain;
+    if (v !== null && typeof v !== "string") {
+      throw new ConfigValidationError(
+        "deployments.subdomain",
+        "must be a string or null"
+      );
+    }
+    out.subdomain = v;
+  }
   return out;
 }
 function validateAuth(input) {
@@ -9099,6 +9190,128 @@ function validateAuth(input) {
     }
     out.allowed_redirect_urls = v;
   }
+  if ("require_email_verification" in obj) {
+    if (typeof obj.require_email_verification !== "boolean") {
+      throw new ConfigValidationError(
+        "auth.require_email_verification",
+        "must be a boolean"
+      );
+    }
+    out.require_email_verification = obj.require_email_verification;
+  }
+  if ("verify_email_method" in obj) {
+    out.verify_email_method = validateVerificationMethod(
+      "auth.verify_email_method",
+      obj.verify_email_method
+    );
+  }
+  if ("reset_password_method" in obj) {
+    out.reset_password_method = validateVerificationMethod(
+      "auth.reset_password_method",
+      obj.reset_password_method
+    );
+  }
+  if ("password" in obj) out.password = validatePassword(obj.password);
+  if ("smtp" in obj) out.smtp = validateSmtp(obj.smtp);
+  return out;
+}
+function validateVerificationMethod(path6, value) {
+  if (value !== "code" && value !== "link") {
+    throw new ConfigValidationError(path6, 'must be "code" or "link"');
+  }
+  return value;
+}
+function validatePassword(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new ConfigValidationError("auth.password", "must be a table");
+  }
+  const obj = input;
+  const out = {};
+  if ("min_length" in obj) {
+    if (typeof obj.min_length !== "number" || !Number.isInteger(obj.min_length) || obj.min_length < 4 || obj.min_length > 128) {
+      throw new ConfigValidationError(
+        "auth.password.min_length",
+        "must be an integer between 4 and 128"
+      );
+    }
+    out.min_length = obj.min_length;
+  }
+  for (const key of [
+    "require_number",
+    "require_lowercase",
+    "require_uppercase",
+    "require_special_char"
+  ]) {
+    if (key in obj) {
+      if (typeof obj[key] !== "boolean") {
+        throw new ConfigValidationError(`auth.password.${key}`, "must be a boolean");
+      }
+      out[key] = obj[key];
+    }
+  }
+  return out;
+}
+function validateSmtp(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new ConfigValidationError("auth.smtp", "must be a table");
+  }
+  const obj = input;
+  const out = {};
+  if ("enabled" in obj) {
+    if (typeof obj.enabled !== "boolean") {
+      throw new ConfigValidationError("auth.smtp.enabled", "must be a boolean");
+    }
+    out.enabled = obj.enabled;
+  }
+  if ("host" in obj) {
+    if (typeof obj.host !== "string") {
+      throw new ConfigValidationError("auth.smtp.host", "must be a string");
+    }
+    out.host = obj.host;
+  }
+  if ("port" in obj) {
+    if (typeof obj.port !== "number" || !Number.isInteger(obj.port) || obj.port < 1 || obj.port > 65535) {
+      throw new ConfigValidationError(
+        "auth.smtp.port",
+        "must be an integer between 1 and 65535"
+      );
+    }
+    out.port = obj.port;
+  }
+  if ("username" in obj) {
+    if (typeof obj.username !== "string") {
+      throw new ConfigValidationError("auth.smtp.username", "must be a string");
+    }
+    out.username = obj.username;
+  }
+  if ("password" in obj) {
+    out.password = validateSensitiveString(
+      "auth.smtp.password",
+      obj.password,
+      "SMTP_PASSWORD"
+    );
+  }
+  if ("sender_email" in obj) {
+    if (typeof obj.sender_email !== "string") {
+      throw new ConfigValidationError("auth.smtp.sender_email", "must be a string");
+    }
+    out.sender_email = obj.sender_email;
+  }
+  if ("sender_name" in obj) {
+    if (typeof obj.sender_name !== "string") {
+      throw new ConfigValidationError("auth.smtp.sender_name", "must be a string");
+    }
+    out.sender_name = obj.sender_name;
+  }
+  if ("min_interval_seconds" in obj) {
+    if (typeof obj.min_interval_seconds !== "number" || !Number.isInteger(obj.min_interval_seconds) || obj.min_interval_seconds < 0) {
+      throw new ConfigValidationError(
+        "auth.smtp.min_interval_seconds",
+        "must be a non-negative integer"
+      );
+    }
+    out.min_interval_seconds = obj.min_interval_seconds;
+  }
   return out;
 }
 
@@ -9120,14 +9333,204 @@ function stringifyConfigToml(config) {
   }
   if (config.auth) {
     lines.push("[auth]");
-    if (config.auth.allowed_redirect_urls !== void 0) {
-      const urls = config.auth.allowed_redirect_urls.map((u) => JSON.stringify(u)).join(", ");
-      lines.push(`allowed_redirect_urls = [${urls}]`);
-    }
+    renderAuthFlatFields(config.auth, lines);
     lines.push("");
+    if (config.auth.password !== void 0) {
+      lines.push("[auth.password]");
+      renderPasswordFields(config.auth.password, lines);
+      lines.push("");
+    }
+    if (config.auth.smtp !== void 0) {
+      lines.push("[auth.smtp]");
+      renderSmtpFields(config.auth.smtp, lines);
+      lines.push("");
+    }
+  }
+  if (config.deployments) {
+    if (typeof config.deployments.subdomain === "string" && config.deployments.subdomain !== "") {
+      lines.push("[deployments]");
+      lines.push(`subdomain = ${JSON.stringify(config.deployments.subdomain)}`);
+      lines.push("");
+    }
   }
   return lines.join("\n").replace(/\n+$/, "\n");
 }
+function renderAuthFlatFields(auth, lines) {
+  if (auth.allowed_redirect_urls !== void 0) {
+    const urls = auth.allowed_redirect_urls.map((u) => JSON.stringify(u)).join(", ");
+    lines.push(`allowed_redirect_urls = [${urls}]`);
+  }
+  if (auth.require_email_verification !== void 0) {
+    lines.push(`require_email_verification = ${auth.require_email_verification}`);
+  }
+  if (auth.verify_email_method !== void 0) {
+    lines.push(`verify_email_method = ${JSON.stringify(auth.verify_email_method)}`);
+  }
+  if (auth.reset_password_method !== void 0) {
+    lines.push(`reset_password_method = ${JSON.stringify(auth.reset_password_method)}`);
+  }
+}
+function renderPasswordFields(pw, lines) {
+  if (pw.min_length !== void 0) lines.push(`min_length = ${pw.min_length}`);
+  if (pw.require_number !== void 0) lines.push(`require_number = ${pw.require_number}`);
+  if (pw.require_lowercase !== void 0) {
+    lines.push(`require_lowercase = ${pw.require_lowercase}`);
+  }
+  if (pw.require_uppercase !== void 0) {
+    lines.push(`require_uppercase = ${pw.require_uppercase}`);
+  }
+  if (pw.require_special_char !== void 0) {
+    lines.push(`require_special_char = ${pw.require_special_char}`);
+  }
+}
+function renderSmtpFields(smtp, lines) {
+  if (smtp.enabled !== void 0) lines.push(`enabled = ${smtp.enabled}`);
+  if (smtp.host !== void 0) lines.push(`host = ${JSON.stringify(smtp.host)}`);
+  if (smtp.port !== void 0) lines.push(`port = ${smtp.port}`);
+  if (smtp.username !== void 0) lines.push(`username = ${JSON.stringify(smtp.username)}`);
+  if (smtp.password !== void 0) {
+    const secretName = parseEnvRef(smtp.password) ?? "SMTP_PASSWORD";
+    lines.push(
+      `# password is managed via secrets \u2014 run \`insforge secrets add ${secretName} "<value>"\``
+    );
+    lines.push(`password = ${JSON.stringify(smtp.password)}`);
+  }
+  if (smtp.sender_email !== void 0) {
+    lines.push(`sender_email = ${JSON.stringify(smtp.sender_email)}`);
+  }
+  if (smtp.sender_name !== void 0) {
+    lines.push(`sender_name = ${JSON.stringify(smtp.sender_name)}`);
+  }
+  if (smtp.min_interval_seconds !== void 0) {
+    lines.push(`min_interval_seconds = ${smtp.min_interval_seconds}`);
+  }
+}
+
+// src/lib/config-metadata.ts
+function liveFromMetadata(raw) {
+  const live = { auth: {} };
+  const a = isPlainObject(raw.auth) ? raw.auth : void 0;
+  if (a && "allowedRedirectUrls" in a) {
+    live.auth.allowed_redirect_urls = asStringArray(a.allowedRedirectUrls) ?? [];
+  }
+  if (a && "requireEmailVerification" in a) {
+    live.auth.require_email_verification = a.requireEmailVerification ?? false;
+  }
+  if (a && "verifyEmailMethod" in a && (a.verifyEmailMethod === "code" || a.verifyEmailMethod === "link")) {
+    live.auth.verify_email_method = a.verifyEmailMethod;
+  }
+  if (a && "resetPasswordMethod" in a && (a.resetPasswordMethod === "code" || a.resetPasswordMethod === "link")) {
+    live.auth.reset_password_method = a.resetPasswordMethod;
+  }
+  if (a && ("passwordMinLength" in a || "requireNumber" in a || "requireLowercase" in a || "requireUppercase" in a || "requireSpecialChar" in a)) {
+    live.auth.password = {
+      min_length: a.passwordMinLength ?? 8,
+      require_number: a.requireNumber ?? false,
+      require_lowercase: a.requireLowercase ?? false,
+      require_uppercase: a.requireUppercase ?? false,
+      require_special_char: a.requireSpecialChar ?? false
+    };
+  }
+  if (isPlainObject(a?.smtpConfig)) {
+    const s = a.smtpConfig;
+    live.auth.smtp = {
+      enabled: s.enabled ?? false,
+      host: s.host ?? "",
+      port: s.port ?? 587,
+      username: s.username ?? "",
+      hasPassword: s.hasPassword ?? false,
+      sender_email: s.senderEmail ?? "",
+      sender_name: s.senderName ?? "",
+      min_interval_seconds: s.minIntervalSeconds ?? 60
+    };
+  }
+  const d = isPlainObject(raw.deployments) ? raw.deployments : void 0;
+  if (d) {
+    live.deployments = {
+      subdomain: typeof d.customSlug === "string" && d.customSlug ? d.customSlug : null
+    };
+  }
+  return live;
+}
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function asStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string") ? v : null;
+}
+function configFromMetadata(raw) {
+  const config = {};
+  const skipped = [];
+  const a = isPlainObject(raw.auth) ? raw.auth : void 0;
+  if (a && "allowedRedirectUrls" in a) {
+    config.auth = config.auth ?? {};
+    config.auth.allowed_redirect_urls = asStringArray(a.allowedRedirectUrls) ?? [];
+  } else {
+    skipped.push("auth.allowed_redirect_urls");
+  }
+  if (a && "requireEmailVerification" in a) {
+    config.auth = config.auth ?? {};
+    config.auth.require_email_verification = a.requireEmailVerification ?? false;
+  } else {
+    skipped.push("auth.require_email_verification");
+  }
+  if (a && "verifyEmailMethod" in a && (a.verifyEmailMethod === "code" || a.verifyEmailMethod === "link")) {
+    config.auth = config.auth ?? {};
+    config.auth.verify_email_method = a.verifyEmailMethod;
+  } else {
+    skipped.push("auth.verify_email_method");
+  }
+  if (a && "resetPasswordMethod" in a && (a.resetPasswordMethod === "code" || a.resetPasswordMethod === "link")) {
+    config.auth = config.auth ?? {};
+    config.auth.reset_password_method = a.resetPasswordMethod;
+  } else {
+    skipped.push("auth.reset_password_method");
+  }
+  if (a && ("passwordMinLength" in a || "requireNumber" in a || "requireLowercase" in a || "requireUppercase" in a || "requireSpecialChar" in a)) {
+    config.auth = config.auth ?? {};
+    config.auth.password = {};
+    if ("passwordMinLength" in a) config.auth.password.min_length = a.passwordMinLength ?? 8;
+    if ("requireNumber" in a) config.auth.password.require_number = a.requireNumber ?? false;
+    if ("requireLowercase" in a) config.auth.password.require_lowercase = a.requireLowercase ?? false;
+    if ("requireUppercase" in a) config.auth.password.require_uppercase = a.requireUppercase ?? false;
+    if ("requireSpecialChar" in a) {
+      config.auth.password.require_special_char = a.requireSpecialChar ?? false;
+    }
+  } else {
+    skipped.push("auth.password");
+  }
+  if (a && "smtpConfig" in a) {
+    const s = a.smtpConfig;
+    if (isPlainObject(s)) {
+      config.auth = config.auth ?? {};
+      config.auth.smtp = {
+        enabled: s.enabled ?? false,
+        host: s.host ?? "",
+        port: s.port ?? 587,
+        username: s.username ?? "",
+        // When backend has a password set, emit a deterministic env() placeholder
+        // so the user knows which secret to define. We do NOT round-trip the
+        // value (it never leaves the backend). Re-applying this TOML force-resends
+        // from the secrets store — see config-diff.ts for the force-resend rationale.
+        ...s.hasPassword ? { password: "env(SMTP_PASSWORD)" } : {},
+        sender_email: s.senderEmail ?? "",
+        sender_name: s.senderName ?? "",
+        min_interval_seconds: s.minIntervalSeconds ?? 60
+      };
+    }
+  } else {
+    skipped.push("auth.smtp");
+  }
+  const d = isPlainObject(raw.deployments) ? raw.deployments : void 0;
+  if (d) {
+    if (typeof d.customSlug === "string" && d.customSlug) {
+      config.deployments = { subdomain: d.customSlug };
+    }
+  } else {
+    skipped.push("deployments.subdomain");
+  }
+  return { config, skipped };
+}
 
 // src/commands/config/export.ts
 function registerConfigExportCommand(cfg) {
@@ -9155,16 +9558,7 @@ function registerConfigExportCommand(cfg) {
       }
       const res = await ossFetch("/api/metadata");
       const raw = await res.json();
-      const config = {};
-      const skipped = [];
-      const authSlice = raw?.auth;
-      if (authSlice && typeof authSlice === "object" && "allowedRedirectUrls" in authSlice) {
-        config.auth = {
-          allowed_redirect_urls: authSlice.allowedRedirectUrls ?? []
-        };
-      } else {
-        skipped.push("auth.allowed_redirect_urls");
-      }
+      const { config, skipped } = configFromMetadata(raw);
       const toml = stringifyConfigToml(config);
       writeFileSync9(target, toml, "utf8");
       if (json) {
@@ -9210,8 +9604,165 @@ function diffConfig({ live, file }) {
       });
     }
   }
+  if (fileAuth && "require_email_verification" in fileAuth) {
+    const fromV = liveAuth.require_email_verification ?? false;
+    const toV = fileAuth.require_email_verification ?? false;
+    if (fromV !== toV) {
+      changes.push({
+        section: "auth",
+        op: "modify",
+        key: "require_email_verification",
+        from: fromV,
+        to: toV
+      });
+    }
+  }
+  if (fileAuth && "verify_email_method" in fileAuth && fileAuth.verify_email_method) {
+    const fromV = liveAuth.verify_email_method ?? "code";
+    const toV = fileAuth.verify_email_method;
+    if (fromV !== toV) {
+      changes.push({
+        section: "auth",
+        op: "modify",
+        key: "verify_email_method",
+        from: fromV,
+        to: toV
+      });
+    }
+  }
+  if (fileAuth && "reset_password_method" in fileAuth && fileAuth.reset_password_method) {
+    const fromV = liveAuth.reset_password_method ?? "code";
+    const toV = fileAuth.reset_password_method;
+    if (fromV !== toV) {
+      changes.push({
+        section: "auth",
+        op: "modify",
+        key: "reset_password_method",
+        from: fromV,
+        to: toV
+      });
+    }
+  }
+  if (fileAuth?.password) {
+    diffPassword(liveAuth.password, fileAuth.password, changes);
+  }
+  if (fileAuth?.smtp !== void 0) {
+    const smtpChange = diffSmtp(liveAuth.smtp, fileAuth.smtp);
+    if (smtpChange) changes.push(smtpChange);
+  }
+  const fileDeployments = file.deployments;
+  const liveDeployments = live.deployments ?? {};
+  if (fileDeployments && "subdomain" in fileDeployments) {
+    const fromV = liveDeployments.subdomain ?? null;
+    const rawTo = fileDeployments.subdomain;
+    const toV = rawTo === null || rawTo === void 0 || rawTo === "" ? null : rawTo;
+    if (fromV !== toV) {
+      changes.push({
+        section: "deployments",
+        op: "modify",
+        key: "subdomain",
+        from: fromV,
+        to: toV
+      });
+    }
+  }
   return { changes, summary: summarize(changes) };
 }
+function diffPassword(live, file, changes) {
+  const liveView = live ?? EMPTY_PASSWORD_POLICY;
+  if (file.min_length !== void 0 && liveView.min_length !== file.min_length) {
+    changes.push({
+      section: "auth.password",
+      op: "modify",
+      key: "min_length",
+      from: liveView.min_length,
+      to: file.min_length
+    });
+  }
+  for (const key of [
+    "require_number",
+    "require_lowercase",
+    "require_uppercase",
+    "require_special_char"
+  ]) {
+    const fromV = liveView[key];
+    const toV = file[key];
+    if (toV !== void 0 && fromV !== toV) {
+      changes.push({
+        section: "auth.password",
+        op: "modify",
+        key,
+        from: fromV,
+        to: toV
+      });
+    }
+  }
+}
+function diffSmtp(live, fileSmtp) {
+  const livedView = renderLiveSmtp(live);
+  const tomlView = renderFileSmtp(fileSmtp);
+  const envRef = fileSmtp.password ? parseEnvRef(fileSmtp.password) : null;
+  const nonPasswordFieldsChanged = livedView.enabled !== tomlView.enabled || livedView.host !== tomlView.host || livedView.port !== tomlView.port || livedView.username !== tomlView.username || livedView.sender_email !== tomlView.sender_email || livedView.sender_name !== tomlView.sender_name || livedView.min_interval_seconds !== tomlView.min_interval_seconds;
+  if (!nonPasswordFieldsChanged && envRef === null) {
+    return null;
+  }
+  return {
+    section: "auth.smtp",
+    op: "modify",
+    key: "config",
+    from: livedView,
+    to: tomlView,
+    passwordEnvRef: envRef ?? void 0
+  };
+}
+function renderLiveSmtp(live) {
+  const empty = EMPTY_SMTP_VIEW;
+  if (!live) return empty;
+  return {
+    enabled: live.enabled,
+    host: live.host,
+    port: live.port,
+    username: live.username,
+    password: live.hasPassword ? "(set)" : "(unset)",
+    sender_email: live.sender_email,
+    sender_name: live.sender_name,
+    min_interval_seconds: live.min_interval_seconds
+  };
+}
+function renderFileSmtp(file) {
+  return {
+    enabled: file.enabled ?? false,
+    host: file.host ?? "",
+    port: file.port ?? 587,
+    username: file.username ?? "",
+    password: renderFilePassword(file.password),
+    sender_email: file.sender_email ?? "",
+    sender_name: file.sender_name ?? "",
+    min_interval_seconds: file.min_interval_seconds ?? 60
+  };
+}
+function renderFilePassword(value) {
+  if (value === void 0) return "(unchanged)";
+  const ref = parseEnvRef(value);
+  return ref ? `env(${ref})` : "(invalid)";
+}
+var EMPTY_SMTP_VIEW = {
+  enabled: false,
+  host: "",
+  port: 587,
+  username: "",
+  password: "(unset)",
+  sender_email: "",
+  sender_name: "",
+  min_interval_seconds: 60
+};
+var EMPTY_PASSWORD_POLICY = {
+  min_length: 8,
+  require_number: false,
+  require_lowercase: false,
+  require_uppercase: false,
+  require_special_char: false
+};
 function summarize(changes) {
   const s = { add: 0, modify: 0, remove: 0, kept: 0 };
   for (const c of changes) {
@@ -9253,19 +9804,82 @@ function formatPlan(result) {
   return lines.join("\n");
 }
 function formatChange(c) {
+  if (c.section === "auth.smtp") {
+    const lines = [`~ smtp config:`];
+    const from = c.from;
+    const to = c.to;
+    for (const key of [
+      "enabled",
+      "host",
+      "port",
+      "username",
+      "password",
+      "sender_email",
+      "sender_name",
+      "min_interval_seconds"
+    ]) {
+      if (from[key] !== to[key]) {
+        lines.push(`    ${key}: ${JSON.stringify(from[key])} \u2192 ${JSON.stringify(to[key])}`);
+      }
+    }
+    if (c.passwordEnvRef) {
+      lines.push(`    (password force-resent from env(${c.passwordEnvRef}))`);
+    }
+    return lines.join("\n    ");
+  }
+  if (c.section === "deployments" && c.key === "subdomain") {
+    const fromLabel = c.from === null ? "(unset)" : JSON.stringify(c.from);
+    const toLabel = c.to === null ? "(unset)" : JSON.stringify(c.to);
+    return `~ ${c.key}: ${fromLabel} \u2192 ${toLabel}`;
+  }
   return `~ ${c.key}: ${JSON.stringify(c.from)} \u2192 ${JSON.stringify(c.to)}`;
 }
 
 // src/lib/config-capabilities.ts
 function metadataSupports(raw, change) {
   if (change.section === "auth" && change.key === "allowed_redirect_urls") {
-    return raw?.auth !== void 0 && raw.auth !== null && typeof raw.auth === "object" && "allowedRedirectUrls" in raw.auth;
+    return hasAuthKey(raw, "allowedRedirectUrls");
+  }
+  if (change.section === "auth" && change.key === "require_email_verification") {
+    return hasAuthKey(raw, "requireEmailVerification");
+  }
+  if (change.section === "auth" && change.key === "verify_email_method") {
+    return hasAuthKey(raw, "verifyEmailMethod");
+  }
+  if (change.section === "auth" && change.key === "reset_password_method") {
+    return hasAuthKey(raw, "resetPasswordMethod");
+  }
+  if (change.section === "auth.password") {
+    return hasAuthKey(raw, AUTH_PASSWORD_WIRE_KEY[change.key]);
   }
+  if (change.section === "auth.smtp") {
+    return hasAuthKey(raw, "smtpConfig");
+  }
+  if (change.section === "deployments" && change.key === "subdomain") {
+    return raw?.deployments !== void 0 && raw.deployments !== null && typeof raw.deployments === "object";
+  }
+  const _exhaustive = change;
+  void _exhaustive;
   return false;
 }
+function hasAuthKey(raw, key) {
+  const auth = raw?.auth;
+  return auth !== void 0 && auth !== null && typeof auth === "object" && key in auth;
+}
+var AUTH_PASSWORD_WIRE_KEY = {
+  min_length: "passwordMinLength",
+  require_number: "requireNumber",
+  require_lowercase: "requireLowercase",
+  require_uppercase: "requireUppercase",
+  require_special_char: "requireSpecialChar"
+};
 function changePath(change) {
+  if (change.section === "auth.smtp") return "auth.smtp";
   return `${change.section}.${change.key}`;
 }
+function authPasswordWireKey(key) {
+  return AUTH_PASSWORD_WIRE_KEY[key];
+}
 
 // src/commands/config/plan.ts
 function registerConfigPlanCommand(cfg) {
@@ -9278,9 +9892,7 @@ function registerConfigPlanCommand(cfg) {
       const file = parseConfigToml(tomlSource);
       const res = await ossFetch("/api/metadata");
       const raw = await res.json();
-      const live = {
-        auth: { allowed_redirect_urls: raw.auth?.allowedRedirectUrls ?? [] }
-      };
+      const live = liveFromMetadata(raw);
       const result = diffConfig({ live, file });
       const skipped = result.changes.filter((c) => !metadataSupports(raw, c)).map((c) => changePath(c));
       if (json) {
@@ -9318,9 +9930,7 @@ function registerConfigApplyCommand(cfg) {
       const file = parseConfigToml(tomlSource);
       const res = await ossFetch("/api/metadata");
       const raw = await res.json();
-      const live = {
-        auth: { allowed_redirect_urls: raw.auth?.allowedRedirectUrls ?? [] }
-      };
+      const live = liveFromMetadata(raw);
       const result = diffConfig({ live, file });
       const approved = opts.autoApprove || yes;
       if (!json) {
@@ -9400,7 +10010,68 @@ async function applyChange(change) {
     });
     return;
   }
-  throw new Error(`Unsupported change type: ${change.section}.${change.key}`);
+  if (change.section === "auth" && change.key === "require_email_verification") {
+    await ossFetch("/api/auth/config", {
+      method: "PUT",
+      body: JSON.stringify({ requireEmailVerification: change.to })
+    });
+    return;
+  }
+  if (change.section === "auth" && change.key === "verify_email_method") {
+    await ossFetch("/api/auth/config", {
+      method: "PUT",
+      body: JSON.stringify({ verifyEmailMethod: change.to })
+    });
+    return;
+  }
+  if (change.section === "auth" && change.key === "reset_password_method") {
+    await ossFetch("/api/auth/config", {
+      method: "PUT",
+      body: JSON.stringify({ resetPasswordMethod: change.to })
+    });
+    return;
+  }
+  if (change.section === "auth.password") {
+    const wireKey = authPasswordWireKey(change.key);
+    await ossFetch("/api/auth/config", {
+      method: "PUT",
+      body: JSON.stringify({ [wireKey]: change.to })
+    });
+    return;
+  }
+  if (change.section === "auth.smtp") {
+    const to = change.to;
+    const body = {
+      enabled: to.enabled,
+      host: to.host,
+      port: to.port,
+      username: to.username,
+      senderEmail: to.sender_email,
+      senderName: to.sender_name,
+      minIntervalSeconds: to.min_interval_seconds
+    };
+    if (change.passwordEnvRef) {
+      const value = await resolveEnvRef(
+        `env(${change.passwordEnvRef})`,
+        "auth.smtp.password"
+      );
+      body.password = value;
+    }
+    await ossFetch("/api/auth/smtp-config", {
+      method: "PUT",
+      body: JSON.stringify(body)
+    });
+    return;
+  }
+  if (change.section === "deployments" && change.key === "subdomain") {
+    await ossFetch("/api/deployments/slug", {
+      method: "PUT",
+      body: JSON.stringify({ slug: change.to })
+    });
+    return;
+  }
+  const _exhaustive = change;
+  throw new Error(`Unsupported change: ${JSON.stringify(_exhaustive)}`);
 }
 
 // src/commands/config/index.ts
@@ -9411,9 +10082,161 @@ function registerConfigCommand(program2) {
   registerConfigApplyCommand(cfg);
 }
 
+// src/commands/ai/setup.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync15, readFileSync as readFileSync13 } from "fs";
+import { isAbsolute, join as join17, relative as relative4, resolve as resolve8 } from "path";
+import * as clack17 from "@clack/prompts";
+import pc7 from "picocolors";
+
+// src/lib/api/ai.ts
+async function getOpenRouterApiKey() {
+  const res = await ossFetch("/api/ai/openrouter/api-key");
+  const data = await res.json();
+  const apiKey = typeof data.apiKey === "string" ? data.apiKey.trim() : "";
+  const maskedKey = typeof data.maskedKey === "string" ? data.maskedKey.trim() : void 0;
+  if (apiKey.length === 0) {
+    throw new CLIError(
+      "AI gateway returned no OpenRouter API key. Open the InsForge dashboard AI page and verify Model Gateway is configured."
+    );
+  }
+  return {
+    apiKey,
+    maskedKey
+  };
+}
+
+// src/commands/ai/setup.ts
+var DEFAULT_ENV_FILE = ".env.local";
+var OPENROUTER_ENV_KEY = "OPENROUTER_API_KEY";
+function registerAiSetupCommand(aiCmd2) {
+  aiCmd2.command("setup").description("Write the linked project OpenRouter key to a local env file").option("--env-file <path>", `Env file to update (default: ${DEFAULT_ENV_FILE})`).action(async (opts, cmd) => {
+    const { json } = getRootOpts(cmd);
+    try {
+      const result = await runAiSetup({
+        envFile: opts.envFile,
+        json
+      });
+      if (json) {
+        outputJson({ success: true, ...result });
+      }
+    } catch (err) {
+      handleError(err, json);
+    } finally {
+      await shutdownAnalytics();
+    }
+  });
+}
+async function runAiSetup(opts) {
+  const project = getProjectConfig();
+  if (!project) {
+    throw new ProjectNotLinkedError();
+  }
+  if (!opts.json) {
+    clack17.intro("AI setup");
+    outputSuccess(`Linked to InsForge project: ${project.project_name} (${project.project_id})`);
+  }
+  const spinner11 = !opts.json && isInteractive ? clack17.spinner() : null;
+  spinner11?.start("Fetching OpenRouter key...");
+  let key;
+  try {
+    key = await getOpenRouterApiKey();
+    spinner11?.stop("Fetched OpenRouter key.");
+  } catch (err) {
+    spinner11?.stop("Could not fetch OpenRouter key.");
+    throw err;
+  }
+  const envFile = opts.envFile ?? DEFAULT_ENV_FILE;
+  const envPath = resolve8(process.cwd(), envFile);
+  const envLabel = displayPath(envPath);
+  const update = upsertEnvFile(envPath, { [OPENROUTER_ENV_KEY]: key.apiKey });
+  const gitignoreUpdated = ensureLocalEnvIgnored(process.cwd(), envFile);
+  captureEvent(project.project_id, "cli_ai_setup", {
+    project_id: project.project_id,
+    project_name: project.project_name,
+    org_id: project.org_id,
+    region: project.region,
+    env_file: envLabel,
+    added: update.added.includes(OPENROUTER_ENV_KEY),
+    skipped: update.skipped.includes(OPENROUTER_ENV_KEY),
+    mismatched: update.mismatched.some((m) => m.key === OPENROUTER_ENV_KEY)
+  });
+  if (!opts.json) {
+    if (update.added.length > 0) {
+      outputSuccess(`Wrote ${envLabel}: ${update.added.join(", ")}`);
+    }
+    if (update.skipped.length > 0) {
+      outputInfo(pc7.dim(`${envLabel}: ${update.skipped.join(", ")} already set (matching) - left as-is.`));
+    }
+    for (const m of update.mismatched) {
+      clack17.log.warn(
+        `${envLabel} already has ${m.key}; left existing value untouched. Remove it or pass --env-file to write elsewhere.`
+      );
+    }
+    if (gitignoreUpdated) {
+      outputInfo(pc7.dim("Added .env*.local to .gitignore."));
+    }
+    if (!isLocalEnvFile(envFile)) {
+      clack17.log.warn(
+        `${envLabel} may be committed unless it is listed in .gitignore. Keep ${OPENROUTER_ENV_KEY} server-only.`
+      );
+    }
+    outputInfo("");
+    outputInfo("Use this key only from server-side code as process.env.OPENROUTER_API_KEY.");
+    outputInfo("For deployment, add OPENROUTER_API_KEY to your hosting provider environment.");
+    outputInfo(`Do not rename it to ${pc7.bold("NEXT_PUBLIC_")}, ${pc7.bold("VITE_")}, or ${pc7.bold("PUBLIC_")}.`);
+    clack17.outro("Done.");
+  }
+  return {
+    envFile: envLabel,
+    added: update.added,
+    skipped: update.skipped,
+    mismatched: update.mismatched.map((m) => m.key),
+    gitignoreUpdated,
+    maskedKey: key.maskedKey
+  };
+}
+function displayPath(path6) {
+  const rel = relative4(process.cwd(), path6);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+    return path6;
+  }
+  return rel;
+}
+function isLocalEnvFile(envFile) {
+  const normalized = envFile.replace(/\\/g, "/");
+  const basename8 = normalized.split("/").pop() ?? normalized;
+  return basename8 === ".env.local" || /^\.env\..+\.local$/.test(basename8);
+}
+function ensureLocalEnvIgnored(cwd, envFile) {
+  if (!isLocalEnvFile(envFile)) return false;
+  const envPath = resolve8(cwd, envFile);
+  const relEnvPath = relative4(cwd, envPath);
+  if (!relEnvPath || relEnvPath.startsWith("..") || isAbsolute(relEnvPath)) {
+    return false;
+  }
+  const gitignorePath = join17(cwd, ".gitignore");
+  const existing = existsSync15(gitignorePath) ? readFileSync13(gitignorePath, "utf-8") : "";
+  const lines = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+  const envBasename = envFile.replace(/\\/g, "/").split("/").pop() ?? envFile;
+  if (lines.has(".env*") || lines.has(".env.*") || lines.has(".env*.local") || lines.has(".env.local") && envBasename === ".env.local") {
+    return false;
+  }
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const spacer = existing.length > 0 ? "\n" : "";
+  appendFileSync2(gitignorePath, `${prefix}${spacer}# Local environment secrets
+.env*.local
+`);
+  return true;
+}
+
+// src/commands/ai/index.ts
+function registerAiCommands(aiCmd2) {
+  registerAiSetupCommand(aiCmd2);
+}
+
 // src/index.ts
 var __dirname = dirname3(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync13(join17(__dirname, "../package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync14(join18(__dirname, "../package.json"), "utf-8"));
 var INSFORGE_LOGO = `
 \u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D
@@ -9497,6 +10320,8 @@ registerComputeStopCommand(computeCmd);
 registerComputeEventsCommand(computeCmd);
 var posthogCmd = program.command("posthog").description("Manage PostHog product analytics integration");
 registerPosthogSetupCommand(posthogCmd);
+var aiCmd = program.command("ai").description("Manage AI model gateway setup");
+registerAiCommands(aiCmd);
 var schedulesCmd = program.command("schedules").description("Manage scheduled tasks (cron jobs)");
 registerSchedulesListCommand(schedulesCmd);
 registerSchedulesGetCommand(schedulesCmd);
@@ -9522,7 +10347,7 @@ async function showInteractiveMenu() {
   } catch {
   }
   console.log(INSFORGE_LOGO);
-  clack17.intro(`InsForge CLI v${pkg.version}`);
+  clack18.intro(`InsForge CLI v${pkg.version}`);
   const options = [];
   if (!isLoggedIn) {
     options.push({ value: "login", label: "Log in to InsForge" });
@@ -9543,7 +10368,7 @@ async function showInteractiveMenu() {
     options
   });
   if (isCancel2(action)) {
-    clack17.cancel("Bye!");
+    clack18.cancel("Bye!");
     process.exit(0);
   }
   switch (action) {