@rankcli/cli 0.0.29 → 0.0.30

package/dist/index.mjs

@@ -22,6 +22,7 @@ import open from "open";
 
 // src/lib/config.ts
 import Conf from "conf";
+import { createHash } from "crypto";
 import { createClient } from "@supabase/supabase-js";
 const INJECTED_CONFIG = {"supabaseUrl":"https://bspljbxwbjiqueeyzyat.supabase.co","supabaseAnonKey":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJzcGxqYnh3YmppcXVlZXl6eWF0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjkyNzQ1NTksImV4cCI6MjA4NDg1MDU1OX0.7gprxM2gT9cZ99sjZURLltrln78dEnwyFFKYpTzBaUU","webAppUrl":"https://rankcli.dev","decryptPassphrase":"lKFLeIw/xGPa6E8c4XswZX/oiLtJf/yLF/Y6zwovte8="};
 function getSupabaseUrl() {
@@ -61,6 +62,7 @@ function getApiUrl() {
 }
 var config = new Conf({
   projectName: "rankcli",
+  ...process.env.RANKCLI_CONFIG_DIR ? { cwd: process.env.RANKCLI_CONFIG_DIR } : {},
   schema: {
     accessToken: { type: "string" },
     refreshToken: { type: "string" },
@@ -71,7 +73,9 @@ var config = new Conf({
     apiKeyName: { type: "string" },
     planId: { type: "string" },
     planName: { type: "string" },
-    sitesLimit: { type: "number" }
+    sitesLimit: { type: "number" },
+    planKeyFingerprint: { type: "string" },
+    planCheckedAt: { type: "number" }
   }
 });
 var supabaseClient = null;
@@ -122,15 +126,17 @@ async function validateApiKey(apiKey) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "X-API-Key": apiKey
+        "X-API-Key": apiKey,
+        "X-Endpoint": "cli"
       }
     });
-    const data = await response.json();
+    const data = await response.json().catch(() => ({}));
     if (!response.ok) {
-      return { valid: false, error: data.error || "Invalid API key" };
+      return { valid: false, status: response.status, error: data.error || `Invalid API key (HTTP ${response.status})` };
     }
     return {
       valid: true,
+      status: response.status,
       user: data.user,
       subscription: data.subscription
     };
@@ -138,6 +144,50 @@ async function validateApiKey(apiKey) {
     return { valid: false, error: err instanceof Error ? err.message : "Validation failed" };
   }
 }
+function keyFingerprint(apiKey) {
+  return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+var PLAN_CACHE_MS = 6 * 60 * 60 * 1e3;
+async function ensureApiKeyPlan(options = {}) {
+  if (!isApiKeyAuth()) return null;
+  const apiKey = getApiKey();
+  const fingerprint = keyFingerprint(apiKey);
+  const sameKey = config.get("planKeyFingerprint") === fingerprint;
+  const fresh = sameKey && Date.now() - (config.get("planCheckedAt") || 0) < PLAN_CACHE_MS;
+  if (fresh && !options.force) {
+    return { status: "ok", planId: config.get("planId"), planName: config.get("planName") || "Free", email: config.get("email"), cached: true };
+  }
+  const result = await validateApiKey(apiKey);
+  if (result.valid) {
+    config.set("planKeyFingerprint", fingerprint);
+    config.set("planCheckedAt", Date.now());
+    if (result.user?.email) config.set("email", result.user.email);
+    if (result.subscription?.planId && result.subscription.planId !== "free") {
+      saveSubscription(result.subscription);
+    } else {
+      setFreePlan();
+    }
+    return { status: "ok", planId: config.get("planId"), planName: config.get("planName") || "Free", email: result.user?.email, cached: false };
+  }
+  if (result.status === 403) {
+    config.set("planKeyFingerprint", fingerprint);
+    config.set("planCheckedAt", Date.now());
+    setFreePlan();
+    return { status: "free" };
+  }
+  if (result.status === 401) {
+    config.delete("planKeyFingerprint");
+    setFreePlan();
+    return { status: "invalid", error: result.error || "Invalid API key" };
+  }
+  if (!sameKey) setFreePlan();
+  return { status: "unavailable", error: result.error || "Validation failed" };
+}
+function setFreePlan() {
+  config.delete("planId");
+  config.set("planName", "Free");
+  config.set("sitesLimit", 1);
+}
 async function getSession() {
   const accessToken = config.get("accessToken");
   const refreshToken = config.get("refreshToken");
@@ -197,6 +247,8 @@ function clearCredentials() {
   config.delete("planId");
   config.delete("planName");
   config.delete("sitesLimit");
+  config.delete("planKeyFingerprint");
+  config.delete("planCheckedAt");
 }
 function getUserInfo() {
   return {
@@ -231,7 +283,7 @@ async function browserLogin(spinner) {
   } catch (err) {
     spinner.fail("Could not start login");
     console.log(chalk.red(err instanceof Error ? err.message : "Network error"));
-    return;
+    return false;
   }
   spinner.text = "Opening browser to approve...";
   try {
@@ -242,6 +294,10 @@ async function browserLogin(spinner) {
 If a browser didn't open, visit:
 ${start.url}
 `));
+  if (start.userCode) {
+    console.log(`Approve in your browser only if it shows this code: ${chalk.bold(start.userCode)}
+`);
+  }
   const deadline = Date.now() + start.expiresInSeconds * 1e3;
   spinner.text = "Waiting for approval in your browser...";
   while (Date.now() < deadline) {
@@ -259,58 +315,75 @@ ${start.url}
     }
     if (status.status === "claimed" && status.apiKey) {
       saveApiKey(status.apiKey, status.apiKeyName, status.email);
-      await fetchAndSaveSubscription();
+      await ensureApiKeyPlan({ force: true });
       spinner.succeed(`Logged in as ${chalk.green(status.email)}`);
-      return;
+      return true;
     }
     if (status.status === "expired" || status.status === "not_found") {
       spinner.fail("Login link expired");
       console.log(chalk.dim('Run "rankcli login" again.'));
-      return;
+      return false;
     }
   }
   spinner.fail("Timed out waiting for approval");
   console.log(chalk.dim(`Run "rankcli login" again when you're ready.`));
+  return false;
+}
+async function verifyApiKey(spinner, source) {
+  spinner.start("Validating API key...");
+  const plan = await ensureApiKeyPlan({ force: true });
+  if (!plan || plan.status === "invalid") {
+    spinner.fail("Invalid API key");
+    console.log(chalk.red(`
+${plan?.error || "The key was rejected"}`));
+    return 1;
+  }
+  if (plan.status === "unavailable") {
+    spinner.fail("Could not validate API key");
+    console.log(chalk.red(`
+${plan.error}`));
+    return 1;
+  }
+  spinner.succeed(`Authenticated via ${source}`);
+  const { email, planName } = getUserInfo();
+  if (email) console.log(chalk.dim(`
+Email: ${email}`));
+  console.log(chalk.dim(`${email ? "" : "\n"}Plan: ${planName || "Free"}`));
+  if (plan.status === "free") {
+    console.log(chalk.dim("The key works for dashboard sync; the paid checks and API features need a paid plan."));
+  }
+  return 0;
 }
 async function login(options) {
+  const spinner = ora();
+  if (options.token !== void 0) {
+    const apiKey = options.token.trim();
+    if (!apiKey.startsWith("rankcli_")) {
+      console.log(chalk.red(apiKey ? 'Invalid API key format. Keys should start with "rankcli_"' : "Empty API key - is the RANKCLI_API_KEY secret set?"));
+      return 1;
+    }
+    if (process.env.RANKCLI_API_KEY && process.env.RANKCLI_API_KEY !== apiKey) {
+      console.log(chalk.red("RANKCLI_API_KEY is set to a different key and would take precedence over --token. Unset it or pass the same key."));
+      return 1;
+    }
+    clearCredentials();
+    saveApiKey(apiKey);
+    const code = await verifyApiKey(spinner, "API key");
+    if (code !== 0) clearCredentials();
+    return code;
+  }
+  if (process.env.RANKCLI_API_KEY) {
+    return verifyApiKey(spinner, "RANKCLI_API_KEY");
+  }
   if (isLoggedIn()) {
     const { email } = getUserInfo();
     console.log(chalk.yellow(`Already logged in as ${email}`));
     console.log(chalk.dim('Run "rankcli logout" to sign out first.'));
-    return;
+    return 0;
   }
-  const spinner = ora();
   try {
-    if (options.token) {
-      const apiKey = options.token;
-      if (!apiKey.startsWith("rankcli_")) {
-        console.log(chalk.red('Invalid API key format. Keys should start with "rankcli_"'));
-        return;
-      }
-      spinner.start("Validating API key...");
-      const result = await validateApiKey(apiKey);
-      if (!result.valid) {
-        spinner.fail("Invalid API key");
-        console.log(chalk.red(`
-${result.error}`));
-        return;
-      }
-      saveApiKey(apiKey);
-      if (result.subscription) {
-        saveSubscription({
-          planId: result.subscription.planId,
-          planName: result.subscription.planName,
-          sitesLimit: result.subscription.sitesLimit
-        });
-      }
-      spinner.succeed(`Authenticated via API key`);
-      console.log(chalk.dim(`
-Email: ${result.user?.email}`));
-      console.log(chalk.dim(`Plan: ${result.subscription?.planName || "Free"}`));
-      return;
-    }
     if (options.browser !== false && !options.email) {
-      await browserLogin(spinner);
+      return await browserLogin(spinner) ? 0 : 1;
     } else {
       let email = options.email;
       if (!email) {
@@ -349,11 +422,11 @@ ${error.message}`));
           console.log(chalk.dim("\nDon't have an account? Sign up at:"));
           console.log(chalk.cyan(`  ${WEB_APP_URL}/signup`));
         }
-        return;
+        return 1;
       }
       if (!data.session) {
         spinner.fail("No session returned");
-        return;
+        return 1;
       }
       saveSession(data.session);
       await fetchAndSaveSubscription();
@@ -361,10 +434,12 @@ ${error.message}`));
       const { planName, sitesLimit } = getUserInfo();
       console.log(chalk.dim(`
 Plan: ${planName} (${sitesLimit} site${sitesLimit !== 1 ? "s" : ""})`));
+      return 0;
     }
   } catch (err) {
     spinner.fail("Login failed");
     console.error(chalk.red(err instanceof Error ? err.message : "Unknown error"));
+    return 1;
   }
 }
 async function logout() {
@@ -394,16 +469,10 @@ async function whoami() {
   const spinner = ora("Checking account...").start();
   try {
     if (isApiKeyAuth()) {
-      const apiKey = getApiKey();
-      if (apiKey) {
-        const result = await validateApiKey(apiKey);
-        if (result.valid && result.subscription) {
-          saveSubscription({
-            planId: result.subscription.planId,
-            planName: result.subscription.planName,
-            sitesLimit: result.subscription.sitesLimit
-          });
-        }
+      const plan = await ensureApiKeyPlan({ force: true });
+      if (plan?.status === "invalid") {
+        spinner.fail(`API key rejected: ${plan.error}`);
+        return;
       }
     } else {
       await fetchAndSaveSubscription();
@@ -481,7 +550,10 @@ async function setup(options) {
     await setupGSC(projectPath, options.gsc);
   }
   if (options.githubAction) {
-    await setupGitHubAction(projectPath, options.schedule || "weekly");
+    if (!options.url) {
+      console.log("\u2139\uFE0F  No --url given - the workflow audits https://example.com until you edit SITE_URL in it.\n");
+    }
+    await setupGitHubAction(projectPath, options.schedule || "weekly", options.url, options.sync);
   }
 }
 async function interactiveSetup(projectPath) {
@@ -614,9 +686,12 @@ async function setupGitHubAction(projectPath, schedule, siteUrl, syncToDashboard
     siteUrl: siteUrl || "https://example.com",
     features: {
       audit: true,
-      autoFix: true,
+      // `rankcli fix --auto` needs a Solo+ plan, which the workflow can
+      // only prove with a RANKCLI_API_KEY secret - without one the step
+      // is always tier-blocked, so don't generate it.
+      autoFix: !!syncToDashboard,
       createIssues: true,
-      createPRs: true
+      createPRs: !!syncToDashboard
     },
     syncToDashboard
   };
@@ -1054,6 +1129,11 @@ var TIER_LIMITS = {
     features: { geo: true, auto_fix: true, github: true, ai: true }
   }
 };
+function tierFromPlanId(planId) {
+  if (!planId) return void 0;
+  const base = planId.toLowerCase().replace(/^ltd_/, "").replace(/_(annual|yearly|monthly|founding|lifetime|ltd)$/, "");
+  return base === "free" || base === "solo" || base === "pro" || base === "agency" ? base : void 0;
+}
 var UPSELL_MESSAGES = {
   // After free audit completes
   free_audit_complete: () => [
@@ -1206,100 +1286,403 @@ function hasFeature(tier, feature) {
 // src/models.ts
 var OPENAI_FAST = "gpt-5.6-luna";
 var ANTHROPIC_FAST = "claude-haiku-4-5-20251001";
+var OPENROUTER_DEFAULT = "openrouter/free";
+var GROQ_DEFAULT = "llama-3.3-70b-versatile";
+var GEMINI_DEFAULT = "gemini-3.7-flash";
+var DEEPSEEK_DEFAULT = "deepseek-flash";
+var MISTRAL_DEFAULT = "mistral-small-latest";
+var TOGETHER_DEFAULT = "openai/gpt-oss-120b";
+var FIREWORKS_DEFAULT = "accounts/fireworks/models/gpt-oss-120b";
+var CEREBRAS_DEFAULT = "gpt-oss-120b";
 
-// src/commands/audit.ts
-var { detectFramework: detectFramework2, getFrameworkDisplayName } = frameworks;
-async function fetchHtml(url, timeout = 1e4) {
+// src/lib/ai.ts
+var AI_PROVIDERS = {
+  // Hosted
+  openrouter: { label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1", model: OPENROUTER_DEFAULT, envKeys: ["OPENROUTER_API_KEY"] },
+  openai: { label: "OpenAI", baseUrl: "https://api.openai.com/v1", model: OPENAI_FAST, envKeys: ["OPENAI_API_KEY"], jsonMode: true },
+  anthropic: { label: "Anthropic", baseUrl: "https://api.anthropic.com/v1", model: ANTHROPIC_FAST, envKeys: ["ANTHROPIC_API_KEY"], anthropic: true },
+  groq: { label: "Groq", baseUrl: "https://api.groq.com/openai/v1", model: GROQ_DEFAULT, envKeys: ["GROQ_API_KEY"], jsonMode: true },
+  gemini: { label: "Gemini", baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", model: GEMINI_DEFAULT, envKeys: ["GEMINI_API_KEY", "GOOGLE_API_KEY"] },
+  deepseek: { label: "DeepSeek", baseUrl: "https://api.deepseek.com", model: DEEPSEEK_DEFAULT, envKeys: ["DEEPSEEK_API_KEY"], jsonMode: true },
+  mistral: { label: "Mistral", baseUrl: "https://api.mistral.ai/v1", model: MISTRAL_DEFAULT, envKeys: ["MISTRAL_API_KEY"], jsonMode: true },
+  cerebras: { label: "Cerebras", baseUrl: "https://api.cerebras.ai/v1", model: CEREBRAS_DEFAULT, envKeys: ["CEREBRAS_API_KEY"] },
+  together: { label: "Together", baseUrl: "https://api.together.xyz/v1", model: TOGETHER_DEFAULT, envKeys: ["TOGETHER_API_KEY"] },
+  fireworks: { label: "Fireworks", baseUrl: "https://api.fireworks.ai/inference/v1", model: FIREWORKS_DEFAULT, envKeys: ["FIREWORKS_API_KEY"] },
+  // Local / self-hosted
+  ollama: { label: "Ollama", baseUrl: "http://localhost:11434/v1", envKeys: [], local: true },
+  lmstudio: { label: "LM Studio", baseUrl: "http://localhost:1234/v1", envKeys: [], local: true },
+  llamacpp: { label: "llama.cpp", baseUrl: "http://localhost:8080/v1", envKeys: [], local: true },
+  vllm: { label: "vLLM", baseUrl: "http://localhost:8000/v1", envKeys: [], local: true },
+  custom: { label: "OpenAI-compatible server", envKeys: [], local: true }
+};
+var AI_PROVIDER_IDS = Object.keys(AI_PROVIDERS);
+var DETECT_ORDER = ["openrouter", "groq", "gemini", "deepseek", "cerebras", "mistral", "together", "fireworks", "anthropic", "openai"];
+var AI_ENV_KEYS = DETECT_ORDER.flatMap((id) => AI_PROVIDERS[id].envKeys);
+function providerFromKey(key) {
+  if (key.startsWith("sk-or-")) return "openrouter";
+  if (key.startsWith("sk-ant-")) return "anthropic";
+  if (key.startsWith("gsk_")) return "groq";
+  if (key.startsWith("AIza")) return "gemini";
+  if (key.startsWith("csk-")) return "cerebras";
+  return void 0;
+}
+function ollamaBaseUrl(env) {
+  const raw = env.OLLAMA_HOST?.trim();
+  if (!raw) return AI_PROVIDERS.ollama.baseUrl;
   try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    const response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        "User-Agent": "RankCLI-Bot/1.0 (+https://rankcli.dev/bot)",
-        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
-      }
-    });
-    clearTimeout(timeoutId);
-    if (!response.ok) {
-      return null;
-    }
-    return await response.text();
+    const hasScheme = /^https?:\/\//i.test(raw);
+    const u = new URL(hasScheme ? raw : `http://${raw}`);
+    if (!hasScheme && !/:\d+$/.test(raw)) u.port = "11434";
+    if (u.hostname === "0.0.0.0") u.hostname = "127.0.0.1";
+    return `${u.origin}/v1`;
+  } catch {
+    return AI_PROVIDERS.ollama.baseUrl;
+  }
+}
+async function fetchWithTimeout(url, init2, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init2, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function probeOllama(baseUrl, timeoutMs = 800) {
+  try {
+    const origin = new URL(baseUrl).origin;
+    const res = await fetchWithTimeout(`${origin}/api/tags`, {}, timeoutMs);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return (data.models || []).map((m) => m.name || m.model || "").filter(Boolean);
   } catch {
     return null;
   }
 }
-var AI_PROVIDER_DEFAULTS = {
-  openai: { baseUrl: "https://api.openai.com/v1", model: OPENAI_FAST },
-  openrouter: { baseUrl: "https://openrouter.ai/api/v1", model: "deepseek/deepseek-r1:free" },
-  groq: { baseUrl: "https://api.groq.com/openai/v1", model: "llama-3.3-70b-versatile" },
-  gemini: { baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", model: "gemini-2.0-flash" }
-};
-async function runAIAnalysis(url, issues, provider, apiKey) {
-  const isAnthropic = provider === "anthropic";
-  const providerConfig = AI_PROVIDER_DEFAULTS[provider] || AI_PROVIDER_DEFAULTS.openai;
-  const apiUrl = isAnthropic ? "https://api.anthropic.com/v1/messages" : `${providerConfig.baseUrl}/chat/completions`;
-  const prompt = `Analyze these SEO audit results and provide prioritized recommendations:
+async function firstServerModel(baseUrl, apiKey) {
+  try {
+    const res = await fetchWithTimeout(`${baseUrl}/models`, {
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+    }, 5e3);
+    if (!res.ok) return {};
+    const data = await res.json();
+    return { model: data.data?.find((m) => m.id)?.id };
+  } catch {
+    return { unreachable: true };
+  }
+}
+function noProviderHints() {
+  return [
+    `Set one of ${AI_ENV_KEYS.join(", ")}, or pass --ai-key`,
+    "Or run a local model: start Ollama (https://ollama.com) and `ollama pull llama3.2` - it is picked up automatically",
+    "Or point at any OpenAI-compatible server: --ai-base-url http://localhost:8080/v1 --ai-model <name>"
+  ];
+}
+async function resolveAIProvider(opts, env = process.env, probe = probeOllama) {
+  let provider = opts.aiProvider?.trim().toLowerCase();
+  let notice;
+  let ollamaModels = null;
+  if (provider && !AI_PROVIDERS[provider]) {
+    return {
+      ok: false,
+      error: `Unknown AI provider "${opts.aiProvider}"`,
+      hints: [`Choose one of: ${AI_PROVIDER_IDS.join(", ")}`]
+    };
+  }
+  if (!provider) {
+    if (opts.aiBaseUrl) {
+      provider = "custom";
+    } else if (opts.aiKey) {
+      provider = providerFromKey(opts.aiKey) ?? "openai";
+    } else {
+      provider = DETECT_ORDER.find((id) => AI_PROVIDERS[id].envKeys.some((k) => env[k]));
+    }
+  }
+  if (!provider) {
+    const base = ollamaBaseUrl(env);
+    ollamaModels = await probe(base);
+    if (ollamaModels === null) {
+      return { ok: false, error: "AI analysis requested but no AI provider is configured", hints: noProviderHints() };
+    }
+    provider = "ollama";
+    notice = `No AI key set - using local Ollama at ${base}`;
+  }
+  const preset = AI_PROVIDERS[provider];
+  const baseUrl = (opts.aiBaseUrl || (provider === "ollama" ? ollamaBaseUrl(env) : preset.baseUrl) || "").replace(/\/+$/, "");
+  if (!baseUrl) {
+    return {
+      ok: false,
+      error: "The custom provider needs --ai-base-url",
+      hints: ["e.g. --ai-base-url http://localhost:8080/v1 --ai-model <name>"]
+    };
+  }
+  try {
+    new URL(baseUrl);
+  } catch {
+    return { ok: false, error: `Invalid --ai-base-url "${opts.aiBaseUrl}"`, hints: ["Use a full URL such as http://localhost:11434/v1"] };
+  }
+  const apiKey = opts.aiKey || preset.envKeys.map((k) => env[k]).find(Boolean) || void 0;
+  if (!apiKey && !preset.local) {
+    return {
+      ok: false,
+      error: `No API key for ${preset.label}`,
+      hints: [`Set ${preset.envKeys.join(" or ")}, or pass --ai-key`]
+    };
+  }
+  let model = opts.aiModel || preset.model;
+  if (!model && provider === "ollama") {
+    ollamaModels ??= await probe(baseUrl);
+    if (ollamaModels === null) {
+      return { ok: false, error: `Could not reach Ollama at ${baseUrl}`, hints: ["Start it with `ollama serve`, or set OLLAMA_HOST"] };
+    }
+    model = ollamaModels.find((name) => !/embed/i.test(name));
+    if (!model) {
+      return { ok: false, error: "Ollama is running but has no chat models installed", hints: ["Install one, e.g. `ollama pull llama3.2`, or pass --ai-model"] };
+    }
+  }
+  if (!model) {
+    const found = await firstServerModel(baseUrl, apiKey);
+    if (found.unreachable) {
+      return { ok: false, error: `Could not reach ${preset.label} at ${baseUrl}`, hints: ["Is the server running? Or pass a different --ai-base-url"] };
+    }
+    model = found.model;
+    if (!model) {
+      return { ok: false, error: `${preset.label} at ${baseUrl} did not report a loaded model`, hints: ["Pass --ai-model <name>"] };
+    }
+  }
+  if (notice) notice += ` (model ${model})`;
+  return {
+    ok: true,
+    ai: {
+      provider,
+      label: preset.label,
+      baseUrl,
+      model,
+      apiKey,
+      // A base-URL override may point anywhere; only trust JSON mode on the real endpoint.
+      jsonMode: !!preset.jsonMode && !opts.aiBaseUrl,
+      anthropic: !!preset.anthropic,
+      local: !!preset.local,
+      notice
+    }
+  };
+}
+function tryParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    try {
+      return JSON.parse(text.replace(/,\s*([}\]])/g, "$1"));
+    } catch {
+      return void 0;
+    }
+  }
+}
+function balancedObjectAt(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+function extractJsonObject(content) {
+  const text = content.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const sources = fenced ? [fenced[1], text] : [text];
+  for (const source of sources) {
+    let from = source.indexOf("{");
+    let attempts = 0;
+    while (from !== -1 && attempts++ < 50) {
+      const candidate = balancedObjectAt(source, from);
+      if (candidate) {
+        const parsed = tryParse(candidate);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+      }
+      from = source.indexOf("{", from + 1);
+    }
+  }
+  return null;
+}
+function normalizeAnalysis(raw) {
+  const score = Number(raw.contentScore);
+  const suggestions = Array.isArray(raw.suggestions) ? raw.suggestions.map((s) => typeof s === "string" ? s : JSON.stringify(s)).filter(Boolean) : [];
+  const prioritizedFixes = Array.isArray(raw.prioritizedFixes) ? raw.prioritizedFixes.filter((f) => !!f && typeof f === "object" && "code" in f).map((f) => ({
+    code: String(f.code),
+    priority: Number(f.priority) || 3,
+    rationale: String(f.rationale ?? "")
+  })) : [];
+  if (!Number.isFinite(score) && suggestions.length === 0 && prioritizedFixes.length === 0) return null;
+  return {
+    contentScore: Number.isFinite(score) ? Math.max(0, Math.min(100, Math.round(score))) : 0,
+    suggestions,
+    prioritizedFixes
+  };
+}
+var SEVERITY_ORDER = { critical: 0, error: 1, warning: 2, notice: 3, info: 3 };
+var MAX_ISSUES_IN_PROMPT = 60;
+function buildPrompt(url, issues) {
+  const ranked = [...issues].sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 4) - (SEVERITY_ORDER[b.severity] ?? 4));
+  const shown = ranked.slice(0, MAX_ISSUES_IN_PROMPT);
+  const more = ranked.length > shown.length ? `
+(${ranked.length - shown.length} lower-severity issues omitted)` : "";
+  return `Analyze these SEO audit results and provide prioritized recommendations:
 
 URL: ${url}
 
 Issues found:
-${issues.map((i) => `- [${i.severity.toUpperCase()}] ${i.code}: ${i.title}`).join("\n")}
+${shown.map((i) => `- [${i.severity.toUpperCase()}] ${i.code}: ${i.title}`).join("\n")}${more}
 
-Return JSON with:
+Respond with only this JSON object - no prose, no code fences:
 {
   "contentScore": <0-100 overall content quality>,
-  "suggestions": [<3-5 high-impact suggestions>],
+  "suggestions": [<3-5 high-impact suggestions, as strings>],
   "prioritizedFixes": [
     {"code": "<issue code>", "priority": <1-5>, "rationale": "<why fix this first>"}
   ]
 }`;
-  try {
-    const headers = {
-      "Content-Type": "application/json"
+}
+async function runAIAnalysis(url, issues, ai) {
+  const prompt = buildPrompt(url, issues);
+  const system = "You are an SEO expert. Respond with valid JSON only.";
+  const timeoutMs = ai.local ? 3e5 : 9e4;
+  const maxTokens = 4096;
+  const headers = { "Content-Type": "application/json" };
+  let endpoint;
+  let body;
+  if (ai.anthropic) {
+    endpoint = `${ai.baseUrl}/messages`;
+    headers["x-api-key"] = ai.apiKey || "";
+    headers["anthropic-version"] = "2023-06-01";
+    body = { model: ai.model, max_tokens: maxTokens, system, messages: [{ role: "user", content: prompt }] };
+  } else {
+    endpoint = `${ai.baseUrl}/chat/completions`;
+    if (ai.apiKey) headers["Authorization"] = `Bearer ${ai.apiKey}`;
+    if (ai.provider === "openrouter") {
+      headers["HTTP-Referer"] = "https://rankcli.dev";
+      headers["X-Title"] = "RankCLI";
+    }
+    body = {
+      model: ai.model,
+      messages: [
+        { role: "system", content: system },
+        { role: "user", content: prompt }
+      ],
+      // OpenAI's GPT-5.6 rejects max_tokens (and temperature); everyone else expects max_tokens.
+      ...ai.provider === "openai" && !ai.local ? { max_completion_tokens: maxTokens } : { max_tokens: maxTokens },
+      ...ai.jsonMode ? { response_format: { type: "json_object" } } : {}
     };
-    let body;
-    if (isAnthropic) {
-      headers["x-api-key"] = apiKey;
-      headers["anthropic-version"] = "2023-06-01";
-      body = JSON.stringify({
-        model: ANTHROPIC_FAST,
-        max_tokens: 1500,
-        messages: [{ role: "user", content: prompt }]
-      });
-    } else {
-      headers["Authorization"] = `Bearer ${apiKey}`;
-      if (provider === "openrouter") {
-        headers["HTTP-Referer"] = "https://rankcli.dev";
-        headers["X-Title"] = "RankCLI";
-      }
-      body = JSON.stringify({
-        model: providerConfig.model,
-        messages: [
-          { role: "system", content: "You are an SEO expert. Respond with valid JSON only." },
-          { role: "user", content: prompt }
-        ],
-        // OpenAI's GPT-5.6 rejects max_tokens; other OpenAI-compatible servers still expect it.
-        ...provider === "openai" ? { max_completion_tokens: 1500 } : { max_tokens: 1500 },
-        // json_object mode is an OpenAI-specific extension - Groq supports
-        // it too, but not every OpenAI-compatible server does, so only
-        // request it for providers confirmed to support it.
-        ...provider === "openai" || provider === "groq" ? { response_format: { type: "json_object" } } : {}
-      });
+  }
+  let response;
+  try {
+    response = await fetchWithTimeout(endpoint, { method: "POST", headers, body: JSON.stringify(body) }, timeoutMs);
+  } catch (error) {
+    const reason = error instanceof Error && error.name === "AbortError" ? `timed out after ${Math.round(timeoutMs / 1e3)}s` : error instanceof Error ? error.cause instanceof Error ? error.cause.message : error.message : String(error);
+    return { error: `${ai.label} request failed: ${reason}` };
+  }
+  if (!response.ok) {
+    const detail = (await response.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 200);
+    return { error: `${ai.label} returned HTTP ${response.status}${detail ? `: ${detail}` : ""}` };
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    return { error: `${ai.label} returned a non-JSON response` };
+  }
+  const content = ai.anthropic ? data.content?.filter((b) => typeof b.text === "string").map((b) => b.text).join("") : data.choices?.[0]?.message?.content;
+  if (!content) {
+    return { error: `${ai.label} returned no content (a reasoning model may have used its whole token budget - try another --ai-model)` };
+  }
+  const parsed = extractJsonObject(content);
+  const analysis = parsed ? normalizeAnalysis(parsed) : null;
+  if (!analysis) {
+    return { error: `${ai.label} (${ai.model}) did not return the requested JSON` };
+  }
+  return { analysis };
+}
+
+// src/commands/audit.ts
+var { detectFramework: detectFramework2, getFrameworkDisplayName } = frameworks;
+var EXIT_CODES = {
+  /** Audit completed and no --fail-on / --min-score gate tripped. */
+  OK: 0,
+  /** A --fail-on or --min-score gate tripped. */
+  GATE_FAILED: 1,
+  /** Bad invocation: missing/invalid --url or an invalid flag value. */
+  USAGE: 2,
+  /** No real audit: the site was unreachable, the URL answered 4xx/5xx, no page could be analyzed, or an internal error. */
+  AUDIT_FAILED: 3
+};
+var FAIL_ON_LEVELS = ["error", "warning", "notice"];
+var SEVERITY_RANK = { critical: 4, error: 3, warning: 2, notice: 1, info: 1 };
+function evaluateGate(issues, score, failOn, minScore) {
+  const failures = [];
+  if (failOn) {
+    const threshold = SEVERITY_RANK[failOn];
+    const hits = issues.filter((i) => (SEVERITY_RANK[i.severity] ?? 0) >= threshold);
+    if (hits.length > 0) {
+      const counts = /* @__PURE__ */ new Map();
+      for (const i of hits) counts.set(i.severity, (counts.get(i.severity) || 0) + 1);
+      const breakdown = [...counts.entries()].sort((a, b) => (SEVERITY_RANK[b[0]] ?? 0) - (SEVERITY_RANK[a[0]] ?? 0)).map(([severity, n]) => `${n} ${severity}`).join(", ");
+      failures.push(`${hits.length} issue${hits.length === 1 ? "" : "s"} at or above --fail-on ${failOn} (${breakdown})`);
+    }
+  }
+  if (minScore !== void 0 && score < minScore) {
+    failures.push(`score ${score} is below --min-score ${minScore}`);
+  }
+  return { failOn, minScore, passed: failures.length === 0, failures };
+}
+function parseGateOptions(options) {
+  let failOn;
+  let minScore;
+  if (options.failOn !== void 0) {
+    const level = String(options.failOn).trim().toLowerCase();
+    if (!FAIL_ON_LEVELS.includes(level)) {
+      return { error: `Invalid --fail-on "${options.failOn}" (use ${FAIL_ON_LEVELS.join(", ")})` };
+    }
+    failOn = level;
+  }
+  if (options.minScore !== void 0) {
+    const raw = String(options.minScore).trim();
+    const n = Number(raw);
+    if (raw === "" || !Number.isFinite(n) || n < 0 || n > 100) {
+      return { error: `Invalid --min-score "${options.minScore}" (use a number from 0 to 100)` };
     }
-    const response = await fetch(apiUrl, { method: "POST", headers, body });
+    minScore = n;
+  }
+  return { failOn, minScore };
+}
+async function fetchHtml(url, timeout = 1e4) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "RankCLI-Bot/1.0 (+https://rankcli.dev/bot)",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+      }
+    });
+    clearTimeout(timeoutId);
     if (!response.ok) {
-      console.error(chalk4.yellow(`AI analysis failed: ${response.status}`));
       return null;
     }
-    const data = await response.json();
-    const content = isAnthropic ? data.content?.[0]?.text : data.choices?.[0]?.message?.content;
-    if (!content) return null;
-    const jsonMatch = content.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) return null;
-    return JSON.parse(jsonMatch[0]);
-  } catch (error) {
-    console.error(chalk4.yellow(`AI analysis error: ${error}`));
+    return await response.text();
+  } catch {
     return null;
   }
 }
@@ -1311,6 +1694,9 @@ function mergeIssues(issueArrays) {
       if (existing) {
         const urls = /* @__PURE__ */ new Set([...existing.affectedUrls || [], ...issue.affectedUrls || []]);
         existing.affectedUrls = Array.from(urls);
+        if ((SEVERITY_RANK[issue.severity] ?? 0) > (SEVERITY_RANK[existing.severity] ?? 0)) {
+          existing.severity = issue.severity;
+        }
       } else {
         issueMap.set(issue.code, { ...issue });
       }
@@ -1356,9 +1742,9 @@ async function syncToCloud(url, report, mergedIssues, pagesAudited, aiAnalysis,
     const data = await res.json();
     if (!res.ok) {
       if (data.error === "project_limit_reached") {
-        console.log(chalk4.yellow(`
+        console.error(chalk4.yellow(`
 \u26A0\uFE0F  Project limit reached (${data.count}/${data.limit})`));
-        console.log(chalk4.dim(`   Upgrade at: ${WEB_APP_URL}/account`));
+        console.error(chalk4.dim(`   Upgrade at: ${WEB_APP_URL}/account`));
       } else {
         console.error(chalk4.dim(data.error || "Cloud sync failed"));
       }
@@ -1374,60 +1760,70 @@ async function syncToCloud(url, report, mergedIssues, pagesAudited, aiAnalysis,
     return null;
   }
 }
+function printUsage(loggedIn) {
+  console.error("\n\u26A0\uFE0F  Please provide a URL to audit:");
+  console.error("   rankcli audit --url https://your-site.com");
+  console.error('\nRun "rankcli audit --help" for every option, exit codes, and AI providers.');
+  if (!loggedIn) {
+    console.error(chalk4.dim("\nTip: Log in to sync results to the web dashboard:"));
+    console.error(chalk4.dim("   rankcli login"));
+  }
+  console.error("");
+}
 async function audit(options) {
   const url = options.url;
-  const maxPages = parseInt(options.maxPages || "5", 10);
-  const enableAI = options.ai || false;
-  const detectedProvider = options.aiProvider || (process.env.OPENROUTER_API_KEY ? "openrouter" : process.env.GROQ_API_KEY ? "groq" : process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY ? "gemini" : process.env.ANTHROPIC_API_KEY ? "anthropic" : "openai");
-  const aiProvider = detectedProvider;
-  const providerEnvKey = {
-    openai: process.env.OPENAI_API_KEY,
-    anthropic: process.env.ANTHROPIC_API_KEY,
-    openrouter: process.env.OPENROUTER_API_KEY,
-    groq: process.env.GROQ_API_KEY,
-    gemini: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY
-  };
-  const aiKey = options.aiKey || providerEnvKey[aiProvider] || "";
-  const loggedIn = isLoggedIn();
-  const { planId } = getUserInfo();
-  const tierId = planId && planId in TIER_LIMITS ? planId : loggedIn ? "free" : "free_anon";
-  const checksLimit = TIER_LIMITS[tierId].checks;
-  let premiumChecks;
-  if (checksLimit > TIER_LIMITS.free.checks) {
-    const passphrase = getDecryptPassphrase();
-    if (passphrase) {
-      try {
-        await initEngine(passphrase);
-        premiumChecks = await getPremiumChecks();
-      } catch (error) {
-        console.error(chalk4.dim(`(premium checks unavailable: ${error instanceof Error ? error.message : error})`));
-      }
+  const json = options.output === "json";
+  const fail = (code, message, extra = {}) => {
+    if (json) {
+      console.log(JSON.stringify({ url: url ?? null, error: message, exitCode: code, ...extra }, null, 2));
+    } else {
+      console.error(`
+\u274C ${message}
+`);
     }
-  }
+    return code;
+  };
+  const gate = parseGateOptions(options);
+  if (gate.error) return fail(EXIT_CODES.USAGE, gate.error);
   if (!url) {
-    console.log("\n\u26A0\uFE0F  Please provide a URL to audit:");
-    console.log("   rankcli audit --url https://your-site.com");
-    console.log("\nOptions:");
-    console.log("   --max-pages <n>     Max pages to crawl (default: 5)");
-    console.log("   --ai                Enable AI analysis");
-    console.log("   --ai-provider <p>   AI provider: openai, anthropic, openrouter, groq, or gemini (auto-detected from env if omitted)");
-    console.log("   --ai-key <key>      API key (or set OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, or GEMINI_API_KEY)");
-    console.log("   --output json       Output as JSON");
-    if (!loggedIn) {
-      console.log(chalk4.dim("\nTip: Log in to sync results to the web dashboard:"));
-      console.log(chalk4.dim("   rankcli login"));
-    }
-    console.log("");
-    return;
+    if (json) return fail(EXIT_CODES.USAGE, "No URL given - use --url https://your-site.com");
+    printUsage(isLoggedIn());
+    return EXIT_CODES.USAGE;
   }
   try {
-    new URL(url);
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("not http(s)");
   } catch {
-    console.log("\n\u274C Invalid URL format. Please provide a valid URL.\n");
-    return;
+    return fail(EXIT_CODES.USAGE, `Invalid URL "${url}" - use a full http(s) URL such as https://example.com`);
   }
-  const startTime = Date.now();
+  if (options.ai && options.aiProvider && !AI_PROVIDERS[options.aiProvider.trim().toLowerCase()]) {
+    return fail(EXIT_CODES.USAGE, `Unknown --ai-provider "${options.aiProvider}" (use ${AI_PROVIDER_IDS.join(", ")})`);
+  }
+  const maxPages = Math.max(1, parseInt(options.maxPages || "5", 10) || 5);
   try {
+    const loggedIn = isLoggedIn();
+    const keyPlan = await ensureApiKeyPlan();
+    if (keyPlan?.status === "invalid") {
+      console.error(chalk4.yellow(`\u26A0\uFE0F  RankCLI API key rejected (${keyPlan.error}) - auditing on the Free tier.`));
+    } else if (keyPlan?.status === "unavailable") {
+      console.error(chalk4.dim(`(could not verify your RankCLI plan: ${keyPlan.error})`));
+    }
+    const { planId } = getUserInfo();
+    const tierId = tierFromPlanId(planId) ?? (loggedIn ? "free" : "free_anon");
+    const checksLimit = TIER_LIMITS[tierId].checks;
+    let premiumChecks;
+    if (checksLimit > TIER_LIMITS.free.checks) {
+      const passphrase = getDecryptPassphrase();
+      if (passphrase) {
+        try {
+          await initEngine(passphrase);
+          premiumChecks = await getPremiumChecks();
+        } catch (error) {
+          console.error(chalk4.dim(`(premium checks unavailable: ${error instanceof Error ? error.message : error})`));
+        }
+      }
+    }
+    const startTime = Date.now();
     const discoverySpinner = ora2("Discovering pages...").start();
     let pagesToAudit = [url];
     const homepageHtml = await fetchHtml(url, 1e4);
@@ -1447,6 +1843,7 @@ async function audit(options) {
       try {
         const report = await runFullAudit({
           url: pageUrl,
+          auditRootUrl: url,
           maxPages: 1,
           checkBrokenLinks: options.checkLinks || false,
           // Bundled with --check-links: both mean "verify actual link
@@ -1483,40 +1880,68 @@ async function audit(options) {
     }
     if (!primaryReport) {
       auditSpinner.fail("Audit failed - could not analyze any pages");
-      return;
+      return fail(EXIT_CODES.AUDIT_FAILED, `Audit failed - could not analyze ${url}`);
+    }
+    const pageFailure = primaryReport.issues.find((i) => i.code === "FETCH_ERROR" || i.code === "HTTP_ERROR_STATUS");
+    if (pageFailure) {
+      auditSpinner.fail(`Could not audit ${url}: ${pageFailure.title}`);
+    } else {
+      auditSpinner.succeed(`Audited ${successCount}/${pagesToAudit.length} pages in ${parallelTime}ms`);
     }
-    auditSpinner.succeed(`Audited ${successCount}/${pagesToAudit.length} pages in ${parallelTime}ms`);
     const mergedIssues = mergeIssues(allIssues);
+    const score = primaryReport.healthScore?.overall || 0;
     let aiAnalysis = null;
-    if (enableAI && aiKey) {
-      const aiSpinner = ora2(`Running AI analysis (${aiProvider})...`).start();
-      aiAnalysis = await runAIAnalysis(url, mergedIssues, aiProvider, aiKey);
-      if (aiAnalysis) {
-        aiSpinner.succeed("AI analysis complete");
+    let aiError;
+    if (options.ai && !pageFailure) {
+      const resolution = await resolveAIProvider({
+        aiProvider: options.aiProvider,
+        aiKey: options.aiKey,
+        aiModel: options.aiModel,
+        aiBaseUrl: options.aiBaseUrl
+      });
+      if (!resolution.ok) {
+        aiError = resolution.error;
+        console.error(chalk4.yellow(`
+\u26A0\uFE0F  ${resolution.error}`));
+        for (const hint of resolution.hints) console.error(chalk4.dim(`   ${hint}`));
       } else {
-        aiSpinner.warn("AI analysis failed or returned no results");
+        const { ai } = resolution;
+        if (ai.notice) console.error(chalk4.dim(ai.notice));
+        const aiSpinner = ora2(`Running AI analysis (${ai.label}, ${ai.model})...`).start();
+        const result = await runAIAnalysis(url, mergedIssues, ai);
+        if ("analysis" in result) {
+          aiAnalysis = result.analysis;
+          aiSpinner.succeed("AI analysis complete");
+        } else {
+          aiError = result.error;
+          aiSpinner.warn(`AI analysis failed: ${result.error}`);
+        }
       }
-    } else if (enableAI && !aiKey) {
-      console.log(chalk4.yellow("\n\u26A0\uFE0F  AI analysis requested but no API key provided"));
-      console.log(chalk4.dim("   Set OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, or GEMINI_API_KEY, or use --ai-key"));
     }
+    const gateResult = evaluateGate(mergedIssues, score, gate.failOn, gate.minScore);
+    const gated = gate.failOn !== void 0 || gate.minScore !== void 0;
+    const exitCode = pageFailure ? EXIT_CODES.AUDIT_FAILED : gateResult.passed ? EXIT_CODES.OK : EXIT_CODES.GATE_FAILED;
     const totalTime = Date.now() - startTime;
     const frameworkName = detectedFramework.framework !== "unknown" ? getFrameworkDisplayName(detectedFramework.framework) : null;
     const actualChecksRun = (primaryReport.summary?.passed || 0) + (primaryReport.summary?.errors || 0) + (primaryReport.summary?.warnings || 0) || 200;
-    if (options.output === "json") {
+    if (json) {
       let syncResult = null;
       if (loggedIn) {
         syncResult = await syncToCloud(url, primaryReport, mergedIssues, successCount, aiAnalysis, totalTime, actualChecksRun);
       }
       const jsonOutput = {
         url,
-        score: primaryReport.healthScore?.overall || 0,
+        score,
         pagesAudited: successCount,
         totalTime,
         framework: frameworkName,
         issues: mergedIssues,
         healthScores: primaryReport.healthScore,
         aiAnalysis,
+        ...aiError && { aiError },
+        ...pageFailure && { error: pageFailure.title },
+        ...gated && { gate: gateResult },
+        exitCode,
         // Include cloud sync info if synced
         ...syncResult && {
           projectId: syncResult.projectId,
@@ -1525,11 +1950,13 @@ async function audit(options) {
         }
       };
       console.log(JSON.stringify(jsonOutput, null, 2));
+      if (!gateResult.passed) {
+        for (const failure of gateResult.failures) console.error(`Gate failed: ${failure}`);
+      }
     } else {
       console.log("\n" + chalk4.bold("\u2550".repeat(60)));
       console.log(chalk4.bold.cyan(`  SEO AUDIT REPORT: ${url}`));
       console.log(chalk4.bold("\u2550".repeat(60)));
-      const score = primaryReport.healthScore?.overall || 0;
       const scoreColor = score >= 80 ? chalk4.green : score >= 60 ? chalk4.yellow : chalk4.red;
       console.log(`
   ${chalk4.bold("Score:")} ${scoreColor.bold(score + "/100")}`);
@@ -1556,9 +1983,9 @@ async function audit(options) {
         console.log(`    Local SEO:     ${bar(hs.localSeo || 0)} ${hs.localSeo || 0}%`);
         console.log(`    AI Readiness:  ${bar(hs.aiReadiness || 0)} ${hs.aiReadiness || 0}%`);
       }
-      const errors = mergedIssues.filter((i) => i.severity === "error");
+      const errors = mergedIssues.filter((i) => i.severity === "error" || i.severity === "critical");
       const warnings = mergedIssues.filter((i) => i.severity === "warning");
-      const notices = mergedIssues.filter((i) => i.severity === "notice");
+      const notices = mergedIssues.filter((i) => i.severity === "notice" || i.severity === "info");
       console.log("\n" + chalk4.bold("  Issues by Severity:"));
       console.log(`    ${chalk4.red("\u25CF")} Errors:   ${errors.length}`);
       console.log(`    ${chalk4.yellow("\u25CF")} Warnings: ${warnings.length}`);
@@ -1566,7 +1993,7 @@ async function audit(options) {
       console.log("\n" + chalk4.bold("  Top Issues:"));
       const topIssues = [...errors, ...warnings, ...notices].slice(0, 10);
       topIssues.forEach((issue, i) => {
-        const icon = issue.severity === "error" ? chalk4.red("\u2717") : issue.severity === "warning" ? chalk4.yellow("!") : chalk4.blue("i");
+        const icon = issue.severity === "error" || issue.severity === "critical" ? chalk4.red("\u2717") : issue.severity === "warning" ? chalk4.yellow("!") : chalk4.blue("i");
         console.log(`    ${i + 1}. ${icon} ${issue.title}`);
         if (issue.affectedUrls && issue.affectedUrls.length > 1) {
           console.log(chalk4.dim(`       Affects ${issue.affectedUrls.length} pages`));
@@ -1587,11 +2014,16 @@ async function audit(options) {
           });
         }
       }
+      if (gated) {
+        console.log("");
+        if (gateResult.passed) {
+          console.log(chalk4.green(`  \u2713 CI gate passed${gate.failOn ? ` (--fail-on ${gate.failOn})` : ""}${gate.minScore !== void 0 ? ` (--min-score ${gate.minScore})` : ""}`));
+        } else {
+          for (const failure of gateResult.failures) console.log(chalk4.red(`  \u2717 CI gate failed: ${failure}`));
+        }
+      }
       console.log("\n" + chalk4.bold("\u2550".repeat(60)));
-      const userInfo = getUserInfo();
-      const tier = userInfo.planName?.toLowerCase() || "free";
-      const isFreeTier = !loggedIn || tier === "free";
-      const isSoloOrBelow = isFreeTier || tier === "solo";
+      const isFreeTier = tierId === "free" || tierId === "free_anon";
       if (isFreeTier) {
         const checksRun = mergedIssues.length > 0 ? loggedIn ? 100 : 50 : 0;
         showUpsell("checks_limit", {
@@ -1617,13 +2049,46 @@ async function audit(options) {
       } else {
         showUpsell("free_audit_complete");
       }
+      if (pageFailure) {
+        console.error(chalk4.red(`
+\u274C ${pageFailure.title}: ${pageFailure.description}
+`));
+      }
     }
+    return exitCode;
   } catch (error) {
-    console.log(`
-\u274C Audit failed: ${error instanceof Error ? error.message : "Unknown error"}
-`);
+    return fail(EXIT_CODES.AUDIT_FAILED, `Audit failed: ${error instanceof Error ? error.message : "Unknown error"}`);
   }
 }
+var AUDIT_HELP_TEXT = `
+Exit codes:
+  0  audit completed; no --fail-on / --min-score gate tripped
+  1  a --fail-on or --min-score gate tripped
+  2  bad invocation (missing/invalid --url, invalid flag value)
+  3  no real audit: site unreachable, the URL answered 4xx/5xx, no page
+     could be analyzed, or an internal error
+
+CI gating (both opt-in; without them any completed audit exits 0):
+  --fail-on error     fail on any error
+  --fail-on warning   fail on any warning or error
+  --fail-on notice    fail on any issue at all
+  --min-score 80      fail if the overall score is below 80
+
+AI analysis (--ai) runs on your own provider. Hosted: ${Object.entries(AI_PROVIDERS).filter(([, p]) => !p.local).map(([id]) => id).join(", ")}.
+  Picked automatically from the first key found in:
+    ${AI_ENV_KEYS.join(", ")}
+  (OpenRouter first). No key at all? A running local Ollama is used.
+  Local: --ai-provider ollama | lmstudio | llamacpp | vllm (no key needed;
+  the loaded model is used unless you pass --ai-model), or any
+  OpenAI-compatible server: --ai-base-url http://host:port/v1 --ai-model <name>
+
+Examples:
+  rankcli audit --url https://example.com
+  rankcli audit --url https://example.com --fail-on error --min-score 80
+  rankcli audit --url https://example.com -o json > report.json
+  rankcli audit --url https://example.com --ai --ai-provider deepseek
+  rankcli audit --url https://example.com --ai --ai-provider ollama --ai-model qwen3:8b
+`;
 
 // src/commands/apply.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
@@ -1905,6 +2370,29 @@ ${index + 1}. ${icon} ${fix2.issue.message}`);
   }
 }
 async function fix(options) {
+  const result = await runFix(options);
+  if (options.output === "json" && !result.json) {
+    result.json = JSON.stringify({
+      url: result.url ?? options.url ?? null,
+      success: result.success,
+      ...result.error && { error: result.error },
+      dryRun: !!result.dryRun,
+      fixes: (result.fixes || []).map((f) => ({
+        code: f.issue.code,
+        message: f.issue.message,
+        file: f.file,
+        applied: !!f.applied,
+        skipped: f.skipped,
+        skipReason: f.skipReason
+      })),
+      appliedCount: result.appliedCount ?? 0,
+      skippedCount: result.skippedCount ?? 0,
+      ...result.durationMs !== void 0 && { durationMs: result.durationMs }
+    }, null, 2);
+  }
+  return result;
+}
+async function runFix(options) {
   const startTime = Date.now();
   const cwd = options.cwd || process.cwd();
   const url = options.url;
@@ -1929,8 +2417,9 @@ async function fix(options) {
     return { success: false, error };
   }
   const loggedIn = isLoggedIn();
+  if (loggedIn) await ensureApiKeyPlan();
   const userInfo = getUserInfo();
-  const tier = userInfo.planName?.toLowerCase() || "free";
+  const tier = tierFromPlanId(userInfo.planId) ?? tierFromPlanId(userInfo.planName) ?? "free";
   const hasAutoFix = loggedIn && hasFeature(tier, "auto_fix");
   if (!options.dryRun && !hasAutoFix) {
     if (options.output !== "json") {
@@ -3419,17 +3908,21 @@ async function testWebhook(channel, webhookUrl) {
 }
 
 // src/version.ts
-var VERSION = "0.0.29";
+var VERSION = "0.0.30";
 
 // src/index.ts
 var program = new Command();
 program.name("rankcli").description("RankCLI - Ship code, get ranked. SEO meets CI/CD.").version(VERSION);
-program.command("login").description("Log in to your RankCLI account (opens your browser by default)").option("-e, --email <email>", "Log in with email/password instead of the browser").option("--no-browser", "Skip the browser and log in with email/password interactively").option("-t, --token <apiKey>", "API key for non-interactive authentication").action(login);
+program.command("login").description("Log in to your RankCLI account (opens your browser by default)").option("-e, --email <email>", "Log in with email/password instead of the browser").option("--no-browser", "Skip the browser and log in with email/password interactively").option("-t, --token <apiKey>", "API key for non-interactive authentication (validates it and resolves your plan)").action(async (options) => {
+  process.exitCode = await login(options);
+});
 program.command("logout").description("Log out of your RankCLI account").action(logout);
 program.command("whoami").description("Show current logged in user").action(whoami);
 program.command("init").description("Set up RankCLI in your project (detects framework, git/GitHub, AI keys)").option("-y, --yes", "Skip prompts and use defaults").action(init);
 program.command("analyze").description("AI analyzes your codebase for SEO opportunities").option("-v, --verbose", "Show detailed output").action(analyze);
-program.command("audit").description("Run a comprehensive SEO audit (200+ checks, Ahrefs-level)").option("-u, --url <url>", "URL to audit").option("-o, --output <format>", "Output format (json, console)", "console").option("--check-links", "Check for broken internal/external links (slower)").option("--max-pages <n>", "Max pages to crawl (default: 5)").option("--ai", "Enable AI analysis").option("--ai-provider <provider>", "AI provider: openai, anthropic, openrouter, groq, or gemini (auto-detected from env if omitted)").option("--ai-key <key>", "API key (or set OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, or GEMINI_API_KEY)").action(audit);
+program.command("audit").description("Run a comprehensive SEO audit (200+ checks, Ahrefs-level)").option("-u, --url <url>", "URL to audit").option("-o, --output <format>", "Output format (json, console)", "console").option("--check-links", "Check for broken internal/external links (slower)").option("--max-pages <n>", "Max pages to crawl (default: 5)").option("--fail-on <level>", "CI gate: exit 1 if any issue is at or above this severity (error, warning, notice)").option("--min-score <n>", "CI gate: exit 1 if the overall score is below n (0-100)").option("--ai", "Enable AI analysis (your own key, or a local model)").option("--ai-provider <provider>", "AI provider (auto-detected if omitted): openrouter, openai, anthropic, groq, gemini, deepseek, mistral, cerebras, together, fireworks, ollama, lmstudio, llamacpp, vllm, custom").option("--ai-key <key>", "AI provider API key (or set the provider's env var, e.g. OPENROUTER_API_KEY)").option("--ai-model <model>", "Model id (defaults to a cheap model per provider, or the local server's loaded model)").option("--ai-base-url <url>", "OpenAI-compatible base URL, e.g. http://localhost:8080/v1 (implies --ai-provider custom)").addHelpText("after", AUDIT_HELP_TEXT).action(async (options) => {
+  process.exitCode = await audit(options);
+});
 program.command("apply").description("Analyze a live URL and apply SEO fixes to your codebase").option("-u, --url <url>", "URL to analyze").option("--auto", "Auto-apply fixes without confirmation").option("--dry-run", "Preview changes without applying").action(apply);
 program.command("fix").description("Agentic SEO fixer - detect, fix, commit, and push").option("-u, --url <url>", "URL to analyze").option("--auto", "Auto-apply fixes without confirmation").option("--commit", "Commit changes with conventional commit message").option("--push", "Push changes after committing (requires --commit)").option("--dry-run", "Preview changes without applying").option("--only <codes>", "Fix only specific issue codes (comma-separated)", (val) => val.split(",")).option("-o, --output <format>", "Output format (text, json)", "text").action(async (options) => {
   const result = await fix({
@@ -3510,7 +4003,10 @@ program.command("report").description("Generate SEO performance report").option(
 program.command("watch").description("Continuous monitoring mode").action(() => {
   console.log("Watch mode coming soon...");
 });
-program.command("setup").description("Set up SEO tracking (GA4, Search Console, GitHub Actions)").option("--ga4 <id>", "Google Analytics 4 Measurement ID (G-XXXXXXXXXX)").option("--gsc <code>", "Google Search Console verification code").option("--github-action", "Set up automated GitHub Action").option("--schedule <freq>", "GitHub Action schedule (daily, weekly, monthly)", "weekly").option("--all", "Interactive setup wizard").action(setup);
+program.command("setup").description("Set up SEO tracking (GA4, Search Console, GitHub Actions)").option("--ga4 <id>", "Google Analytics 4 Measurement ID (G-XXXXXXXXXX)").option("--gsc <code>", "Google Search Console verification code").option("--github-action", "Set up automated GitHub Action").option("--schedule <freq>", "GitHub Action schedule (daily, weekly, monthly)", "weekly").option("--all", "Interactive setup wizard").option("--url <url>", "Site URL the GitHub Action audits").option("--sync", "GitHub Action: sync audits to your dashboard and enable auto-fix PRs (needs a RANKCLI_API_KEY secret)").action(setup);
 program.command("gsc-setup").description("Show Google Search Console API setup instructions").action(showGSCInstructions);
 program.command("alerts").description("Configure Slack/Discord notifications for SEO events").option("-c, --channel <channel>", "Alert channel (slack, discord)").option("-w, --webhook <url>", "Webhook URL").option("--test", "Test the webhook").option("--list", "List current alert configurations").option("--remove <id>", "Remove an alert configuration").action(alerts);
-program.parse();
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});