@inferall/cli 0.2.0 → 0.2.1

package/bin/inferall.js

@@ -23,15 +23,222 @@ import {
   existsSync,
   readdirSync,
   statSync,
+  realpathSync,
+  accessSync,
+  constants as fsConstants,
 } from "node:fs";
-import { join, relative, extname } from "node:path";
+import { join, relative, extname, basename, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
 
 const API_BASE = env.INFERALL_API_BASE || "https://api.inferall.ai/v1";
 // The Anthropic SDK appends /v1/messages itself, so its baseURL is the host root.
 const ANTHROPIC_BASE = API_BASE.replace(/\/v1$/, "");
 const KEYS_URL = "https://inferall.ai/keys";
 const BILLING_URL = "https://inferall.ai/billing?src=cli_init";
-const FREE_MODEL = "meta/llama-3.1-8b-instruct";
+
+/**
+ * Did we fail to REACH the gateway, as opposed to reaching it and disliking the
+ * answer? 2026-07-27 tick 832.
+ *
+ * With the gateway unreachable, `doctor` printed
+ *
+ *     ✗ key rejected by gateway (network error). Check https://inferall.ai/keys
+ *
+ * The key was never checked. That sentence names a cause that did not happen
+ * and sends the user to mint a replacement key, which cannot fix an unreachable
+ * host. `models` was worse: the throw reached the top-level handler and printed
+ * a bare `✗ fetch failed`, which is Node's words, not ours.
+ *
+ * One predicate so every caller classifies it the same way. Node/undici phrases
+ * the same condition several ways depending on how it fails, so match on all of
+ * them rather than the one seen first.
+ */
+/**
+ * Every request this CLI makes is bounded.
+ *
+ * WHY THIS EXISTS (2026-07-31, tick 883)
+ * -------------------------------------
+ * Node's fetch applies no request timeout, and none of the call sites set one.
+ * Measured against a stub that accepts the connection and never replies:
+ *
+ *     inferall status  ->  45s+, ZERO bytes of output, no exit
+ *
+ * Not a hang forever (undici gives up on headers around 300s) but five minutes
+ * of a completely blank terminal, with nothing printed to say a request is even
+ * in flight. That is the worst shape a failure can take: there is nothing to
+ * read, nothing to act on, and no error to search for. A blackholing firewall
+ * or a proxy that swallows outbound traffic produces exactly this.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+const timeoutSignal = () => AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+
+function isNetworkError(err) {
+  // A timeout arrives as a DOMException named TimeoutError carrying no code,
+  // so matching on codes alone would drop it into the generic catch and print
+  // Node's words instead of ours.
+  if (err?.name === "TimeoutError" || err?.cause?.name === "TimeoutError") return true;
+  const m = `${err?.cause?.code || ""} ${err?.code || ""} ${err?.message || err || ""}`;
+  return /fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|socket hang up|UND_ERR|network/i.test(m);
+}
+
+/** What to say when we could not reach the gateway. Never blames the key. */
+/**
+ * Name WHY the gateway could not be reached, from the cause the error already
+ * carries.
+ *
+ * 2026-07-29 tick 852. `err.message` is always the string "fetch failed",
+ * whatever went wrong, so the old single remedy ("check your connection") was
+ * printed for every cause. MEASURED against real failures:
+ *
+ *   self-signed TLS   cause.code = DEPTH_ZERO_SELF_SIGNED_CERT
+ *   DNS failure       cause.code = ENOTFOUND
+ *   nothing listening cause.code = ECONNREFUSED
+ *
+ * These need completely different fixes, and the one that matters most is the
+ * TLS case: behind a corporate proxy that re-signs traffic, the user's
+ * connection is fine and "check your connection" sends them looking in the
+ * wrong place entirely. The remedy is a trust store, which they will not guess.
+ *
+ * Returns null for a cause we cannot name, and the caller then prints the raw
+ * code. Inventing a confident explanation for an unrecognised failure is how a
+ * diagnostic starts lying, and this file has paid for that twice already.
+ */
+export function describeNetworkCause(err) {
+  const code = err?.cause?.code || err?.code || "";
+  if (err?.name === "TimeoutError" || err?.cause?.name === "TimeoutError") {
+    return {
+      code: "TIMEOUT",
+      why: `the gateway accepted the connection but sent nothing back within ${REQUEST_TIMEOUT_MS / 1000}s`,
+      fix: "Often a firewall or proxy that swallows outbound traffic. Retry, or check INFERALL_API_BASE.",
+    };
+  }
+  if (!code) return null;
+  if (/SELF_SIGNED|UNABLE_TO_VERIFY|CERT_|_CERT$|ERR_TLS/i.test(code)) {
+    return {
+      code,
+      why: "the TLS certificate could not be verified, which usually means a proxy is re-signing traffic",
+      fix: `Point Node at your organisation's CA: ${c.cyan("export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem")}`,
+    };
+  }
+  if (/ENOTFOUND|EAI_AGAIN/i.test(code)) {
+    return { code, why: "the hostname did not resolve", fix: "Check DNS, a VPN, or a typo in the host name." };
+  }
+  if (/ECONNREFUSED/i.test(code)) {
+    return {
+      code,
+      why: "nothing is listening there",
+      fix: `Usually a stale ${c.cyan("INFERALL_API_BASE")} pointing at a local port that is not running.`,
+    };
+  }
+  if (/ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT|ECONNRESET|EPIPE/i.test(code)) {
+    return { code, why: "the connection timed out or was dropped", fix: "Often a firewall or a proxy that blocks outbound HTTPS." };
+  }
+  return { code, why: null, fix: null };
+}
+
+/**
+ * Explain a NON-OK HTTP response without guessing at the cause.
+ *
+ * WHY THIS EXISTS (2026-07-31, tick 882)
+ * -------------------------------------
+ * Tick 832 established that an unreachable gateway must not be reported as a
+ * rejected key, "so users went and regenerated a key that was fine". That fix
+ * covered NETWORK errors, which arrive as a thrown exception. A 500 is not a
+ * network error: it is a completed HTTP exchange with a failure status, so it
+ * never entered that path and the old wording survived there untouched.
+ *
+ * Measured this tick against a stub forced to 500:
+ *
+ *   status  ->  "status check failed (HTTP 500). Check the key at <keys page>"
+ *   doctor  ->  "key rejected by gateway (HTTP 500)"
+ *
+ * Both blame the key for a server fault. During a real gateway incident every
+ * user would be told their key was rejected, and the remedy on offer, minting a
+ * new key, cannot fix a 500. doctor carries a comment two lines above saying a
+ * confident wrong cause is the failure that costs the most there.
+ *
+ * Only 401/403 are actually a verdict on the key.
+ */
+export function httpFailureLines(status) {
+  if (status === 401 || status === 403) {
+    return [
+      `${c.red("✗")} key rejected by gateway (HTTP ${status})`,
+      `  The gateway does not recognise this key. Mint one at ${KEYS_URL}`,
+    ];
+  }
+  if (status === 429) {
+    return [
+      `${c.red("✗")} rate limited by the gateway (HTTP 429)`,
+      `  Your key is fine. Wait a moment and retry.`,
+    ];
+  }
+  if (status >= 500) {
+    return [
+      `${c.red("✗")} the gateway is failing (HTTP ${status})`,
+      `  This is NOT your key and there is nothing to fix on your side.`,
+      `  Retry shortly. A new key will not help.`,
+    ];
+  }
+  return [
+    `${c.red("✗")} unexpected response from the gateway (HTTP ${status})`,
+    `  This is not a verdict on your key. Retry, and report it if it persists.`,
+  ];
+}
+
+function unreachableLines(err) {
+  const cause = describeNetworkCause(err);
+  return [
+    `${c.red("✗")} cannot reach the InferAll gateway at ${c.bold(API_BASE)}`,
+    // The cause is printed even when unrecognised: a bare code is still a
+    // search term, and hiding it leaves the user with nothing.
+    ...(cause
+      ? [`  cause: ${c.bold(cause.code)}${cause.why ? `, ${cause.why}` : ""}`, ...(cause.fix ? [`  ${cause.fix}`] : [])]
+      : []),
+    // Phrased to be exactly true from every caller: `models` never sends a key
+    // at all, so "your key was not checked" would be true but beside the point
+    // there. What every caller needs is the same: do not read this as a verdict
+    // on your setup.
+    `  ${c.bold("Nothing")} was verified, so this says nothing about your key or your setup.`,
+    `  Check your connection, or whether ${c.cyan("INFERALL_API_BASE")} points somewhere unexpected.`,
+  ];
+}
+// 2026-10-03: the previous default was end-of-lifed by NVIDIA; ultra is the default free model.
+const FREE_MODEL = "nvidia/nemotron-3-ultra-550b-a55b";
+const CLI_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// Written by scripts/publish-gate.sh at publish time, and never committed.
+// npm publishes the working tree rather than a commit, so without this the
+// version string is the only identity the artifact has - and one version string
+// has covered 34 different trees so far.
+//
+// ABSENT MEANS "unstamped", NOT "broken". A dev checkout and an `npm link` are
+// legitimate states; neither should be reported as a fault. Only a stamp that
+// is present AND carries a sha counts.
+const BUILD_INFO = (() => {
+  try {
+    const j = JSON.parse(readFileSync(new URL("./build-info.json", import.meta.url), "utf8"));
+    return j && typeof j.sha === "string" && j.sha ? j : null;
+  } catch {
+    return null;
+  }
+})();
+
+// An off-main publish is surfaced to the user rather than buried in a CI log,
+// because the CI log is exactly what nobody reads on a green run.
+export function versionLine(version, build) {
+  if (!build || typeof build.sha !== "string" || !build.sha) return version;
+  const offMain = typeof build.offMain === "string" && build.offMain.trim() ? build.offMain.trim() : null;
+  return offMain
+    ? `${version} (${build.sha}, published off-main: ${offMain})`
+    : `${version} (${build.sha})`;
+}
 
 const c = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
@@ -43,8 +250,37 @@ const c = {
 };
 
 const args = argv.slice(2);
-const cmd = args.find((a) => !a.startsWith("-")) || "init";
-const flag = (name) => args.includes(`--${name}`);
+// 2026-07-31 tick 876. `|| "init"` swallowed every flag-only invocation.
+// `inferall --help` has no non-flag argument, so cmd fell through to init and
+// the user got an interactive setup wizard prompting "Paste your InferAll API
+// key" instead of help. Measured on the packed artifact: --help, -h and -v all
+// ran the wizard; only the bare word `help` and the long `--version` worked.
+//
+// --help is the first thing anyone types on an unfamiliar CLI, so the default
+// has to run AFTER the help and version flags are considered, not before.
+const HELP_FLAGS = new Set(["--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v", "-V"]);
+const cmd =
+  args.find((a) => !a.startsWith("-")) ||
+  (args.some((a) => HELP_FLAGS.has(a))
+    ? "help"
+    : args.some((a) => VERSION_FLAGS.has(a))
+      ? "version"
+      : "init");
+// Single-character names also accept the conventional single-dash form.
+//
+// 2026-08-01 tick 899. `const YES = flag("yes") || flag("y")` on the line below
+// reads as a `-y` alias and was clearly written to be one, but flag() only ever
+// built `--${name}`, so it enabled `--y` (which nobody types and no doc
+// mentions) and NOT `-y`. Meanwhile README.md documents `--yes` / `-y` in its
+// flag table. MEASURED end to end against a stub: `init --key ... --yes` exits
+// 0 and wires the project; the identical run with `-y` exits 1 and prints the
+// non-interactive help. So the landing page documented a flag that failed, and
+// a user copying it into CI got a broken step.
+//
+// Restricted to length 1 so this cannot start accepting `-yes` or `-no-ai`,
+// which are not real forms and would be a new way to be wrong.
+const flag = (name) => args.includes(`--${name}`) || (name.length === 1 && args.includes(`-${name}`));
 const flagValue = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 && args[i + 1] && !args[i + 1].startsWith("-") ? args[i + 1] : undefined;
@@ -52,12 +288,114 @@ const flagValue = (name) => {
 const YES = flag("yes") || flag("y");
 const NO_AI = flag("no-ai");
 
-const rl = createInterface({ input: stdin, output: stdout });
+// Lazily created. At module scope this held stdin open, so merely IMPORTING
+// this file kept a Node process alive forever — which is why `node --test`
+// hung the first time the codemod was given tests. Interactive state must not
+// be a side effect of loading the module.
+let _rl = null;
+const rlHandle = () => (_rl ??= createInterface({ input: stdin, output: stdout }));
+const rl = {
+  question: (q) => rlHandle().question(q),
+  close: () => { _rl?.close(); _rl = null; },
+};
+/**
+ * Raised when a prompt is reached but there is no more input to answer it.
+ *
+ * 2026-07-31 tick 879: piping answers into `init` crashed with a bare
+ * `✗ readline was closed`, and Ctrl+D produced `✗ Aborted with Ctrl+D`.
+ * Neither string is ours; both are Node internals reaching the user through
+ * the generic catch. The crash landed AFTER the key was written and after we
+ * had printed that it was saved, so the last thing a user saw was an internal
+ * error with no way to tell whether setup had finished.
+ */
+class InputEndedError extends Error {
+  constructor(cause) {
+    super("input ended before setup finished");
+    this.name = "InputEndedError";
+    this.cause = cause;
+  }
+}
+
 async function ask(q, fallback) {
   if (YES) return fallback ?? "y";
-  const a = (await rl.question(q)).trim();
+  // Ending stdin fails in TWO different ways and both had to be caught.
+  //
+  //   1. At a LATER prompt, after a close/reopen, question() REJECTS with
+  //      "readline was closed". Closing a readline over a pipe ends stdin for
+  //      good, so queued answers are discarded; feeding eight answers failed
+  //      exactly like feeding one.
+  //   2. At the FIRST prompt, when stdin is already ended, question() simply
+  //      NEVER SETTLES. The event loop empties and the process exits with no
+  //      message at all, which is worse than a bad message.
+  //
+  // Racing the readline's own close event covers both, so this cannot depend
+  // on which prompt happened to be reached first.
+  const handle = rlHandle();
+  let a = await new Promise((resolve, reject) => {
+    const onClose = () => reject(new InputEndedError());
+    handle.once("close", onClose);
+    handle.question(q).then(
+      (v) => { handle.off("close", onClose); resolve(v); },
+      (err) => { handle.off("close", onClose); reject(new InputEndedError(err)); },
+    );
+  });
+  a = a.trim();
   return a === "" ? (fallback ?? "") : a;
 }
+/**
+ * Open a URL in the user's default browser. Returns true if the command was
+ * dispatched, false if we could not.
+ *
+ * Deliberately fire-and-forget and never throws: this is a convenience on the
+ * signup path, and a headless box, a locked-down container, or a missing
+ * xdg-open must degrade to "here is the URL" rather than taking down a wizard
+ * that was about to work fine.
+ *
+ * The URL is a module constant, never user input, so there is no injection
+ * surface here — but it is passed as an argv element rather than interpolated
+ * into a shell string, so that stays true if someone later makes it dynamic.
+ */
+function openBrowser(url) {
+  try {
+    const cmd =
+      process.platform === "darwin" ? "open" :
+      process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});   // ENOENT on a box with no opener — already handled by the return
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Keep the patched file's trailing-newline state identical to the original.
+ *
+ * 2026-07-26 tick 801: the wizard was STRIPPING the final newline from every
+ * source file it rewrote. Found by running `init` on a Python project and
+ * noticing the next shell prompt ran onto the last line of the patched file.
+ *
+ * Small, but this is someone else's repository. A missing final newline is
+ * `W292` to flake8, `eol-last` to eslint, and renders as
+ * "" in the first git diff a user sees after
+ * running our installer. Introducing lint errors into a project we were
+ * invited to configure is exactly the kind of thing that makes a tool feel
+ * unsafe to run twice.
+ *
+ * Symmetric on purpose: a file that never ended with a newline does not get
+ * one added. The rule is "leave it as you found it", not "normalise it" — this
+ * tool has no business having an opinion about a convention it did not set.
+ */
+export function preserveTrailingNewline(original, patched) {
+  const had = original.endsWith("\n");
+  const has = patched.endsWith("\n");
+  if (had && !has) return patched + "\n";
+  if (!had && has) return patched.replace(/\n+$/, "");
+  return patched;
+}
+
 async function confirm(q, defaultYes = true) {
   const hint = defaultYes ? "Y/n" : "y/N";
   const a = (await ask(`${q} ${c.dim(`[${hint}]`)} `, defaultYes ? "y" : "n")).toLowerCase();
@@ -66,89 +404,739 @@ async function confirm(q, defaultYes = true) {
 
 // ---------- project detection ----------
 
-function detectProject(root) {
-  const p = { root, kind: null, sdks: [], pkg: null };
+const NODE_SDKS = ["openai", "@anthropic-ai/sdk", "@google/generative-ai", "@google/genai", "ai", "@inferall/sdk"];
+
+/**
+ * Every package.json at or below `root`, skipping node_modules.
+ *
+ * 2026-07-26 tick 803: detection used to read ONLY the root package.json. In a
+ * workspace monorepo the root declares `workspaces` and no dependencies, so
+ * `sdks` came back empty, the wizard took its greenfield branch, wrote a
+ * hello-world example, and printed "Done. Your project is wired to InferAll"
+ * while packages/api/src/service.ts still pointed at OpenAI with
+ * OPENAI_API_KEY. Reported success, migrated nothing. Same failure family as
+ * the tick-800 codemod bug, and monorepos are not an edge case in this
+ * ecosystem.
+ *
+ * Deliberately a filesystem walk rather than parsing the `workspaces` globs:
+ * it also catches pnpm/nx/turbo layouts and plain nested packages that never
+ * declare workspaces at the root. The call-site scanner already walks to depth
+ * 6, so detection was the only thing looking in one place.
+ *
+ * Depth 3 covers packages/<name>/package.json and apps/<name>/package.json,
+ * which is where these live in practice.
+ */
+function findPackageJsons(root, depth = 0, acc = []) {
+  if (depth > 3) return acc;
+  const here = join(root, "package.json");
+  if (existsSync(here)) acc.push(here);
+  let entries = [];
+  try { entries = readdirSync(root); } catch { return acc; }
+  for (const name of entries) {
+    if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
+    const full = join(root, name);
+    try { if (!statSync(full).isDirectory()) continue; } catch { continue; }
+    findPackageJsons(full, depth + 1, acc);
+  }
+  return acc;
+}
+
+/**
+ * Does .gitignore list .env?
+ *
+ * TRI-STATE ON PURPOSE, and `covers: null` is the whole reason this exists.
+ *
+ * 2026-07-28 tick 844: `doctor` did `existsSync(giPath) && readFileSync(giPath)`
+ * with nothing around it. existsSync answers TRUE for a directory, so a
+ * .gitignore that was a directory threw EISDIR and an unreadable one threw
+ * EACCES -- from step 2 of five, which meant the hygiene verdict AND the key
+ * check never ran at all. MEASURED, both spellings:
+ *
+ *     ✗ EISDIR: illegal operation on a directory, read
+ *     ✗ EACCES: permission denied, open '/private/tmp/.../giperm/.gitignore'
+ *
+ * People run `doctor` precisely because something is already wrong, so handing
+ * them a bare errno, the absolute path of their own machine, and no diagnosis
+ * is the worst moment to fail. This is the tick 835 unreadable-.env bug in the
+ * one reader I never enumerated: 835 fixed the .env READ, 836 fixed the WRITES
+ * including .gitignore, and this READ sat between them untouched.
+ *
+ * Returning `false` on failure would have been the smaller change and the wrong
+ * one. false means "not ignored" and would print a confident warning about a
+ * file we could not open; the tick-839 lesson is that a boolean meaning both
+ * "no" and "could not tell" is two facts wearing one type.
+ */
+export function gitignoreCoversEnv(root) {
+  const giPath = join(root, ".gitignore");
+  if (!existsSync(giPath)) return { covers: false, problem: null };
+  try {
+    const gi = readFileSync(giPath, "utf8");
+    return {
+      covers: gi.split("\n").some((l) => [".env", ".env*", "*.env"].includes(l.trim())),
+      problem: null,
+    };
+  } catch (err) {
+    // describeFsError basenames the path, so this stops leaking the absolute
+    // path of the user's machine along with the errno.
+    return { covers: null, problem: describeFsError(err, giPath, "read") };
+  }
+}
+
+export function detectProject(root) {
+  const p = { root, kind: null, sdks: [], pkg: null, readProblems: [] };
   const pkgPath = join(root, "package.json");
   if (existsSync(pkgPath)) {
     p.kind = "node";
     try {
       p.pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-      const deps = { ...p.pkg.dependencies, ...p.pkg.devDependencies };
-      for (const name of ["openai", "@anthropic-ai/sdk", "@google/generative-ai", "@google/genai", "ai", "@inferall/sdk"]) {
-        if (deps?.[name]) p.sdks.push(name);
-      }
     } catch {
       /* unparseable package.json — treat as bare node */
     }
+    const found = new Set();
+    for (const f of findPackageJsons(root)) {
+      try {
+        const pkg = JSON.parse(readFileSync(f, "utf8"));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const name of NODE_SDKS) if (deps?.[name]) found.add(name);
+      } catch { /* skip unparseable */ }
+    }
+    p.sdks = [...found];
   } else if (existsSync(join(root, "pyproject.toml")) || existsSync(join(root, "requirements.txt"))) {
     p.kind = "python";
+    // 2026-07-28 tick 844: same unguarded existsSync-then-readFileSync as the
+    // .gitignore reader in `doctor`. MEASURED: a pyproject.toml that is a
+    // DIRECTORY killed `init` with "EISDIR: illegal operation on a directory,
+    // read", and an unreadable requirements.txt with EACCES plus the absolute
+    // path. Found by enumerating every read in this file rather than by fixing
+    // only the one that was reported, which is how the first copy survived.
+    //
+    // Swallowing the error to "" would be the tempting one-liner and it
+    // recreates the tick 805 bug documented immediately below: with no manifest
+    // text, detection finds no SDK, the wizard takes its greenfield branch and
+    // announces "Done. Your project is wired to InferAll" over a project that
+    // still calls OpenAI directly. So the failure is recorded and surfaced.
     const reqs = ["pyproject.toml", "requirements.txt"]
       .filter((f) => existsSync(join(root, f)))
-      .map((f) => readFileSync(join(root, f), "utf8"))
+      .map((f) => {
+        try {
+          return readFileSync(join(root, f), "utf8");
+        } catch (err) {
+          p.readProblems.push(describeFsError(err, join(root, f), "read"));
+          return "";
+        }
+      })
       .join("\n");
-    for (const name of ["openai", "anthropic", "google-generativeai", "google-genai", "inferall-ai"]) {
+    // 2026-07-26 tick 805: langchain-openai added. A LangChain project declares
+    // `langchain-openai`, never `openai`, so detection found nothing, the wizard
+    // took its greenfield branch and printed "Done. Your project is wired to
+    // InferAll" while app/chain.py still called OpenAI directly. Third variant
+    // of the detected-reported-success-migrated-nothing family (t803 monorepo,
+    // t804 Vercel AI). LangChain is one of the most common Python AI stacks.
+    for (const name of ["openai", "anthropic", "google-generativeai", "google-genai", "inferall-ai",
+                        "langchain-openai", "langchain_openai",
+                        "langchain-anthropic", "langchain_anthropic"]) {
       if (new RegExp(`^\\s*"?${name}`, "m").test(reqs)) p.sdks.push(name);
     }
   }
+
+  // 2026-07-27 tick 828: a Python project with NO manifest.
+  //
+  // pip install without a committed requirements.txt is ordinary — scripts,
+  // notebooks-turned-scripts, anything using a venv or conda or uv where the
+  // lockfile is not in the repo. Neither branch above matched, so kind stayed
+  // null and the wizard said:
+  //
+  //     No package.json / pyproject.toml / requirements.txt found here.
+  //     Run this from your project root, or continue for a bare .env setup.
+  //
+  // while standing IN the project root, with .py files calling the exact SDKs
+  // it migrates. The advice was not merely unhelpful, it was impossible to
+  // follow: there is no other directory to run it from. Then it labelled the
+  // project "node" and offered a bare .env, so the Python code was never
+  // migrated and the user was told to go somewhere that does not exist.
+  //
+  // The manifest is evidence, not the definition. Imports are the better
+  // evidence, and the codemod handles these files perfectly once detection
+  // stops filtering them out (verified: both an OpenAI and an Anthropic site
+  // patch with the correct per-SDK base). So when no manifest is found, look
+  // for actual SDK imports in the source.
+  if (!p.kind) {
+    const imported = findPythonSdkImports(root);
+    if (imported.length) {
+      p.kind = "python";
+      p.sdks = imported;
+      p.inferredFrom = "imports";
+    } else {
+      // 2026-07-27 tick 829: the same hole, one surface over.
+      //
+      // A notebook-only project (the ordinary data-science shape: one .ipynb,
+      // pip install, nothing committed) still had no manifest and no .py, so
+      // the tick-828 fallback missed it and we printed
+      //
+      //     No project detected here: ... and no Python file importing an AI SDK.
+      //     If your code lives elsewhere, cd there and re-run.
+      //
+      // while findNotebookSites finds that exact notebook in under a
+      // millisecond. The assertion was false and the advice was again
+      // impossible to follow.
+      //
+      // Notebooks are deliberately NOT patched -- handing JSON to the text
+      // codemod corrupts the file (t816) -- but they ARE reported, and being
+      // reported requires getting past detection first. Detecting them sets up
+      // the honest path: .env written, notebook guidance printed, and the
+      // "still need the one-line change" count includes them.
+      //
+      // Reuses findNotebookSites and CLIENT_CLASSES rather than parsing cells
+      // again here. A parallel copy is how these two would drift apart.
+      const nbSites = findNotebookSites(root);
+      if (nbSites.length) {
+        p.kind = "python";
+        p.sdks = [...new Set(nbSites.flatMap((s) => s.hits.map((h) => CLIENT_CLASSES[h.sdk])))];
+        p.inferredFrom = "notebooks";
+      }
+    }
+  }
   return p;
 }
 
+/**
+ * Which Python SDKs does this tree actually import? Used only when there is no
+ * manifest to read. Reuses the same walker as the codemod so the two can never
+ * disagree about which files count -- a mismatch there would recreate the
+ * detected-but-not-migrated family of bugs (t803/t804/t805) from the other end.
+ */
+const PY_IMPORT_SDKS = [
+  ["openai", /^\s*(?:from\s+openai\b|import\s+openai\b)/m],
+  ["anthropic", /^\s*(?:from\s+anthropic\b|import\s+anthropic\b)/m],
+  ["langchain-openai", /^\s*(?:from\s+langchain_openai\b|import\s+langchain_openai\b)/m],
+  ["langchain-anthropic", /^\s*(?:from\s+langchain_anthropic\b|import\s+langchain_anthropic\b)/m],
+  ["google-generativeai", /^\s*(?:from\s+google\.generativeai\b|import\s+google\.generativeai\b)/m],
+  ["google-genai", /^\s*(?:from\s+google\s+import\s+genai\b|from\s+google\.genai\b)/m],
+];
+
+export function findPythonSdkImports(root) {
+  const found = new Set();
+  for (const file of walk(root)) {
+    if (extname(file) !== ".py") continue;
+    let body;
+    try {
+      body = readFileSync(file, "utf8");
+    } catch {
+      continue; // unreadable file is not a detection failure (t824)
+    }
+    for (const [name, re] of PY_IMPORT_SDKS) if (re.test(body)) found.add(name);
+  }
+  return [...found];
+}
+
 // ---------- env / key setup ----------
 
-function upsertEnvFile(root, key) {
+/**
+ * The INFERALL_API_KEY currently in .env, or null.
+ *
+ * 2026-07-27 tick 820: added because upsertEnvFile replaced any existing key
+ * line unconditionally and the caller announced it as "+ written". A user with
+ * a working key in .env who re-ran init had it silently swapped for whatever
+ * the wizard resolved, and the only report was a plus sign. Measured:
+ *
+ *   before  INFERALL_API_KEY=ifu_MY_EXISTING_WORKING_KEY
+ *   after   INFERALL_API_KEY=ifu_NEW_DIFFERENT_KEY
+ *   printed + INFERALL_API_KEY written to .env
+ *
+ * Destroying somebody's credential is bad; describing it as an addition is
+ * what makes it undiscoverable.
+ */
+/**
+ * Pull INFERALL_API_KEY out of .env text, the way dotenv would.
+ *
+ * 2026-07-27 tick 834. Three copies of `/^INFERALL_API_KEY=(.+)$/m` lived in
+ * this file and none of them understood ordinary .env syntax. MEASURED against
+ * a stub that echoes the Authorization header it received:
+ *
+ *   INFERALL_API_KEY=ifu_x            -> Bearer ifu_x              ok
+ *   INFERALL_API_KEY="ifu_x"          -> Bearer "ifu_x"            401
+ *   INFERALL_API_KEY='ifu_x'          -> Bearer 'ifu_x'            401
+ *   INFERALL_API_KEY=ifu_x # my key   -> Bearer ifu_x # my key     401
+ *   export INFERALL_API_KEY=ifu_x     -> not found at all
+ *   INFERALL_API_KEY = ifu_x          -> not found at all
+ *
+ * Every one of those is valid dotenv. The first three produce a 401, and
+ * `doctor` then reports "key rejected by gateway. Check <keys page>" -- a
+ * confident wrong cause about a key that is fine, sending the user to mint a
+ * replacement that will fail in exactly the same way. The last two produce
+ * "No key in INFERALL_API_KEY or .env. Run init" while the key is sitting in
+ * the file being read.
+ *
+ * Quoting rules follow dotenv rather than anything invented here: quotes are
+ * stripped only when the same quote opens and closes the value, and an inline
+ * `#` comment is stripped only from an UNQUOTED value, because a quoted one may
+ * legitimately contain a hash.
+ */
+export function parseEnvKey(text) {
+  if (!text) return null;
+  const line = text.split(/\r?\n/).find((l) => /^\s*(?:export\s+)?INFERALL_API_KEY\s*=/.test(l));
+  if (line === undefined) return null;
+  let v = line.replace(/^\s*(?:export\s+)?INFERALL_API_KEY\s*=/, "").trim();
+  const quote = v[0];
+  if (quote === '"' || quote === "'") {
+    // 2026-07-28 tick 840: find the CLOSING quote rather than requiring it to
+    // be the last character of the line. Requiring last-char meant
+    //
+    //     INFERALL_API_KEY="ifu_x" # note
+    //
+    // failed the pair test (last char is "e"), fell through to the unquoted
+    // branch, and returned "ifu_x" WITH the quotes -- the tick 834 bug alive in
+    // the one spelling that has both features at once. Tick 834 tested quotes
+    // and comments separately and never together, which is exactly what the
+    // build-the-awkward-combination rule exists to prevent.
+    const close = v.indexOf(quote, 1);
+    if (close === -1) return v || null;   // unterminated: leave exactly as written
+    v = v.slice(1, close);                // trailing whitespace/comment discarded
+  } else {
+    v = v.replace(/\s+#.*$/, "").trim();  // inline comment, unquoted values only
+  }
+  return v || null;
+}
+
+/**
+ * Read .env as text, reporting WHY it could not be read rather than throwing.
+ *
+ * 2026-07-27 tick 835. Tick 834 unified how the key is PARSED across three call
+ * sites and left how the file is READ alone. Two of those three sites called
+ * readFileSync bare, so an ordinary filesystem state escaped as a Node errno:
+ *
+ *   .env is a directory   -> "✗ EISDIR: illegal operation on a directory, read"
+ *   .env is chmod 000     -> "✗ EACCES: permission denied, open '/long/path/.env'"
+ *
+ * Neither names `.env` as the thing at fault or says what to do, and the first
+ * does not even name a file. Same leak as the bare "fetch failed" fixed in tick
+ * 832: Node's words reaching a user who asked us a question.
+ *
+ * Returns { text, code }: code is null when the file was read, "ENOENT" when
+ * there is no .env at all (not an error, just absent), or the errno.
+ */
+/**
+ * Is there a .env holding a key in an ANCESTOR directory?
+ *
+ * 2026-07-29 tick 850, measured in a monorepo whose key sits at the repo root
+ * with the code in packages/api:
+ *
+ *   doctor (from packages/api)  ->  "INFERALL_API_KEY not found in environment
+ *                                    or .env. Run npx @inferall/cli init"
+ *   init   (from packages/api)  ->  writes packages/api/.env with a SECOND key
+ *
+ * Neither step is wrong on its own. `.env` is conventionally read from the
+ * working directory and this deliberately does NOT change that. The damage is
+ * the CHAIN: doctor reports absence without saying where it looked, tells the
+ * user to run init, and init then creates a second credential for one repo
+ * without mentioning the one already there. Which key the app uses afterwards
+ * depends on the directory it happens to start in.
+ *
+ * So this reports LOCATION ONLY, never the key itself, and both commands use it
+ * to say what they checked rather than to change what they read.
+ *
+ * Stops at the repository root: a .env above someone's checkout is not ours to
+ * reason about. Bounded rather than while(true) because a symlink cycle in a
+ * path walk is a hang, and a hang in `doctor` is the worst failure it has.
+ */
+export function findAncestorEnvKey(startDir) {
+  let dir = startDir;
+  for (let hops = 0; hops < 32; hops++) {
+    const parent = dirname(dir);
+    if (!parent || parent === dir) return null;   // filesystem root
+    dir = parent;
+    // Check the file BEFORE the .git stop, or a key sitting at the repo root
+    // (the single most likely place for it) would be missed by one step.
+    const { text } = readEnvText(dir);
+    if (text && parseEnvKey(text)) return { dir };
+    if (existsSync(join(dir, ".git"))) return null;
+  }
+  return null;
+}
+
+export function readEnvText(root) {
+  const envPath = join(root, ".env");
+  if (!existsSync(envPath)) return { text: null, code: "ENOENT" };
+  try {
+    return { text: readFileSync(envPath, "utf8"), code: null };
+  } catch (err) {
+    return { text: null, code: err?.code || "EUNKNOWN" };
+  }
+}
+
+/** One line explaining an unreadable .env, or null when it read fine. */
+export function envReadProblem(code) {
+  if (!code || code === "ENOENT") return null;
+  if (code === "EISDIR") return ".env is a directory, not a file";
+  if (code === "EACCES" || code === "EPERM") return ".env exists but cannot be read (permission denied)";
+  return `.env could not be read (${code})`;
+}
+
+export function readEnvKey(root) {
+  // Contract unchanged for existing callers: a key, or null for any reason.
+  return parseEnvKey(readEnvText(root).text);
+}
+
+/** Mask a key for display. Never print a whole credential. */
+export function maskKey(k) {
+  return k && k.length > 12 ? `${k.slice(0, 8)}...${k.slice(-4)}` : "(set)";
+}
+
+/**
+ * Why a filesystem operation failed, in words rather than an errno.
+ *
+ * 2026-07-27 tick 836. Companion to envReadProblem (tick 835), which covered
+ * READING .env. This covers the WRITES, which is where it mattered more.
+ */
+export function describeFsError(err, path, action) {
+  const code = err?.code;
+  const why =
+    code === "EISDIR" ? "it is a directory, not a file" :
+    code === "EACCES" || code === "EPERM" ? "permission denied" :
+    code === "EROFS" ? "the filesystem is read-only" :
+    code === "ENOSPC" ? "there is no space left on the device" :
+    code === "ENOTDIR" ? "part of the path is not a directory" :
+    code ? `of ${code}` : "of an unknown error";
+  return `could not ${action} ${basename(path)}: ${why}`;
+}
+
+// writeKey=false leaves the .env key line alone (the user declined a replace)
+// while still ensuring .env.example and .gitignore are correct.
+//
+// 2026-07-27 tick 836: every step here used to be a bare filesystem call. With
+// .gitignore as a directory, MEASURED:
+//
+//     verifying key against … ok
+//     ✗ EISDIR: illegal operation on a directory, read
+//
+// and `.env` on disk containing the key. So the wizard wrote a live credential,
+// failed to protect it, crashed with a Node errno that names no file, and said
+// nothing about either. That is worse than the tick-835 read case: this is a
+// crash MID-MUTATION that leaves a secret exposed.
+//
+// Each step now degrades on its own (the per-file rule from tick 824) and the
+// caller is told what actually happened, in particular whether the key reached
+// disk without gitignore protection.
+function upsertEnvFile(root, key, { writeKey = true } = {}) {
+  const result = { keyWritten: false, problems: [], gitignoreOk: false };
   const envPath = join(root, ".env");
   const line = `INFERALL_API_KEY=${key}`;
-  if (existsSync(envPath)) {
-    const body = readFileSync(envPath, "utf8");
-    if (/^INFERALL_API_KEY=/m.test(body)) {
-      writeFileSync(envPath, body.replace(/^INFERALL_API_KEY=.*$/m, line));
-    } else {
-      appendFileSync(envPath, `${body.endsWith("\n") || body === "" ? "" : "\n"}${line}\n`);
+  if (writeKey) {
+    try {
+      if (existsSync(envPath)) {
+        const body = readFileSync(envPath, "utf8");
+        if (/^INFERALL_API_KEY=/m.test(body)) {
+          writeFileSync(envPath, body.replace(/^INFERALL_API_KEY=.*$/m, line));
+        } else {
+          appendFileSync(envPath, `${body.endsWith("\n") || body === "" ? "" : "\n"}${line}\n`);
+        }
+      } else {
+        writeFileSync(envPath, `${line}\n`);
+      }
+      result.keyWritten = true;
+    } catch (err) {
+      result.problems.push(describeFsError(err, envPath, "write"));
     }
-  } else {
-    writeFileSync(envPath, `${line}\n`);
   }
 
   const examplePath = join(root, ".env.example");
   const exampleLine = "INFERALL_API_KEY=ifu_your_key_here";
-  if (existsSync(examplePath)) {
-    const body = readFileSync(examplePath, "utf8");
-    if (!/^INFERALL_API_KEY=/m.test(body)) {
-      appendFileSync(examplePath, `${body.endsWith("\n") || body === "" ? "" : "\n"}${exampleLine}\n`);
+  try {
+    if (existsSync(examplePath)) {
+      const body = readFileSync(examplePath, "utf8");
+      if (!/^INFERALL_API_KEY=/m.test(body)) {
+        appendFileSync(examplePath, `${body.endsWith("\n") || body === "" ? "" : "\n"}${exampleLine}\n`);
+      }
+    } else {
+      writeFileSync(examplePath, `${exampleLine}\n`);
     }
-  } else {
-    writeFileSync(examplePath, `${exampleLine}\n`);
+  } catch (err) {
+    result.problems.push(describeFsError(err, examplePath, "write"));
   }
 
   const giPath = join(root, ".gitignore");
-  if (existsSync(giPath)) {
-    const gi = readFileSync(giPath, "utf8");
-    if (!gi.split("\n").some((l) => l.trim() === ".env" || l.trim() === ".env*" || l.trim() === "*.env")) {
-      appendFileSync(giPath, `${gi.endsWith("\n") ? "" : "\n"}.env\n`);
-      console.log(`  ${c.green("+")} added ${c.bold(".env")} to .gitignore`);
+  try {
+    if (existsSync(giPath)) {
+      const gi = readFileSync(giPath, "utf8");
+      if (!gi.split("\n").some((l) => l.trim() === ".env" || l.trim() === ".env*" || l.trim() === "*.env")) {
+        appendFileSync(giPath, `${gi.endsWith("\n") ? "" : "\n"}.env\n`);
+        console.log(`  ${c.green("+")} added ${c.bold(".env")} to .gitignore`);
+      }
+      result.gitignoreOk = true;
+    } else {
+      writeFileSync(giPath, ".env\n");
+      console.log(`  ${c.green("+")} created .gitignore with .env`);
+      result.gitignoreOk = true;
     }
-  } else {
-    writeFileSync(giPath, ".env\n");
-    console.log(`  ${c.green("+")} created .gitignore with .env`);
+  } catch (err) {
+    result.problems.push(describeFsError(err, giPath, "update"));
+  }
+
+  // 2026-07-27 tick 821. .gitignore does NOTHING for a file git is ALREADY
+  // tracking, and we have just written an API key into that file.
+  //
+  // Measured: on a repo with .env committed, init printed
+  //   + created .gitignore with .env
+  //   + INFERALL_API_KEY written to .env
+  // and left `git status` showing " M .env". The next `git add .` commits a
+  // live credential, and our own output had just implied it was protected.
+  //
+  // ls-files reads the INDEX, which is the question being asked. check-ignore
+  // reads the working tree and would answer a different one (that scar is why
+  // this is spelled out).
+  // 2026-07-28 tick 839: tri-state. We have just written a credential, so
+  // "could not check" is worth a line of its own here rather than silence.
+  const track = result.keyWritten ? gitTrackStatus(root) : "untracked";
+  if (track === "tracked") {
+    console.log(`  ${c.red("!")} ${c.bold(".env is tracked by git")} and now contains your API key.`);
+    console.log(`    .gitignore does not apply to already-tracked files. Untrack it before committing:`);
+    console.log(c.cyan(`      git rm --cached .env`));
+  } else if (track === "unknown") {
+    console.log(`  ${c.yellow("~")} could not check whether ${c.bold(".env")} is tracked by git (git is not available here).`);
+    console.log(`    If it is already committed, .gitignore will not protect the key you just saved.`);
   }
+  return result;
+}
+
+/**
+ * Is .env in the git index? Returns false when there is no repo, no git on
+ * PATH, or the file is untracked. Never throws: this is advisory, and a wizard
+ * that dies because git is missing is worse than one that stays quiet.
+ */
+/**
+ * Is .env in git's index? "tracked" | "untracked" | "unknown".
+ *
+ * 2026-07-28 tick 839. This used to be a bare boolean, and it answered FALSE in
+ * two very different situations: git said no, and git could not be asked.
+ * MEASURED on a repo whose .env IS committed, with git removed from PATH:
+ *
+ *   git present -> true
+ *   git absent  -> false        <-- same answer as "your .env is safe"
+ *
+ * doctor then prints "✓ .env hygiene ok" over a committed credential, which is
+ * precisely the bug fixed in tick 825 coming back through a different door
+ * whenever git is not installed (slim containers, minimal CI images).
+ *
+ * A guard that cannot run must not report a pass. "unknown" is only for a git
+ * that could not be executed: a directory that is not a repository at all
+ * genuinely has no tracked files, so that stays "untracked" and the green tick
+ * there is honest.
+ */
+export function gitTrackStatus(root) {
+  let r;
+  try {
+    r = spawnSync("git", ["ls-files", "--error-unmatch", ".env"], {
+      cwd: root, stdio: "ignore", timeout: 5000,
+    });
+  } catch {
+    return "unknown";
+  }
+  if (r.error || r.status === null) return "unknown";   // git missing, or killed
+  if (r.status === 0) return "tracked";
+  return "untracked";                                    // includes "not a repo"
+}
+
+/** Boolean contract preserved for callers that only care about the yes case. */
+export function envIsGitTracked(root) {
+  return gitTrackStatus(root) === "tracked";
 }
 
 // ---------- gateway API helpers ----------
 
+// Distinctive User-Agent so gateway-side ai_usage_log.client_ua attributes
+// wizard-originated calls to the CLI (and which command) — lets us measure
+// how many people actually run `init` without any gateway change or new
+// telemetry column. `cmd` is the subcommand (init/doctor/models/status).
+// The gateway records client_ua on every call, so the sha rides along and
+// telemetry can tell two builds of one version apart. Semver build-metadata
+// spelling (+sha) so anything already parsing the version keeps working.
+const CLI_UA = `@inferall/cli/${CLI_VERSION}${BUILD_INFO?.sha ? `+${BUILD_INFO.sha}` : ""} (${cmd})`;
+
 async function apiGet(path, key) {
   const res = await fetch(`${API_BASE}${path}`, {
-    headers: { Authorization: `Bearer ${key}` },
+    signal: timeoutSignal(),
+    headers: { Authorization: `Bearer ${key}`, "User-Agent": CLI_UA },
   });
   return { status: res.status, body: await res.json().catch(() => ({})) };
 }
 
-async function apiChat(key, messages, model = FREE_MODEL) {
+// maxTokens is a parameter rather than a constant as of tick 817: the chat
+// command now tells a user whose reasoning model ran out of budget to retry
+// with a larger --max-tokens, and a message that names a flag which does not
+// exist is worse than no message. Default is the previous hardcoded 512, so
+// every other caller is unchanged.
+async function apiChat(key, messages, model = FREE_MODEL, maxTokens = 512) {
   const res = await fetch(`${API_BASE}/chat/completions`, {
+    signal: timeoutSignal(),
     method: "POST",
-    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-    body: JSON.stringify({ model, messages, max_tokens: 512 }),
+    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", "User-Agent": CLI_UA },
+    body: JSON.stringify({ model, messages, max_tokens: maxTokens }),
   });
-  return { status: res.status, body: await res.json().catch(() => ({})) };
+  // 2026-07-27 tick 833: this used to be `await res.json().catch(() => ({}))`,
+  // which collapsed two different facts into one empty object: "the server sent
+  // JSON with nothing useful in it" and "the server sent something that is not
+  // JSON at all". A proxy 502 is an HTML page, and the caller printed
+  //
+  //     HTTP 502: {}
+  //
+  // Reading the body as text first keeps the distinction, and keeps a snippet
+  // so we can quote what actually arrived instead of an empty object.
+  const raw = await res.text().catch(() => "");
+  let body = {};
+  let parseFailed = false;
+  if (raw) {
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      parseFailed = true;
+    }
+  }
+  return {
+    status: res.status,
+    body,
+    parseFailed,
+    raw,
+    contentType: res.headers.get("content-type") || "",
+    retryAfter: res.headers.get("retry-after"),
+  };
+}
+
+
+/**
+ * Read a response as JSON, or say plainly that it was not JSON.
+ *
+ * WHY THIS EXISTS (2026-07-31, tick 886)
+ * -------------------------------------
+ * `chat` has handled this correctly since tick 833: a body it cannot parse is a
+ * FAILED call whatever the status line said. That fix was never carried to the
+ * other three commands, and they each failed differently against a stub serving
+ * a corporate proxy login page with HTTP 200:
+ *
+ *     models   raw Node text: Unexpected token '<', "<!DOCTYPE "...
+ *     status   the same raw text
+ *     doctor   rc=0 and "key accepted by gateway"      <-- the bad one
+ *
+ * doctor is the DIAGNOSTIC command. Behind a captive portal or a proxy that
+ * intercepts HTTPS it told the user their setup was healthy, because it looked
+ * only at r.status and a login page is served with 200.
+ *
+ * Returns the same shape apiChat already returns, so nonJsonSummary works on it.
+ */
+async function readJsonBody(res) {
+  const raw = await res.text().catch(() => "");
+  let body = {};
+  let parseFailed = false;
+  if (raw) {
+    try { body = JSON.parse(raw); } catch { parseFailed = true; }
+  }
+  /*
+   * TRIAL HEADERS, 2026-08-03 tick 929.
+   *
+   * The gateway emits X-InferAll-Trial-Usage ("N/cap") and
+   * X-InferAll-Trial-Status on every SUCCESSFUL call from a trial key. We were
+   * reading content-type off this response and throwing the rest away, so the
+   * countdown was on the wire for every call the CLI ever made and never once
+   * reached the person spending it.
+   *
+   * Read here rather than at the call site because every caller goes through
+   * this function, so a future command gets the counter for free instead of
+   * rediscovering the header.
+   */
+  return {
+    status: res.status,
+    body,
+    parseFailed,
+    raw,
+    contentType: res.headers.get("content-type") || "",
+    trialUsage: res.headers.get("x-inferall-trial-usage") || "",
+    trialStatus: res.headers.get("x-inferall-trial-status") || "",
+  };
+}
+
+/**
+ * Render "N/cap" from the gateway into a line worth printing, or null.
+ *
+ * Returns null when the header is absent (a paid key sends none, and a paid
+ * user must not be shown a trial counter) or unparseable. Exported shape kept
+ * pure so the thresholds below are testable without a network call.
+ *
+ * WHY IT ESCALATES RATHER THAN ALWAYS PRINTING THE SAME LINE. Measured since
+ * the micro-trial: 9 real users hit the ceiling, and SEVEN OF THE NINE spent
+ * all five calls within 0.0 to 0.3 hours of their first one, several through
+ * agent tooling that burns the whole allowance inside a single task. A line
+ * that reads identically at 4 remaining and at 1 remaining is wallpaper by the
+ * time it matters, so the last call before the wall says so plainly.
+ */
+function trialCountdownLine(trialUsage) {
+  const m = /^(\d+)\s*\/\s*(\d+)$/.exec((trialUsage || "").trim());
+  if (!m) return null;
+  const used = Number(m[1]);
+  const cap = Number(m[2]);
+  if (!Number.isFinite(used) || !Number.isFinite(cap) || cap <= 0) return null;
+  const left = Math.max(0, cap - used);
+  if (left === 0) {
+    return `${c.yellow("~")} that was your last free call. ${c.dim(`Activate at https://inferall.ai/billing to keep going.`)}`;
+  }
+  if (left === 1) {
+    return `${c.yellow("~")} 1 free call left of ${cap}. ${c.dim(`Run ${"npx @inferall/cli status"} for details.`)}`;
+  }
+  return `${c.dim(`· ${left} free calls left of ${cap}`)}`;
+}
+
+/** The lines every caller prints when the gateway sent something unparseable. */
+function nonJsonLines(r, indent = "") {
+  return [
+    `${indent}${c.red("✗")} ${nonJsonSummary(r)}`,
+    `${indent}  HTTP ${r.status}, but the body is not JSON, so nothing was verified.`,
+    `${indent}  A proxy or captive portal intercepting HTTPS produces exactly this.`,
+  ];
+}
+
+/**
+ * When a write fails, is the DIRECTORY the problem rather than the file?
+ *
+ * WHY THIS EXISTS (2026-07-31, tick 887)
+ * -------------------------------------
+ * Measured with `init` in a directory at mode 555: every write failed with
+ * "permission denied" and the wizard then said "fix the file above" and "until
+ * the file above is fixed". There IS no file to fix. .env was never created,
+ * so `chmod +w .env` cannot work, and the user is sent to look for something
+ * that does not exist.
+ *
+ * That is the same defect this changelog keeps recording in a new place: the
+ * message names a cause confidently and names the wrong one. The remedy for an
+ * unwritable directory is different from the remedy for an unwritable file, so
+ * the two have to be told apart before either is recommended.
+ */
+function dirIsUnwritable(root) {
+  try {
+    accessSync(root, fsConstants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Is this a model catalog, an object of {id: pricingObject}?
+ *
+ * An empty object is a legitimate catalog; emptiness is a different complaint
+ * and check-pricing-coverage already owns it.
+ */
+export function isCatalogShape(map) {
+  if (!map || typeof map !== "object" || Array.isArray(map)) return false;
+  return Object.values(map).every((v) => v && typeof v === "object" && !Array.isArray(v));
+}
+
+/**
+ * One line describing a body we could not parse. Used wherever a caller has to
+ * explain a non-JSON response without pasting an HTML page into a terminal.
+ */
+export function nonJsonSummary({ contentType, raw }) {
+  const kind = /html/i.test(contentType) ? "an HTML page" : contentType ? `content-type ${contentType}` : "a non-JSON body";
+  const title = /<title>([^<]{1,80})<\/title>/i.exec(raw || "")?.[1]?.trim();
+  const snippet = title || (raw || "").replace(/\s+/g, " ").trim().slice(0, 80);
+  return `the gateway returned ${kind}${snippet ? `: ${c.dim(snippet)}` : ""}`;
 }
 
 // ---------- codemod: point OpenAI SDK at InferAll ----------
@@ -156,8 +1144,43 @@ async function apiChat(key, messages, model = FREE_MODEL) {
 const SOURCE_EXTS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py"]);
 const SKIP_DIRS = new Set(["node_modules", ".git", ".next", "dist", "build", "venv", ".venv", "__pycache__", ".turbo"]);
 
-function* walk(dir, depth = 0) {
-  if (depth > 6) return;
+// Notebooks are deliberately NOT in SOURCE_EXTS. A .ipynb is JSON, so handing
+// it to the text codemod would rewrite escaped source inside a JSON string and
+// corrupt the file. They get their own walk and their own honest report.
+const NOTEBOOK_EXTS = new Set([".ipynb"]);
+// Notebooks carry base64 image outputs, so the source-file cap is far too low
+// for them. Only cell.source is ever read; the outputs are skipped.
+const NOTEBOOK_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Walk the project for source files.
+ *
+ * 2026-07-30 tick 854. Two of the limits here used to stop the walk SILENTLY,
+ * and the caller then printed a count and declared success over it. MEASURED,
+ * with three identical `new OpenAI({...})` sites in one project:
+ *
+ *     Found 1 client constructor site(s):
+ *     Done. Your project is wired to InferAll.
+ *
+ * while `packages/api/src/lib/clients/openai/v1/deep.js` (one level past the
+ * depth cap) and a 600KB file were never opened, and both still called OpenAI
+ * directly. That is the tick 805 failure verbatim: a wizard that reports a wired
+ * project and hands back one that throws "OPENAI_API_KEY is missing or empty" on
+ * its first run. The codemod suite exists because of that exact outcome.
+ *
+ * THE LIMITS STAY. A depth bound and a size bound are correct: they keep `init`
+ * from walking a vendored tree or reading a bundle, and raising them trades one
+ * failure for a slower one. What was wrong is that stopping early was invisible.
+ *
+ * `capped` collects ONLY the limit-driven skips. SKIP_DIRS, dotfiles and
+ * unreadable entries are deliberate and universal, and reporting them would bury
+ * the two that actually hide a user's code in noise nobody reads.
+ */
+function* walk(dir, depth = 0, exts = SOURCE_EXTS, maxBytes = 512 * 1024, capped = null) {
+  if (depth > 6) {
+    capped?.push({ path: dir, why: "deeper than 6 directory levels" });
+    return;
+  }
   let entries = [];
   try {
     entries = readdirSync(dir);
@@ -173,14 +1196,111 @@ function* walk(dir, depth = 0) {
     } catch {
       continue;
     }
-    if (st.isDirectory()) yield* walk(full, depth + 1);
-    else if (st.isFile() && SOURCE_EXTS.has(extname(name)) && st.size < 512 * 1024) yield full;
+    if (st.isDirectory()) yield* walk(full, depth + 1, exts, maxBytes, capped);
+    else if (st.isFile() && exts.has(extname(name))) {
+      if (st.size < maxBytes) yield full;
+      else capped?.push({ path: full, why: `larger than ${Math.round(maxBytes / 1024)}KB` });
+    }
   }
 }
 
-function findCallSites(root) {
+/**
+ * One line naming what the walk never opened, or null when it opened everything.
+ * Separate from walk() so both the scan and its reporting read the same list.
+ */
+export function cappedSummary(capped) {
+  if (!capped?.length) return null;
+  const dirs = capped.filter((c) => c.why.startsWith("deeper")).length;
+  const big = capped.length - dirs;
+  const parts = [];
+  if (dirs) parts.push(`${dirs} director${dirs === 1 ? "y" : "ies"} deeper than 6 levels`);
+  if (big) parts.push(`${big} file${big === 1 ? "" : "s"} over the size limit`);
+  return `${parts.join(" and ")} were not scanned`;
+}
+
+/**
+ * Jupyter notebooks that construct an AI client.
+ *
+ * 2026-07-26 tick 816. `.ipynb` was not in SOURCE_EXTS, so findCallSites never
+ * looked inside one. But requirements.txt still lists `openai`, so `usesSdk`
+ * was true, the wizard called findCallSites, got ZERO sites back and printed:
+ *
+ *     ✓ AI SDK present but no un-migrated client constructors found.
+ *
+ * over a notebook still calling OpenAI directly. That is the same false green
+ * tick as t811's async clients, and notebooks are where a large share of Python
+ * AI code actually lives.
+ *
+ * REPORTED, NOT PATCHED, and that is a deliberate scope choice rather than an
+ * oversight. A notebook is JSON carrying execution counts and output blobs;
+ * round-tripping it through parse/stringify rewrites the formatting of every
+ * line in the file, and this tool promises "your code otherwise untouched".
+ * The existing Gemini path makes the same call for the same reason. A user
+ * pastes one line into a cell; a mangled notebook diff is much worse than that.
+ *
+ * Class list comes from CLIENT_CLASSES so notebooks cannot silently support a
+ * different set of SDKs than plain .py files do.
+ */
+/**
+ * Does this source text already send its traffic to InferAll?
+ *
+ * 2026-07-27 tick 830. Extracted so `findCallSites` and `findNotebookSites`
+ * cannot answer it differently. `doctor` needed the notebook answer and there
+ * was no way to get one, which is how it ended up reporting "no client
+ * constructors found" over a notebook holding a live OpenAI key.
+ */
+export function pointsAtInferAll(text) {
+  return text.includes(new URL(API_BASE).host);
+}
+
+export function findNotebookSites(root) {
   const sites = [];
-  for (const file of walk(root)) {
+  for (const file of walk(root, 0, NOTEBOOK_EXTS, NOTEBOOK_MAX_BYTES)) {
+    let nb;
+    try {
+      nb = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      continue;   // not valid JSON, or not a notebook we understand
+    }
+    if (!Array.isArray(nb.cells)) continue;
+    const hits = [];
+    nb.cells.forEach((cell, index) => {
+      if (cell.cell_type !== "code") return;
+      // nbformat allows source as either a string or an array of line strings.
+      // Both shapes occur in the wild; JupyterLab writes the array form.
+      const src = Array.isArray(cell.source) ? cell.source.join("") : (cell.source || "");
+      if (typeof src !== "string" || !src) return;
+      for (const sdk of Object.keys(CLIENT_CLASSES)) {
+        // alreadyPointed is per CELL, not per file: a notebook routinely holds
+        // one migrated client and one somebody forgot.
+        if (new RegExp(`\\b${sdk}\\s*\\(`).test(src)) {
+          hits.push({ index, sdk, alreadyPointed: pointsAtInferAll(src) });
+        }
+      }
+    });
+    if (hits.length) sites.push({ file, hits });
+  }
+  return sites;
+}
+
+function printNotebookGuidance(root, sites) {
+  const total = sites.reduce((n, s) => n + s.hits.length, 0);
+  console.log(`\n  ${c.bold("Jupyter notebook")} client(s) found in ${sites.length} file(s), ${total} cell(s):`);
+  for (const s of sites) {
+    for (const h of s.hits) {
+      console.log(`    - ${relative(root, s.file)} ${c.dim(`cell ${h.index} (${h.sdk})`)}`);
+    }
+  }
+  console.log(`  These were ${c.bold("NOT changed")}. Rewriting a notebook would reformat the whole`);
+  console.log(`  file, so edit the cell yourself. Add these two arguments to the client:`);
+  const anySdk = sites[0].hits[0].sdk;
+  console.log(c.cyan(`    ${anySdk}(base_url="${baseForSdk(anySdk)}", api_key=os.environ["INFERALL_API_KEY"])`));
+  console.log(`  ${c.dim(`(and \`import os\` in that cell if it is not there already)`)}`);
+}
+
+export function findCallSites(root, capped = null) {
+  const sites = [];
+  for (const file of walk(root, 0, SOURCE_EXTS, 512 * 1024, capped)) {
     let body;
     try {
       body = readFileSync(file, "utf8");
@@ -189,7 +1309,35 @@ function findCallSites(root) {
     }
     const isPy = file.endsWith(".py");
     const baseKey = isPy ? "base_url" : "baseURL";
-    for (const sdk of ["OpenAI", "Anthropic"]) {
+    // LangChain chat classes. \b does not match inside "ChatOpenAI" (t and O
+    // are both word characters), so the plain "OpenAI" pattern never caught
+    // these.
+    //
+    // 2026-07-26 tick 807 -- CORRECTING MYSELF. At tick 805 I excluded
+    // ChatAnthropic and wrote that langchain-anthropic "uses a different
+    // parameter name, and emitting base_url= there would produce a constructor
+    // that raises at import". That was an assumption, and it was WRONG.
+    // Measured by installing the package and introspecting it:
+    //
+    //   ChatAnthropic.model_fields["anthropic_api_url"].alias == "base_url"
+    //   ChatAnthropic.model_fields["anthropic_api_key"].alias == "api_key"
+    //
+    // and both forms construct successfully. `base_url=` is a supported alias,
+    // not a foreign parameter. Deferring it was right (I had not checked);
+    // the REASON I recorded was not.
+    // 2026-07-26 tick 811: AsyncOpenAI and AsyncAnthropic were invisible here.
+    // \b does not match inside "AsyncOpenAI" (c and O are both word
+    // characters), the same reason ChatOpenAI was missed at t805 -- but this
+    // one failed WORSE. `openai` is in CODEMODDABLE, so usesSdk was true, the
+    // wizard called findCallSites, got zero sites back, and printed
+    //
+    //     ✓ AI SDK present but no un-migrated client constructors found.
+    //
+    // over an async FastAPI service that was still calling OpenAI directly.
+    // A confident green tick, not the honest "couldn't patch" fallback. Async
+    // clients are the norm for Python AI backends, so this is not a corner.
+    // Both classes verified against the installed SDKs to accept base_url.
+    for (const sdk of Object.keys(CLIENT_CLASSES)) {
       const ctorRe = isPy ? new RegExp(`\\b${sdk}\\s*\\(`) : new RegExp(`new\\s+${sdk}\\s*\\(`);
       if (!ctorRe.test(body)) continue;
       sites.push({
@@ -197,7 +1345,7 @@ function findCallSites(root) {
         body,
         isPy,
         sdk,
-        alreadyPointed: body.includes(new URL(API_BASE).host),
+        alreadyPointed: pointsAtInferAll(body),
         hasBaseUrl: new RegExp(`${baseKey}\\s*[:=]`).test(body),
       });
     }
@@ -205,11 +1353,151 @@ function findCallSites(root) {
   return sites;
 }
 
+/**
+ * Every client class we can rewrite, and which base URL each one needs.
+ *
+ * ONE SOURCE OF TRUTH, deliberately. Before tick 811 this knowledge lived in
+ * three places: the class list in findCallSites, and two separate
+ * `sdk === "Anthropic" || sdk === "ChatAnthropic"` chains. The third copy had
+ * ALREADY drifted: the manual-fallback message tested only `=== "Anthropic"`,
+ * so a ChatAnthropic site we could not patch told the user to set the /v1 base
+ * when LangChain's Anthropic client needs the host root. Wrong instructions to
+ * the one user we had just failed to help automatically.
+ *
+ * That is the same shape as the tick-805 "third hardcoded list" bug. Adding
+ * AsyncOpenAI and AsyncAnthropic to a fourth chain would have been asking for
+ * it a third time, so the chains are gone.
+ *
+ * "anthropic" here means the SDK appends /v1 itself, so it gets the host root.
+ *
+ * NOT IN THIS TABLE, ON PURPOSE: llama_index.llms.openai.OpenAI. It collides
+ * with the plain OpenAI class name, and it is TEMPTING to assume it takes
+ * base_url. It does not. Measured against the installed package at tick 811:
+ *
+ *   OpenAI.model_fields has api_base, and has NO base_url
+ *   OpenAI(base_url="https://api.inferall.ai/v1", ...) does NOT raise
+ *   ...and the resolved api_base stays https://api.openai.com/v1
+ *
+ * So patching it with base_url= would leave the project calling OpenAI
+ * directly while we printed a green tick over it. Silently ignored is worse
+ * than rejected. It needs an api_base= branch before it can be added.
+ */
+const CLIENT_CLASSES = {
+  OpenAI: "openai",
+  AsyncOpenAI: "openai",
+  Anthropic: "anthropic",
+  AsyncAnthropic: "anthropic",
+  ChatOpenAI: "openai",
+  ChatAnthropic: "anthropic",
+};
+
+// The base URL a given client class must be given. Derived, never re-typed.
+export function baseForSdk(sdk) {
+  return CLIENT_CLASSES[sdk] === "anthropic" ? ANTHROPIC_BASE : API_BASE;
+}
+
+// Repoint the CREDENTIAL inside a constructor we have just pointed at InferAll.
+//
+// 2026-07-25: the object-form branch below used to inject only `baseURL`,
+// leaving `apiKey: process.env.OPENAI_API_KEY` untouched while `init` wrote the
+// key to .env as INFERALL_API_KEY. The wizard then printed
+// "Done. Your project is wired to InferAll." and the user's very next run threw
+//   OpenAIError: The OPENAI_API_KEY environment variable is missing or empty
+// i.e. the one-command installer reported success and left a broken project.
+// That is the worst possible outcome for onboarding, and it plausibly accounts
+// for part of the mint -> never-called gap.
+//
+// It survived because the wizard's own "test call ✓" uses the key DIRECTLY
+// rather than the code it just wrote; it verified a convenient proxy instead
+// of the path the user takes. Caught by running the generated project.
+//
+// The rewrite is scoped to the constructor's argument list (brace/paren depth)
+// so an unrelated OPENAI_API_KEY elsewhere in the file is left alone.
+export function repointApiKey(src, sdk, isPy) {
+  const ctor = isPy
+    ? new RegExp(`\\b${sdk}\\s*\\(`)
+    : new RegExp(`new\\s+${sdk}\\s*\\(\\s*\\{`);
+  const m = ctor.exec(src);
+  if (!m) return src;
+  const start = m.index + m[0].length;
+  const open = isPy ? "(" : "{";
+  const close = isPy ? ")" : "}";
+  let depth = 1;
+  let end = start;
+  while (end < src.length && depth > 0) {
+    const ch = src[end];
+    if (ch === open) depth++;
+    else if (ch === close) depth--;
+    end++;
+  }
+  const head = src.slice(0, start);
+  const region = src.slice(start, end);
+  const tail = src.slice(end);
+
+  const want = isPy ? `os.environ["INFERALL_API_KEY"]` : `process.env.INFERALL_API_KEY`;
+  const keyRe = isPy
+    ? /os\.(?:environ\[\s*["'](?:OPENAI|ANTHROPIC|GOOGLE|GEMINI|OPENROUTER)_API_KEY["']\s*\]|getenv\(\s*["'](?:OPENAI|ANTHROPIC|GOOGLE|GEMINI|OPENROUTER)_API_KEY["']\s*\))/g
+    : /process\.env\.(?:OPENAI|ANTHROPIC|GOOGLE|GEMINI|OPENROUTER)_API_KEY/g;
+
+  if (keyRe.test(region)) {
+    keyRe.lastIndex = 0;
+    return head + region.replace(keyRe, want) + tail;
+  }
+
+  // 2026-07-26 tick 810: the HARDCODED-LITERAL case. Until now this function
+  // only understood a credential read from an env var. A constructor written
+  //
+  //     new OpenAI({ apiKey: "sk-live-abc123" })
+  //     OpenAI(api_key="sk-live-abc123")
+  //
+  // fell through both branches (`hasKey` is true, so we returned the region
+  // untouched) and the caller then pointed baseURL at InferAll anyway. The
+  // user ends up sending a foreign provider key to our gateway: the exact
+  // "wired to InferAll, fails on first call" shape fixed at tick 800 for env
+  // vars, still open for literals. Pre-existing in BOTH languages; found by
+  // running the patcher over a module-qualified `openai.OpenAI(api_key="…")`.
+  //
+  // Deliberately keyed on the PROVIDER KEY SHAPE, not on "any string literal".
+  // Local-inference users legitimately write api_key="EMPTY" or "ollama" for
+  // vLLM/Ollama, and silently rewriting those would be us editing something we
+  // do not understand. Those are left alone and reported by the post-patch
+  // check instead. sk- covers OpenAI, Anthropic and OpenRouter; AIza is Google.
+  const literalRe = isPy
+    ? /(\bapi_key\s*=\s*)(["'])(?:sk-[A-Za-z0-9_-]{8,}|AIza[A-Za-z0-9_-]{10,})\2/
+    : /(\bapiKey\s*:\s*)(["'])(?:sk-[A-Za-z0-9_-]{8,}|AIza[A-Za-z0-9_-]{10,})\2/;
+  if (literalRe.test(region)) {
+    return head + region.replace(literalRe, `$1${want}`) + tail;
+  }
+
+  // No credential passed at all: the SDK falls back to the PROVIDER's env var,
+  // which is just as broken once baseURL points at us. Supply ours.
+  const hasKey = isPy ? /\bapi_key\s*=/.test(region) : /\bapiKey\s*:/.test(region);
+  if (!hasKey) {
+    return head + (isPy ? `api_key=${want}, ` : `apiKey: ${want}, `) + region + tail;
+  }
+  return head + region + tail;
+}
+
+// `import os` is required by every Python rewrite we emit (all of them read
+// os.environ["INFERALL_API_KEY"]). Skipped when the module already imports it.
+// The shebang must stay on line 1 to keep working, so insert below it.
+export function ensureImportOs(src) {
+  // `import os` and `import os.path` both bind the name `os`. `from os import
+  // environ` does NOT — a file with only that line still needs the import, or
+  // the os.environ[...] we emit raises NameError. Adding a redundant import is
+  // harmless; omitting a required one is not.
+  if (/^\s*import os(\b|\.)/m.test(src)) return src;
+  const lines = src.split("\n");
+  const at = lines[0]?.startsWith("#!") ? 1 : 0;
+  lines.splice(at, 0, "import os");
+  return lines.join("\n");
+}
+
 // Deterministic rewrite for the common zero-arg / simple-config constructor.
 // The OpenAI SDK's baseURL includes /v1; the Anthropic SDK appends /v1 itself.
-function patchSite(site) {
+export function patchSite(site) {
   const { body, isPy, sdk } = site;
-  const base = sdk === "Anthropic" ? ANTHROPIC_BASE : API_BASE;
+  const base = baseForSdk(sdk);
   const baseLine = isPy
     ? `base_url="${base}", api_key=os.environ["INFERALL_API_KEY"]`
     : `baseURL: "${base}", apiKey: process.env.INFERALL_API_KEY`;
@@ -219,15 +1507,80 @@ function patchSite(site) {
     const bare = new RegExp(`\\b${sdk}\\s*\\(\\s*\\)`);
     if (bare.test(body)) {
       patched = body.replace(bare, `${sdk}(${baseLine})`);
-      if (!/^import os$/m.test(patched)) patched = `import os\n${patched}`;
+    } else {
+      // 2026-07-26 tick 810: the keyword-argument form. Until now the Python
+      // codemod handled ONLY the bare `OpenAI()` constructor, while the
+      // JavaScript branch below handled both bare AND config-object form. That
+      // asymmetry was not a decision — the branch was simply never written.
+      //
+      // Measured before writing this, by running the real patcher over six
+      // realistic Python files: 5 of 6 returned null. Every one of these is a
+      // form you would find in an actual project:
+      //
+      //   OpenAI(api_key=os.environ["OPENAI_API_KEY"])      -> null
+      //   OpenAI(api_key=os.getenv("OPENAI_API_KEY"))       -> null
+      //   self.client = OpenAI(api_key=...)   (in a class)  -> null
+      //   return OpenAI(\n  api_key=...,\n  timeout=30,\n)  -> null
+      //   Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])-> null
+      //
+      // Those users were not silently broken (the t805 fallback prints an
+      // honest "couldn't patch automatically"), but they were pushed onto the
+      // AI-assist path — which costs a call and is skipped entirely on a 402 —
+      // to do something the deterministic codemod can do exactly.
+      //
+      // Guards, in order of how badly each would break a file:
+      //   (?<!class\s)(?<!def\s)  — `class OpenAI(Base):` and `def OpenAI(x):`
+      //     both match a bare `\bOpenAI\s*\(`, and injecting base_url= into a
+      //     class or def header produces a file that will not import.
+      //   \b — keeps `OpenAI` from matching inside `ChatOpenAI` (t805), while
+      //     still allowing the `openai.OpenAI(...)` module-qualified form.
+      //   !site.hasBaseUrl — never touch a client already given a base_url.
+      const kw = new RegExp(`(?<!class\\s)(?<!def\\s)\\b${sdk}\\s*\\([ \\t]*`);
+      if (kw.test(body) && !site.hasBaseUrl) {
+        // Same separator rule as the JS branch: emit the space only when
+        // something follows on the SAME line, so a multiline constructor keeps
+        // its newline and does not gain trailing whitespace.
+        patched = body.replace(kw, (match, offset, whole) => {
+          const nextCh = whole[offset + match.length];
+          const sep = nextCh === "\n" || nextCh === "\r" ? "" : " ";
+          return `${sdk}(base_url="${base}",${sep}`;
+        });
+        patched = repointApiKey(patched, sdk, true);
+      }
     }
+    // Hoisted out of the bare branch so BOTH paths get the import they need —
+    // every Python rewrite here emits os.environ[...]. Inserted after a shebang
+    // rather than above it: `#!/usr/bin/env python3` only works on line 1, and
+    // the old unconditional prepend would have silently disarmed it.
+    if (patched) patched = ensureImportOs(patched);
   } else {
     const bare = new RegExp(`new\\s+${sdk}\\s*\\(\\s*\\)`);
-    const obj = new RegExp(`new\\s+${sdk}\\s*\\(\\s*\\{`);
+    // 2026-07-26 tick 802: consume the spaces/tabs AFTER the brace so the
+    // injected `baseURL: ...,` does not collide with the original's leading
+    // space and produce `,  apiKey` (two spaces). Found by running init on an
+    // Anthropic project and reading the patched line, not the code.
+    //
+    // [ \t]* deliberately, NOT \s*: a multiline constructor
+    //     new OpenAI({
+    //       apiKey: ...
+    //     })
+    // must keep its newline and indentation. Collapsing that onto one line
+    // would be real reformatting, which is a bigger sin than a double space --
+    // the README promises "your code otherwise untouched".
+    const obj = new RegExp(`new\\s+${sdk}\\s*\\(\\s*\\{[ \\t]*`);
     if (bare.test(body)) {
       patched = body.replace(bare, `new ${sdk}({ ${baseLine} })`);
     } else if (obj.test(body) && !site.hasBaseUrl) {
-      patched = body.replace(obj, `new ${sdk}({ baseURL: "${base}", `);
+      // Emit the separating space only when something follows on the SAME
+      // line. On a multiline constructor the next character is a newline, and
+      // a space before it is trailing whitespace (eslint no-trailing-spaces,
+      // and a red block in the diff). Two artifacts, one decision point.
+      patched = body.replace(obj, (match, offset, whole) => {
+        const nextCh = whole[offset + match.length];
+        const sep = nextCh === "\n" || nextCh === "\r" ? "" : " ";
+        return `new ${sdk}({ baseURL: "${base}",${sep}`;
+      });
+      patched = repointApiKey(patched, sdk, false);
     }
   }
   return patched;
@@ -257,6 +1610,115 @@ function findGeminiSites(root) {
   return sites;
 }
 
+/**
+ * Vercel AI SDK call sites (`ai` + `@ai-sdk/<provider>`).
+ *
+ * 2026-07-26 tick 804: `ai` is in NODE_SDKS, so a Vercel-AI project was
+ * DETECTED, but its code has no `new OpenAI({...})` constructor to rewrite --
+ * the provider is `openai("gpt-4o-mini")` from `@ai-sdk/openai`. The codemod
+ * found nothing, the wizard fell through to its greenfield branch, wrote a
+ * hello-world, and printed "Done. Your project is wired to InferAll" while
+ * src/gen.js still routed to OpenAI directly.
+ *
+ * Same failure family as the tick-803 monorepo bug: detected the project and
+ * reported success while migrating none of it. Detection alone is not the
+ * promise; the promise is that the code now points here.
+ *
+ * Unlike Gemini, this one IS re-pointable -- `createOpenAI({ baseURL, apiKey })`
+ * is a supported factory in @ai-sdk/openai. It is left as guidance rather than
+ * a codemod because the change is one line the user makes deliberately, and a
+ * wrong automatic rewrite of a provider factory is worse than an accurate
+ * instruction.
+ */
+/**
+ * Vercel AI SDK call sites, TAGGED WITH WHICH PROVIDER PACKAGE each file uses.
+ *
+ * 2026-07-27 tick 819: the tag is new. The guidance printed for these files was
+ * hardcoded to @ai-sdk/openai, so a project importing @ai-sdk/anthropic was told
+ * to install and rewrite against a package it does not have.
+ */
+export function findVercelAiSites(root) {
+  const sites = [];
+  for (const file of walk(root)) {
+    if (extname(file) === ".py") continue;
+    let body;
+    try { body = readFileSync(file, "utf8"); } catch { continue; }
+    if (!/@ai-sdk\//.test(body)) continue;
+    // 2026-07-27 tick 831: factory files used to be dropped here with the
+    // comment "already re-pointable". Re-pointABLE is not re-pointED. The file
+    // is now kept and tagged, because `doctor` needs to see a createOpenAI call
+    // that never got a baseURL -- exactly what somebody who half-applied our
+    // own snippet ends up with. `init` filters on usesFactory below and so
+    // behaves as before.
+    const usesFactory = /createOpenAI|createAnthropic/.test(body);
+    const providers = [];
+    if (/@ai-sdk\/anthropic/.test(body)) providers.push("anthropic");
+    if (/@ai-sdk\/openai/.test(body)) providers.push("openai");
+    // A file importing some other @ai-sdk/* provider still gets the generic
+    // openai-compatible route, which is the honest fallback rather than
+    // silently naming a package the file never mentions.
+    sites.push({
+      file,
+      body,
+      providers: providers.length ? providers : ["openai"],
+      usesFactory,
+      alreadyPointed: pointsAtInferAll(body),
+    });
+  }
+  return sites;
+}
+
+/**
+ * 2026-07-27 tick 819. Two defects, both MEASURED against the real packages
+ * rather than assumed, because a snippet we print is a claim.
+ *
+ * 1. THE SNIPPET POINTED AT AN ENDPOINT WE DO NOT SERVE. In @ai-sdk/openai v4,
+ *    `openai("gpt-4o")` targets the Responses API. Measured by pointing a
+ *    factory at a recording server:
+ *
+ *      openai("gpt-4o")       -> POST /responses
+ *      openai.chat("gpt-4o")  -> POST /chat/completions
+ *
+ *    and against production: /v1/responses is 404, /v1/chat/completions is 401.
+ *    So anybody who followed the old snippet literally got a 404 from us. The
+ *    fix is `.chat(...)`, which is a CLI-side change; adding a /v1/responses
+ *    route would be a gateway feature and a much larger decision.
+ *
+ * 2. IT NAMED THE WRONG PACKAGE. Every file got @ai-sdk/openai advice, so an
+ *    @ai-sdk/anthropic project was told to import a package it does not have.
+ *    createAnthropic exists and honours baseURL (verified: it reached the
+ *    recording server rather than silently ignoring the option, which is the
+ *    llamaindex api_base trap from tick 811).
+ *
+ * BOTH providers take API_BASE, the /v1 URL. I had assumed anthropic would need
+ * the host root, as the raw @anthropic-ai/sdk does. It does not: this provider
+ * appends only "/messages", so the /v1 has to already be there. Measured, and
+ * the assumption was wrong.
+ */
+function printVercelAiGuidance(root, sites) {
+  console.log(`\n  ${c.bold("Vercel AI SDK usage")} found in ${sites.length} file(s):`);
+  for (const s of sites) {
+    console.log(`    - ${relative(root, s.file)} ${c.dim(`(${s.providers.join(" + ")})`)}`);
+  }
+  console.log(`  These were ${c.bold("NOT changed")}. The provider helper builds its own URL, so there`);
+  console.log(`  is no client constructor to re-point. Swap the helper for its factory form:`);
+  const wanted = [...new Set(sites.flatMap((s) => s.providers))];
+  for (const prov of wanted) {
+    const isAnthropic = prov === "anthropic";
+    const pkg = isAnthropic ? "@ai-sdk/anthropic" : "@ai-sdk/openai";
+    const factory = isAnthropic ? "createAnthropic" : "createOpenAI";
+    const local = isAnthropic ? "anthropic" : "openai";
+    // .chat() on the openai provider: the default export targets /responses,
+    // which this gateway does not serve. See the note above.
+    const call = isAnthropic ? `${local}("${FREE_MODEL}")` : `${local}.chat("${FREE_MODEL}")`;
+    console.log(c.dim(`    // import { ${local} } from "${pkg}";`));
+    console.log(c.cyan(`    import { ${factory} } from "${pkg}";`));
+    console.log(c.cyan(`    const ${local} = ${factory}({ baseURL: "${API_BASE}", apiKey: process.env.INFERALL_API_KEY });`));
+    console.log(c.cyan(`    model: ${call}   ${c.dim("// $0 in/out")}`));
+  }
+  console.log(`  Everything downstream keeps working, and you can now name any InferAll model.`);
+}
+
 function printGeminiGuidance(root, sites) {
   console.log(`\n  ${c.bold("Gemini SDK usage")} found in ${sites.length} file(s):`);
   for (const s of sites) console.log(`    - ${relative(root, s.file)}`);
@@ -271,14 +1733,32 @@ function printGeminiGuidance(root, sites) {
     console.log(c.cyan(`    const ai = new OpenAI({ baseURL: "${API_BASE}", apiKey: process.env.INFERALL_API_KEY });`));
     console.log(c.cyan(`    await ai.chat.completions.create({ model: "gemini/gemini-2.5-flash", messages });`));
   }
-  console.log(`  Same Gemini models, one ifu_ key, $0 markup — migrate at your own pace.`);
+  // ⛔ "$0 markup" CORRECTED 2026-09-03. Premium provider tokens (OpenAI,
+  //   Anthropic, Google) are NOT billed at the provider's rate: InferAll bills its
+  //   own published per-token rates, and applied-margin measures 1.30x across
+  //   those providers. The site published this correction on 2026-08-26 and said
+  //   "every live surface has been corrected" — the CLI is a live surface and was
+  //   missed, so the claim shipped on npm for another week.
+  console.log(`  Same Gemini models, one ifu_ key, one bill. Premium tokens bill at InferAll's published per-token rate; see ${BILLING_URL}. Migrate at your own pace.`);
+  // ⛔ "IT BILLS" AND "YOU CANNOT USE IT" ARE DIFFERENT FACTS, and only the second
+  //   one is actionable for a caller who has not paid. Gemini is a PREMIUM route
+  //   ($0.15/$0.60 per M), so a no-card trial key is REFUSED here rather than
+  //   charged — it routes to free NIM models only. Following this guidance on a
+  //   new key turns a working Gemini SDK into a 402.
+  //
+  //   ⭐ THE CAVEAT ALREADY EXISTED ONE SURFACE OVER. content/blog/
+  //   gemini-2-5-flash-api-free.mdx carries "Using a new key? A no-card trial key
+  //   routes to the free NIM models only" — the site said it, the CLI did not.
+  //   Same shape as the "$0 markup" correction directly above, which the site
+  //   shipped on 2026-08-26 while this file kept the wrong claim for another week.
+  console.log(`  ${c.yellow("~")} On a no-card trial key these premium routes are REFUSED, not billed: the trial covers the free NIM models only. Add $5 at ${BILLING_URL}, or start with model="nvidia/nemotron-3-ultra-550b-a55b" which is $0 and routes as written.`);
 }
 
 // AI-assisted patch for call sites the deterministic codemod can't handle.
 // Uses the user's own key against a $0 NIM model — the wizard dogfoods the
 // gateway. Returns the suggested full-file replacement, or null.
 async function aiSuggestPatch(key, site) {
-  const base = site.sdk === "Anthropic" ? ANTHROPIC_BASE : API_BASE;
+  const base = baseForSdk(site.sdk);
   const prompt = [
     {
       role: "user",
@@ -294,29 +1774,118 @@ async function aiSuggestPatch(key, site) {
   const { status, body } = await apiChat(key, prompt);
   if (status !== 200) return { status, patched: null };
   const text = body?.choices?.[0]?.message?.content;
-  if (!text || Math.abs(text.length - site.body.length) > site.body.length) return { status, patched: null };
-  return { status, patched: text.replace(/^```[a-z]*\n?/, "").replace(/\n?```\s*$/, "") };
+  // Strip fences BEFORE judging the text. The old order measured the fenced
+  // string and then wrote the unfenced one, so the thing checked was never the
+  // thing saved.
+  const cleaned = (text ?? "").replace(/^```[a-z]*\n?/, "").replace(/\n?```\s*$/, "");
+  if (!isPlausiblePatch(cleaned, site, base)) return { status, patched: null };
+  return { status, patched: cleaned };
+}
+
+/**
+ * Would this model output be a sane replacement for the whole file?
+ *
+ * WHY THIS IS STRICT (2026-07-31, tick 880)
+ * ----------------------------------------
+ * The previous check was:
+ *
+ *     Math.abs(text.length - site.body.length) > site.body.length
+ *
+ * For an original of length L that accepts ANY reply from 1 to 2L characters.
+ * Its failing set is empty in the only direction that destroys data. Measured:
+ * a two-character reply overwrote a 250-character main.py, and the wizard then
+ * printed a tick and "Done. Your project is wired to InferAll."
+ *
+ * The replies that actually occur in the short direction are refusals, one-line
+ * apologies and responses truncated by max_tokens. All of them passed. This
+ * function exists so those fail CLOSED: the site is reported as unchanged,
+ * which the caller already accounts for and which suppresses the "wired"
+ * closing line.
+ *
+ * A patch is only accepted if it did the job it was asked to do, which is a
+ * stronger and more honest test than any length band on its own.
+ */
+export function isPlausiblePatch(text, site, base) {
+  if (!text || !text.trim()) return false;
+  const orig = site.body ?? "";
+  // A whole-file rewrite should be about the same size. Anything much shorter
+  // is a refusal or a truncation, not a rewrite.
+  if (orig.length > 0 && text.length < orig.length * 0.6) return false;
+  if (orig.length > 0 && text.length > orig.length * 2) return false;
+  // 2026-07-31 tick 881: a CHARACTER ratio cannot tell a whole file from a
+  // single line once the file is short. Measured end to end: a one-line reply
+  // containing every marker replaced a four-line file, because 105 chars is 80%
+  // of 130 and so cleared the 0.6 bound. The tick 880 test for this case passed
+  // only because it used a longer original, where the same fragment fell below
+  // the ratio. Line count does not decay with file size, so it catches the
+  // fragment at any scale. Allow one line of slack for a dropped blank.
+  const lines = (s) => s.split("\n").filter((l) => l.trim() !== "").length;
+  const origLines = lines(orig);
+  if (origLines > 0 && lines(text) < origLines - 1) return false;
+  // 2026-07-31 tick 884: the line floor above has its OWN degenerate region,
+  // and it is small by construction, which is exactly where a casual test never
+  // looks. At origLines = 2 the floor is 1, so a one-line reply satisfies it,
+  // and the character ratio cannot help because the fragment is often LONGER
+  // than the two lines it replaces (measured: ratio 1.12). A two-line client
+  // module is an ordinary shape:
+  //
+  //     import OpenAI from "openai";
+  //     export default new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+  //
+  // and the fragment silently deletes the import.
+  //
+  // So stop sampling the quantity and test the INVARIANT instead. The model is
+  // told to change the client constructor and NOTHING else, therefore every
+  // import the original had must survive. That holds at any file size and it
+  // disagrees the moment it is wrong, where a size comparison agrees by luck
+  // most of the time.
+  const importsOf = (s) =>
+    s.split("\n").map((l) => l.trim()).filter((l) => /^(import|from)\s/.test(l));
+  for (const line of importsOf(orig)) {
+    if (!text.includes(line)) return false;
+  }
+  // It must contain what it was told to add, or it changed nothing that matters
+  // and there is no reason to overwrite the file with it.
+  if (!text.includes("INFERALL_API_KEY")) return false;
+  if (base && !text.includes(base)) return false;
+  // And it must still be recognisably the same file: the SDK it was built from
+  // has to survive. Catches "here is the rewritten file:" style prose.
+  if (site.sdk && !text.includes(site.sdk)) return false;
+  return true;
 }
 
 // ---------- fresh-install example ----------
 
-function writeExample(root, kind) {
-  if (kind === "python") {
-    const p = join(root, "inferall_hello.py");
-    if (existsSync(p)) return null;
-    writeFileSync(
-      p,
-      `"""InferAll hello — run: python inferall_hello.py (pip install inferall-ai)"""\nfrom inferall import Inferall\n\nai = Inferall()  # reads INFERALL_API_KEY from the environment\nprint(ai.text("Explain InferAll in one sentence."))\n`
-    );
-    return p;
-  }
-  const p = join(root, "inferall-hello.mjs");
-  if (existsSync(p)) return null;
-  writeFileSync(
-    p,
-    `// InferAll hello — run: node --env-file=.env inferall-hello.mjs\nconst res = await fetch("${API_BASE}/chat/completions", {\n  method: "POST",\n  headers: {\n    Authorization: \`Bearer \${process.env.INFERALL_API_KEY}\`,\n    "Content-Type": "application/json",\n  },\n  body: JSON.stringify({\n    model: "${FREE_MODEL}",\n    messages: [{ role: "user", content: "Explain InferAll in one sentence." }],\n  }),\n});\nconsole.log((await res.json()).choices?.[0]?.message?.content ?? (await res.text()));\n`
-  );
-  return p;
+/**
+ * 2026-07-28 tick 837: these two writes were the last bare ones in the wizard.
+ *
+ * Tick 836 guarded .env, .env.example and .gitignore, and MEASURED against a
+ * read-only working directory those three now degrade correctly -- and then
+ * this function threw one line later:
+ *
+ *     ✗ could not write .env: permission denied
+ *     ✗ could not write .env.example: permission denied
+ *     ✗ could not update .gitignore: permission denied
+ *     ✗ EACCES: permission denied, open '/…/inferall-hello.mjs'
+ *
+ * Three honest lines followed by the exact raw errno they replaced. I guarded
+ * the writers I happened to be looking at rather than enumerating them, which
+ * is the same mistake as tick 835 (parse vs read) one surface further on.
+ *
+ * Returns { path, problem }: path when written, problem when it could not be.
+ */
+export function writeExample(root, kind) {
+  const p = join(root, kind === "python" ? "inferall_hello.py" : "inferall-hello.mjs");
+  if (existsSync(p)) return { path: null, problem: null };   // never clobber theirs
+  const body = kind === "python"
+    ? `"""InferAll hello. Run: python inferall_hello.py (pip install inferall-ai)"""\nfrom inferall import Inferall\n\nai = Inferall()  # reads INFERALL_API_KEY from the environment\nprint(ai.text("Explain InferAll in one sentence."))\n`
+    : `// InferAll hello. Run: node --env-file=.env inferall-hello.mjs\nconst res = await fetch("${API_BASE}/chat/completions", {\n  method: "POST",\n  headers: {\n    Authorization: \`Bearer \${process.env.INFERALL_API_KEY}\`,\n    "Content-Type": "application/json",\n  },\n  body: JSON.stringify({\n    model: "${FREE_MODEL}",\n    messages: [{ role: "user", content: "Explain InferAll in one sentence." }],\n  }),\n});\nconsole.log((await res.json()).choices?.[0]?.message?.content ?? (await res.text()));\n`;
+  try {
+    writeFileSync(p, body);
+    return { path: p, problem: null };
+  } catch (err) {
+    return { path: null, problem: describeFsError(err, p, "write") };
+  }
 }
 
 // ---------- models ----------
@@ -334,13 +1903,32 @@ function priceLabel(p) {
 }
 
 async function modelsCmd() {
-  const res = await fetch(`${ANTHROPIC_BASE}/ai/v1/models`);
+  const res = await fetch(`${ANTHROPIC_BASE}/ai/v1/models`, { signal: timeoutSignal() });
   if (!res.ok) {
-    console.log(`${c.red("✗")} couldn't fetch the model list (HTTP ${res.status})`);
+    for (const line of httpFailureLines(res.status)) console.log(line);
+    rl.close();
+    exit(1);
+  }
+  const parsed = await readJsonBody(res);
+  if (parsed.parseFailed) {
+    for (const line of nonJsonLines(parsed)) console.log(line);
+    rl.close();
+    exit(1);
+  }
+  const map = parsed.body;
+  // 2026-07-31 tick 886: valid JSON of the WRONG SHAPE. Measured against a stub
+  // returning an ARRAY: Object.entries gives ["0", "gpt-4o"], p is a string, and
+  // the renderer died on `Cannot read properties of undefined (reading
+  // 'padEnd')`. The catalog is an object of {id: pricing}; anything else is a
+  // different service answering at this URL, which is what a mistyped
+  // INFERALL_API_BASE looks like.
+  if (!isCatalogShape(map)) {
+    console.log(`${c.red("✗")} the gateway returned JSON, but not a model catalog`);
+    console.log(`  Expected an object of model ids to pricing. Got ${Array.isArray(map) ? "an array" : typeof map}.`);
+    console.log(`  Check ${c.cyan("INFERALL_API_BASE")}: something else is answering at that address.`);
     rl.close();
     exit(1);
   }
-  const map = await res.json();
   let rows = Object.entries(map).map(([id, p]) => ({
     id,
     type: p.type,
@@ -362,53 +1950,204 @@ async function modelsCmd() {
     console.log(`${r.id.padEnd(w)}${r.type.padEnd(12)}${price}`);
   }
   const freeCount = Object.values(map).filter((p) => p.type === "token" && !p.inputPerM && !p.outputPerM).length;
-  console.log(`\n${Object.keys(map).length} models — ${c.green(`${freeCount} at $0`)} (NVIDIA NIM). Use any with your ifu_ key.\n`);
+  console.log(`\n${Object.keys(map).length} models, ${c.green(`${freeCount} at $0`)} (NVIDIA NIM). Use any with your InferAll key.\n`);
   rl.close();
 }
 
-// ---------- status ----------
-
-// GET /ai/v1/key/status (host root, API-key auth) — tier, trial counter,
-// balance, savings. Answers "did my payment land?" without opening a browser.
-async function statusCmd() {
-  let key = env.INFERALL_API_KEY || flagValue("key") || "";
-  const envPath = join(cwd(), ".env");
-  if (!key && existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^INFERALL_API_KEY=(.+)$/m);
-    if (m) key = m[1].trim();
+// Resolve the API key from --key, env, or .env (in that order); exit if none.
+function resolveKey() {
+  let key = flagValue("key") || env.INFERALL_API_KEY || "";
+  if (!key) {
+    // 2026-07-27 tick 834: shared parser (quotes, `export`, spaces, comments).
+    // 2026-07-27 tick 835: shared READER too, so an unreadable .env is named
+    // rather than escaping as a Node errno.
+    const { text, code } = readEnvText(cwd());
+    const problem = envReadProblem(code);
+    if (problem) {
+      console.log(`${c.red("✗")} ${problem}`);
+      console.log(`  ${c.dim(join(cwd(), ".env"))}`);
+      console.log(`  Fix it, or pass the key directly: ${c.bold("--key ifu_...")}`);
+      rl.close();
+      exit(1);
+    }
+    key = parseEnvKey(text) || "";
   }
   if (!key) {
-    console.log(`${c.red("✗")} No key in INFERALL_API_KEY or .env — run ${c.bold("npx @inferall/cli init")}`);
+    console.log(`${c.red("✗")} No key in INFERALL_API_KEY or .env. Run ${c.bold("npx @inferall/cli init")}`);
+    rl.close();
+    exit(1);
+  }
+  return key;
+}
+
+// ---------- chat ----------
+
+// One-shot chat: `inferall chat "prompt"` (or piped stdin). The fastest way to
+// confirm a key works and see a real response — dogfoods the gateway on a $0
+// NIM model by default (a taster's first "it works" moment without writing code).
+async function chatCmd() {
+  const key = resolveKey();
+  const model = flagValue("model") || FREE_MODEL;
+  // Every flag that takes a VALUE must be listed here, or its value is
+  // silently treated as part of the prompt. Adding --max-tokens without this
+  // would have made `chat "hi" --max-tokens 900` send the prompt "hi 900".
+  const VALUE_FLAGS = ["--key", "--model", "--max-tokens"];
+  let prompt = args.filter((a, idx) => idx > 0 && !a.startsWith("-") && !VALUE_FLAGS.includes(args[idx - 1])).join(" ").trim();
+  if (!prompt && !stdin.isTTY) {
+    prompt = readFileSync(0, "utf8").trim(); // piped stdin
+  }
+  if (!prompt) {
+    console.log(`Usage: npx @inferall/cli chat "your prompt"   ${c.dim("(or pipe: echo \"hi\" | npx @inferall/cli chat)")}`);
     rl.close();
     exit(1);
   }
+  // Parsed here rather than inside apiChat so the flag is visible where the
+  // error message that recommends it also lives.
+  const rawMax = flagValue("max-tokens");
+  const parsedMax = rawMax === undefined ? 512 : parseInt(rawMax, 10);
+  const maxTokens = Number.isFinite(parsedMax) && parsedMax > 0 ? parsedMax : 512;
+  const reply = await apiChat(key, [{ role: "user", content: prompt }], model, maxTokens);
+  const { status, body } = reply;
+  // 2026-07-27 tick 833: a body we could not parse is a FAILED call whatever
+  // the status line said. Measured: a 200 whose JSON was truncated mid-stream
+  // (a proxy cutting the response) printed `{}` and exited 0, so a script
+  // wrapping this command saw success and an empty answer. Reporting success
+  // for a call that produced nothing is the rung of the ladder this product
+  // keeps landing on, and it is worth its own branch before the status checks.
+  if (reply.parseFailed) {
+    console.log(`${c.red("✗")} ${nonJsonSummary(reply)}`);
+    console.log(`  ${c.dim(`HTTP ${status}. Nothing usable came back, so this call did not succeed.`)}`);
+    if (status >= 500 || status === 502 || status === 503) {
+      console.log(`  That is an infrastructure error, not a problem with your key. Retry shortly.`);
+    }
+    rl.close();
+    exit(1);
+  }
+  if (status === 200) {
+    const choice = body?.choices?.[0];
+    const text = choice?.message?.content;
+    if (text) {
+      console.log(text);
+      /*
+       * Printed to STDERR, deliberately. `chat` is piped: the usage line above
+       * documents `echo "hi" | npx @inferall/cli chat`, and people redirect the
+       * answer into files and other commands. A counter on stdout would corrupt
+       * every one of those, which is a worse bug than the blindness it fixes.
+       * stderr reaches a human at a terminal and stays out of the pipe.
+       */
+      const countdown = trialCountdownLine(reply.trialUsage);
+      if (countdown) process.stderr.write(`${countdown}\n`);
+    } else if (choice?.finish_reason === "length") {
+      // 2026-07-26 tick 817. Reasoning models (nemotron and friends) spend the
+      // token budget on reasoning_content and return content: null with
+      // finish_reason "length". Measured at tick 811: nemotron at max_tokens=64
+      // returns null, at 256 it answers. The old code fell through to
+      // JSON.stringify(body), so a user who asked a question got a JSON blob
+      // back with no hint that the fix is simply a bigger budget.
+      console.log(c.yellow("The model used its whole token budget before answering."));
+      console.log(`  ${c.dim("Reasoning models spend the budget thinking first. Retry with a larger")} ${c.bold("--max-tokens")}${c.dim(", or use a non-reasoning model such as")} ${c.bold(FREE_MODEL)}${c.dim(".")}`);
+      rl.close();
+      exit(1);
+    } else {
+      // 2026-07-27 tick 833: this printed a JSON blob and then fell out of the
+      // function, so the process exited 0. A 200 carrying no answer is still a
+      // call that produced nothing, and a caller piping this into anything had
+      // no way to tell. The blob is kept -- it is the only diagnostic there is
+      // -- but it is labelled and the exit code now says what happened.
+      console.log(`${c.yellow("~")} the gateway returned 200 with no answer in it:`);
+      console.log(`  ${JSON.stringify(body).slice(0, 400)}`);
+      rl.close();
+      exit(1);
+    }
+  } else {
+    // 2026-07-26 tick 817: SHOW THE SERVER'S OWN MESSAGE.
+    //
+    // The gateway writes careful, model-aware 402 and 429 copy (ticks 812 and
+    // 815 were spent making it accurate) and this command threw it away. On 402
+    // it printed "your free allowance is used up or the account isn't activated
+    // yet", which conflates two different states and is simply WRONG for a user
+    // who was never activated: nothing of theirs is used up. The accurate
+    // sentence was in the response we discarded. On 429 it dumped raw JSON at
+    // the user, so the gateway's readable "retry in 42s" arrived wrapped in
+    // braces.
+    //
+    // Both are the same mistake: the client second-guessing a server that knows
+    // more than it does.
+    const serverMsg = body?.error?.message || body?.message;
+    console.log(`${status === 402 ? c.yellow("402") : c.red(`HTTP ${status}`)}: ${serverMsg || JSON.stringify(body).slice(0, 300)}`);
+    // Keep the pointer to `status`, which is genuinely useful and not something
+    // the server can know to suggest. Only for billing states, where "where do
+    // I stand" is the actual next question.
+    if (status === 402) {
+      console.log(`  ${c.dim("check your account:")} ${c.bold("npx @inferall/cli status")}`);
+    }
+    rl.close();
+    exit(1);
+  }
+  rl.close();
+}
+
+// ---------- status ----------
+
+// GET /ai/v1/key/status (host root, API-key auth) — tier, trial counter,
+// balance, savings. Answers "did my payment land?" without opening a browser.
+async function statusCmd() {
+  const key = resolveKey();
   const res = await fetch(`${ANTHROPIC_BASE}/ai/v1/key/status`, {
+    signal: timeoutSignal(),
     headers: { Authorization: `Bearer ${key}` },
   });
   if (!res.ok) {
-    console.log(`${c.red("✗")} status check failed (HTTP ${res.status}) — check the key at ${KEYS_URL}`);
+    for (const line of httpFailureLines(res.status)) console.log(line);
+    rl.close();
+    exit(1);
+  }
+  const parsedStatus = await readJsonBody(res);
+  if (parsedStatus.parseFailed) {
+    for (const line of nonJsonLines(parsedStatus)) console.log(line);
     rl.close();
     exit(1);
   }
-  const s = await res.json();
+  const s = parsedStatus.body;
   console.log(`\n${c.bold("InferAll account status")} ${c.dim(`(key ${key.slice(0, 8)}…)`)}\n`);
   if (s.project) {
-    console.log(`  tier: ${c.cyan(s.tier)} ${c.dim("(project key — billed separately, no trial counter)")}\n`);
+    console.log(`  tier: ${c.cyan(s.tier)} ${c.dim("(project key, billed separately, no trial counter)")}\n`);
     rl.close();
     return;
   }
   const active = s.has_paid_successfully;
   console.log(`  tier:      ${c.cyan(s.tier)}`);
   console.log(`  activated: ${active ? c.green("yes") : c.yellow("not yet")}${!active && s.has_card ? c.dim(" (checkout started, not settled)") : ""}`);
-  console.log(`  balance:   ${s.balance_usd > 0 ? c.green(`$${s.balance_usd.toFixed(2)}`) : `$${s.balance_usd.toFixed(2)}`}`);
+  // 2026-07-31 tick 882: this was a bare s.balance_usd.toFixed(2), so a
+  // response missing the field killed the command with a raw
+  // "Cannot read properties of undefined (reading 'toFixed')". The CLI is
+  // published independently of the gateway, so an older client meeting a
+  // renamed or dropped field is a version-skew case, not a hypothetical. Say
+  // the number is unavailable rather than throwing Node's words at the user.
+  const bal = typeof s.balance_usd === "number" && Number.isFinite(s.balance_usd) ? s.balance_usd : null;
+  console.log(`  balance:   ${bal === null ? c.yellow("unavailable (gateway did not report it)") : bal > 0 ? c.green(`$${bal.toFixed(2)}`) : `$${bal.toFixed(2)}`}`);
   if (s.trial) console.log(`  trial:     ${s.trial.remaining}/${s.trial.cap} calls remaining`);
   const sv = s.savings_7d;
   if (sv && (sv.vs_gpt4o_mini_usd > 0 || sv.vs_claude_sonnet_usd > 0)) {
     console.log(`  saved 7d:  $${sv.vs_gpt4o_mini_usd.toFixed(2)} vs GPT-4o-mini · $${sv.vs_claude_sonnet_usd.toFixed(2)} vs Claude Sonnet`);
   }
   if (!active) {
-    console.log(`\n  Activate with the one-time ${c.bold("$5 starter pack")} (becomes spendable balance):`);
-    console.log(`  ${c.cyan(BILLING_URL)}`);
+    // 2026-07-25: `active` is has_paid_successfully, so before this branch was
+    // split EVERY unpaid user got told to buy the $5 pack -- including someone
+    // holding 5 unused free calls. That is the same mistake the /keys page made
+    // ("your calls will 402 until you pay") at the moment activation is decided.
+    // trial.active comes from the gateway and means "this key can call RIGHT
+    // NOW", so the CTA no longer has to be inferred from payment state.
+    if (s.trial?.active) {
+      const n = s.trial.remaining;
+      console.log(`\n  ${c.green("You can call right now")}: ${c.bold(`${n} free request${n === 1 ? "" : "s"}`)} on 10+ open models, no card needed:`);
+      console.log(`  ${c.cyan('npx @inferall/cli chat "hello"')}`);
+      console.log(c.dim(`  When those run out, the one-time $5 starter pack keeps you going (it becomes`));
+      console.log(c.dim(`  spendable balance, not a fee): ${BILLING_URL}`));
+    } else {
+      console.log(`\n  Activate with the one-time ${c.bold("$5 starter pack")} (becomes spendable balance):`);
+      console.log(`  ${c.cyan(BILLING_URL)}`);
+    }
   }
   console.log("");
   rl.close();
@@ -417,51 +2156,189 @@ async function statusCmd() {
 // ---------- doctor ----------
 
 async function doctor() {
-  console.log(`\n${c.bold("InferAll doctor")} ${c.dim(`— checks your setup against ${API_BASE}`)}\n`);
+  console.log(`\n${c.bold("InferAll doctor")} ${c.dim(`checks your setup against ${API_BASE}`)}\n`);
   const root = cwd();
   let ok = true;
 
   // 1. key present
   let key = env.INFERALL_API_KEY || "";
   const envPath = join(root, ".env");
-  if (!key && existsSync(envPath)) {
-    const m = readFileSync(envPath, "utf8").match(/^INFERALL_API_KEY=(.+)$/m);
-    if (m) key = m[1].trim();
+  if (!key) {
+    // 2026-07-27 tick 834: shared parser (quotes, `export`, spaces, comments).
+    // 2026-07-27 tick 835: shared reader. doctor is the command people run to
+    // find out what is wrong, so "EISDIR: illegal operation on a directory,
+    // read" was the least useful thing it could have said: it names no file, no
+    // cause and no next step.
+    const { text, code } = readEnvText(root);
+    const problem = envReadProblem(code);
+    if (problem) {
+      console.log(`  ${c.red("✗")} ${problem}`);
+      console.log(`    ${c.dim(envPath)}`);
+      console.log(`    Fix that file, or set ${c.cyan("INFERALL_API_KEY")} in your environment.`);
+      rl.close();
+      exit(1);
+    }
+    key = parseEnvKey(text) || "";
   }
   if (!key) {
-    console.log(`  ${c.red("✗")} INFERALL_API_KEY not found in environment or .env — run ${c.bold("npx @inferall/cli init")}`);
+    // 2026-07-29 tick 850: say WHERE we looked, and whether a parent directory
+    // already has one. The old line reported absence with no scope, then sent
+    // the user to `init`, which in a monorepo writes a second key beside the
+    // first. Naming the location turns a wrong instruction into a correct one.
+    const ancestor = findAncestorEnvKey(root);
+    console.log(`  ${c.red("✗")} INFERALL_API_KEY not in the environment, and no key in ${c.bold(".env")} here`);
+    console.log(`    ${c.dim(`looked in ${root}`)}`);
+    if (ancestor) {
+      const rel = relative(root, ancestor.dir) || ".";
+      console.log(`  ${c.yellow("~")} a parent directory already has one: ${c.bold(join(rel, ".env"))}`);
+      console.log(`    Run this from there, or copy that key into this package.`);
+      console.log(`    ${c.bold("Do not run init here")} unless you want a second key for the same repo.`);
+    } else {
+      console.log(`    Run ${c.bold("npx @inferall/cli init")}`);
+    }
     rl.close();
     exit(1);
   }
   console.log(`  ${c.green("✓")} key found (${key.slice(0, 8)}…)`);
-  if (!key.startsWith("ifu_")) {
-    console.log(`  ${c.yellow("~")} key doesn't have the ifu_ prefix — is this an InferAll key?`);
+  // 2026-07-25: this used to warn (and set ok=false) for ANY key without an
+  // ifu_ prefix. The gateway mints ifu_ but auth.ts also accepts ifa_,
+  // kr_user_ and kr_proj_ ("Legacy kr_user_... keys remain valid"), so a user
+  // with a working key was told their setup "needs attention" — and then, two
+  // lines later, told "key accepted by gateway". doctor contradicted itself.
+  //
+  // The gateway check below is authoritative; a client-side prefix guess is a
+  // second copy of a rule enforced elsewhere. Only flag keys that are
+  // recognisably ANOTHER provider's, where a bare 401 would not explain why.
+  const foreign =
+    key.startsWith("sk-ant-") ? "an Anthropic key (sk-ant-…)" :
+    key.startsWith("sk-or-") ? "an OpenRouter key (sk-or-…)" :
+    key.startsWith("sk-") ? "an OpenAI key (sk-…)" :
+    key.startsWith("AIzaSy") ? "a Google AI Studio key (AIzaSy…)" : null;
+  if (foreign) {
+    console.log(`  ${c.red("✗")} that looks like ${foreign}, not an InferAll key. Mint one at ${KEYS_URL}`);
     ok = false;
   }
 
   // 2. .env hygiene
-  const giPath = join(root, ".gitignore");
-  const giCovers =
-    existsSync(giPath) &&
-    readFileSync(giPath, "utf8").split("\n").some((l) => [".env", ".env*", "*.env"].includes(l.trim()));
-  if (existsSync(envPath) && !giCovers) {
-    console.log(`  ${c.yellow("~")} .env exists but is NOT gitignored — your key could be committed`);
+  //
+  // 2026-07-27 tick 825: this asked ONE question (is .env gitignored?) and
+  // then reported on a broader one (".env hygiene ok"). Measured: a .env that
+  // is COMMITTED TO GIT, with a live key in it, got
+  //
+  //     ✓ .env hygiene ok
+  //
+  // because a tracked file is usually also listed in .gitignore, and gitignore
+  // has no effect on tracked files. tick 821 built envIsGitTracked() for the
+  // same check in `init` and this copy never got it: the eighth time in a week
+  // one fact lived in two places and went stale in one of them.
+  //
+  // It is worse here than in init. People run `doctor` to ASK whether their
+  // setup is safe, so a green tick from it is the strongest false assurance
+  // the tool can give.
+  const gi = gitignoreCoversEnv(root);
+  const giCovers = gi.covers === true;
+  const envExists = existsSync(envPath);
+  const trackStatus = envExists ? gitTrackStatus(root) : "untracked";
+  if (trackStatus === "tracked") {
+    // Checked FIRST: for a tracked file the gitignore answer is irrelevant,
+    // and reporting the ignore status here would soften a live exposure.
+    console.log(`  ${c.red("✗")} .env is ${c.bold("tracked by git")} and holds your key. Untrack it: ${c.cyan("git rm --cached .env")}`);
+    ok = false;
+  } else if (trackStatus === "unknown") {
+    // 2026-07-28 tick 839: git could not be run, so this check did not happen.
+    // Reporting "hygiene ok" here would be the tick-825 false all-clear again,
+    // reached through a different door: a committed .env in a container without
+    // git answered exactly the same as a safe one.
+    console.log(`  ${c.yellow("~")} could not check whether .env is tracked by git (git is not available here)`);
+    console.log(`    If this project is a git repository, confirm yourself: ${c.cyan("git ls-files --error-unmatch .env")}`);
+    ok = false;
+  } else if (envExists && gi.covers === null) {
+    // Ordered AFTER the tracked check and BEFORE the not-ignored one, because
+    // "could not read .gitignore" must not be reported as "not ignored". The
+    // key may well be protected; we cannot say. Saying either would be a
+    // confident answer to a question this run did not get to ask.
+    console.log(`  ${c.yellow("~")} ${gi.problem}, so .env protection could not be checked`);
+    console.log(`    Check it yourself: ${c.cyan("git check-ignore -v .env")}`);
+    ok = false;
+  } else if (envExists && !giCovers) {
+    console.log(`  ${c.yellow("~")} .env exists but is NOT gitignored, so your key could be committed`);
     ok = false;
   } else {
     console.log(`  ${c.green("✓")} .env hygiene ok`);
   }
 
-  // 3. key valid against the gateway
-  const models = await apiGet("/models", key).catch(() => null);
-  if (!models || (models.status !== 200 && models.status !== 402)) {
-    console.log(`  ${c.red("✗")} key rejected by gateway (${models ? `HTTP ${models.status}` : "network error"}) — check ${KEYS_URL}`);
+  // 3. key valid against the gateway.
+  // MUST hit an authenticated endpoint. /v1/models is public — it answers 200
+  // with no key at all — so checking it made this line ("key accepted by
+  // gateway") true for any string, in the very tool people run BECAUSE their
+  // key isn't working.
+  const models = await fetch(`${ANTHROPIC_BASE}/ai/v1/key/status`, {
+    signal: timeoutSignal(),
+    headers: { Authorization: `Bearer ${key}` },
+  }).then((r) => readJsonBody(r)).catch((e) => ({ netErr: e }));
+  // 2026-07-27 tick 832: an unreachable gateway used to be reported as
+  // "key rejected by gateway (network error). Check <keys page>". The key was
+  // never checked, and minting a replacement cannot reach a host that is down.
+  // doctor exists to diagnose, so a confident wrong cause is the failure that
+  // costs the most here.
+  if (models.netErr) {
+    for (const line of unreachableLines(models.netErr)) console.log(`  ${line}`);
+    rl.close();
+    exit(1);
+  }
+  if (models.status !== 200 && models.status !== 402) {
+    for (const line of httpFailureLines(models.status)) console.log(`  ${line}`);
+    rl.close();
+    exit(1);
+  }
+  if (models.parseFailed) {
+    // A login page is served with 200, so the status check above passes it.
+    for (const line of nonJsonLines(models, "  ")) console.log(line);
     rl.close();
     exit(1);
   }
   console.log(`  ${c.green("✓")} key accepted by gateway`);
 
+  /*
+   * TRIAL BALANCE, 2026-08-03 tick 927.
+   *
+   * `status` has always printed this; `doctor` never did, even though it
+   * already fetches the very response that carries it (the /ai/v1/key/status
+   * call above). So the command people run BECAUSE something is wrong was the
+   * one command that could not tell them the most common reason it is wrong.
+   *
+   * MEASURED, server-side and synthetic-filtered, since the micro-trial:
+   * 9 real users have hit the trial ceiling, 9 of 9 had made successful calls
+   * first (the cap only fires after five), and SEVEN OF THE NINE burned all
+   * five within 0.0 to 0.3 hours of their first call. Six of them arrived
+   * through real tooling, including claude-cli and opencode, which consume
+   * five calls inside a single task. Nobody saw a counter on the way down.
+   *
+   * A used-up trial is not a fault, so it prints as information rather than as
+   * a failure and deliberately does NOT set ok = false. doctor exits non-zero
+   * for things the user can fix by editing something; "you spent your trial"
+   * is a true, correct state of a working key.
+   *
+   * The zero case gets its own line because that is the population this exists
+   * for, and because "0/5 remaining" scans as a number rather than as a cause.
+   */
+  const trial = models.body?.trial;
+  if (trial && typeof trial.remaining === "number" && typeof trial.cap === "number") {
+    if (trial.remaining > 0) {
+      console.log(`  ${c.dim("·")} trial: ${trial.remaining}/${trial.cap} free calls remaining`);
+    } else {
+      console.log(`  ${c.yellow("~")} trial: 0/${trial.cap} free calls remaining. This key works; the free allowance is spent.`);
+      console.log(`    ${c.dim("Activate at https://inferall.ai/billing to keep calling.")}`);
+    }
+  }
+
   // 4. call-site wiring
-  const sites = findCallSites(root);
+  // 2026-07-30 tick 854: the walk can stop early (depth and size caps), and
+  // both claims below are about the WHOLE project. Saying "no constructors
+  // found" over a tree we did not finish reading is the tick 830 false
+  // all-clear in a new place.
+  const cappedDoc = [];
+  const sites = findCallSites(root, cappedDoc);
   const pointed = sites.filter((s) => s.alreadyPointed).length;
   const unpointed = sites.length - pointed;
   if (sites.length === 0) {
@@ -469,14 +2346,81 @@ async function doctor() {
   } else if (unpointed === 0) {
     console.log(`  ${c.green("✓")} all ${sites.length} client constructor site(s) point at InferAll`);
   } else {
-    console.log(`  ${c.yellow("~")} ${unpointed} of ${sites.length} client site(s) NOT pointed at InferAll — run ${c.bold("npx @inferall/cli init")}`);
+    console.log(`  ${c.yellow("~")} ${unpointed} of ${sites.length} client site(s) NOT pointed at InferAll. Run ${c.bold("npx @inferall/cli init")}`);
+    ok = false;
+  }
+  // A count is only as good as the scan behind it. Printed AFTER the verdict so
+  // it qualifies whatever was just claimed, including the "none found" case.
+  const capDoc = cappedSummary(cappedDoc);
+  if (capDoc) {
+    console.log(`  ${c.yellow("~")} ${capDoc}, so this count may be incomplete`);
+    ok = false;
+  }
+
+  // 4a. Notebook cells.
+  //
+  // 2026-07-27 tick 830: doctor never looked inside a .ipynb. On a
+  // notebook-only project it printed
+  //
+  //     · no OpenAI/Anthropic client constructors found in this project
+  //     All checks passed.
+  //
+  // and exited 0, over a notebook calling OpenAI directly with a live key. The
+  // user's traffic was going to OpenAI, billed by OpenAI, and the tool they ran
+  // to check their InferAll setup told them it was fine.
+  //
+  // This is tick 816 reproduced one command over: t816 taught `init` about
+  // notebooks and `doctor` never got it. Twelfth time one fact lived in two
+  // places and went stale in one. Same severity argument as t825 -- doctor is
+  // the tool people run to ASK whether they are set up, so its green tick is
+  // the strongest false assurance we can hand out.
+  //
+  // Reported, never patched: rewriting a notebook reformats the whole file
+  // (t816). doctor's job here is to say the cell is not wired, not to fix it.
+  const nbSites = findNotebookSites(root);
+  const nbUnpointed = nbSites.flatMap((s) => s.hits.filter((h) => !h.alreadyPointed).map((h) => ({ file: s.file, ...h })));
+  if (nbUnpointed.length) {
+    console.log(`  ${c.yellow("~")} ${nbUnpointed.length} notebook cell(s) still call the provider directly:`);
+    for (const h of nbUnpointed) {
+      console.log(`      ${relative(root, h.file)} ${c.dim(`cell ${h.index} (${h.sdk})`)}`);
+    }
+    console.log(`    Notebooks are never rewritten automatically. Add to the client: ${c.cyan(`base_url="${API_BASE}"`)}`);
+    ok = false;
+  } else if (nbSites.length) {
+    const cells = nbSites.reduce((n, s) => n + s.hits.length, 0);
+    console.log(`  ${c.green("✓")} all ${cells} notebook cell(s) point at InferAll`);
+  }
+
+  // 4c. Vercel AI SDK sites.
+  //
+  // 2026-07-27 tick 831: doctor never called findVercelAiSites, so a Next.js
+  // route doing `openai("gpt-4o")` from @ai-sdk/openai produced
+  //
+  //     · no OpenAI/Anthropic client constructors found in this project
+  //     All checks passed.                                    (exit 0)
+  //
+  // while every request went to OpenAI and was billed by OpenAI. `init` has
+  // handled this surface since tick 804 and doctor never got it. Same shape as
+  // the notebook hole fixed yesterday in tick 830, one surface over, and the
+  // thirteenth time one fact lived in two places.
+  //
+  // Found by the command-x-surface sweep rather than by stumbling into it,
+  // which is the whole reason that sweep is now a standing step.
+  const vSites = findVercelAiSites(root).filter((s) => !s.alreadyPointed);
+  if (vSites.length) {
+    console.log(`  ${c.yellow("~")} ${vSites.length} Vercel AI SDK file(s) still route to the provider directly:`);
+    for (const s of vSites) {
+      const why = s.usesFactory ? "factory without an InferAll baseURL" : `bare ${s.providers[0]}() import`;
+      console.log(`      ${relative(root, s.file)} ${c.dim(`(${why})`)}`);
+    }
+    console.log(`    Run ${c.bold("npx @inferall/cli init")} for the exact snippet.`);
     ok = false;
   }
 
   // 4b. Gemini SDK sites — different protocol, can't be re-pointed
   const gSites = findGeminiSites(root);
   if (gSites.length) {
-    console.log(`  ${c.yellow("~")} ${gSites.length} Gemini SDK site(s) bypass InferAll (different protocol) — use the OpenAI-compat endpoint with model ${c.bold("gemini/gemini-2.5-flash")}; run ${c.bold("npx @inferall/cli init")} for the exact snippet`);
+    console.log(`  ${c.yellow("~")} ${gSites.length} Gemini SDK site(s) bypass InferAll (different protocol). Use the OpenAI-compat endpoint with model ${c.bold("gemini/gemini-2.5-flash")}; run ${c.bold("npx @inferall/cli init")} for the exact snippet`);
     ok = false;
   }
 
@@ -503,26 +2447,44 @@ async function doctor() {
 
 async function main() {
   if (flag("version") || cmd === "version") {
-    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    console.log(pkg.version);
+    console.log(versionLine(CLI_VERSION, BUILD_INFO));
     rl.close();
     return;
   }
   if (cmd === "doctor") return doctor();
   if (cmd === "models") return modelsCmd();
   if (cmd === "status") return statusCmd();
+  if (cmd === "chat") return chatCmd();
   if (cmd !== "init") {
-    console.log(`Usage: npx @inferall/cli <init|doctor|models|status|version> [--key ifu_...] [--yes] [--no-ai] [--free] [--json]`);
+    console.log(`Usage: npx @inferall/cli <init|doctor|models|status|chat|version> [--key ifu_...] [--model id] [--yes] [--no-ai] [--free] [--json]`);
     exit(cmd === "help" || flag("help") ? 0 : 1);
   }
 
-  console.log(`\n${c.bold("InferAll setup")} ${c.dim("— one API for OpenAI, Anthropic, Google, and 118+ $0 NIM models")}\n`);
+  console.log(`\n${c.bold("InferAll setup")} ${c.dim("one API for OpenAI, Anthropic, Google, and 10+ $0 NIM models")}\n`);
 
   const root = cwd();
   const project = detectProject(root);
+  // 2026-07-28 tick 844. Deliberately NOT folded into envResult.problems: that
+  // channel's closing message says either "Your key was not saved" or "your key
+  // is in .env but .gitignore was not updated", and both would be false here.
+  // The key saves fine; what failed is reading a manifest, so what is at risk
+  // is DETECTION, and the honest warning names that instead.
+  for (const problem of project.readProblems) {
+    console.log(`  ${c.yellow("~")} ${problem}`);
+    console.log(`    Your dependencies could not be read, so existing SDK calls may not be rewritten.`);
+  }
   if (!project.kind) {
-    console.log(`${c.yellow("!")} No package.json / pyproject.toml / requirements.txt found here.`);
-    console.log(`  Run this from your project root, or continue for a bare .env + example setup.`);
+    // 2026-07-27 tick 828: this used to say "Run this from your project root",
+    // which was impossible advice for someone already standing in it -- see
+    // detectProject. Import-based detection now covers the manifest-less Python
+    // case, so reaching here means we found no manifest AND no SDK import, and
+    // the honest statement is that there is nothing here to migrate rather than
+    // that the user is in the wrong directory.
+    console.log(`${c.yellow("!")} No project detected here: no package.json, pyproject.toml or requirements.txt,`);
+    console.log(`  and no Python file or notebook using an AI SDK.`);
+    console.log(`  ${c.dim(`(looked in ${root})`)}`);
+    console.log(`  If your code lives elsewhere, cd there and re-run. Otherwise continue for a`);
+    console.log(`  bare .env + example setup you can point at your own code.`);
     if (!(await confirm("Continue anyway?", false))) exit(0);
     project.kind = "node";
   }
@@ -531,36 +2493,276 @@ async function main() {
   // --- key ---
   let key = flagValue("key") || env.INFERALL_API_KEY || "";
   if (!key) {
+    // 2026-07-26 tick 800 — the wizard used to dead-end the ONE person it
+    // exists for: someone with no key yet.
+    //
+    // Pressing Enter with nothing typed sent "" to the gateway, which 401'd,
+    // and we printed "The gateway does not recognise that key." That is the
+    // worst available message — it tells a user their key is wrong when their
+    // actual state is "I don't have one." Then it exited, so the fix was
+    // re-running the whole wizard.
+    //
+    // Two changes: empty input is now its own case (re-prompt, never verified),
+    // and we offer to open the signup page so getting a key is a keystroke
+    // instead of a context switch out of the terminal and back. This is the
+    // widest measured gap in the funnel — 114 arrived, 97 minted, 52 called.
     console.log(`\n  Grab a key at ${c.cyan(KEYS_URL)} (free account, key starts with ${c.bold("ifu_")})`);
-    key = await ask(`  Paste your InferAll API key: `);
+    console.log(`  ${c.dim("It's free, takes about 20 seconds, and includes 5 calls with no card.")}`);
+
+    const interactive = Boolean(process.stdin.isTTY) && !YES;
+    for (let attempt = 1; !key; attempt++) {
+      if (attempt === 1 && interactive && (await confirm(`  Open ${KEYS_URL} in your browser now?`, true))) {
+        if (openBrowser(KEYS_URL)) {
+          console.log(`  ${c.green("→")} opened your browser. Create a key, then paste it below.`);
+        } else {
+          console.log(`  ${c.yellow("!")} couldn't open a browser; visit ${c.cyan(KEYS_URL)} manually.`);
+        }
+      }
+      key = await ask(`  Paste your InferAll API key: `);
+      if (key) break;
+
+      // Non-interactive (CI, piped stdin): looping would spin forever on EOF.
+      // Say what to do and leave a non-zero exit for the caller.
+      if (!interactive) {
+        console.log(`${c.red("✗")} No key provided.`);
+        console.log(`  Pass one non-interactively: ${c.bold("npx @inferall/cli init --key ifu_…")}`);
+        console.log(`  or set ${c.bold("INFERALL_API_KEY")} in the environment. Get one at ${c.cyan(KEYS_URL)}.`);
+        exit(1);
+      }
+      if (attempt >= 3) {
+        console.log(`${c.yellow("!")} No key entered, so nothing was changed.`);
+        console.log(`  Re-run ${c.bold("npx @inferall/cli init")} once you have one from ${c.cyan(KEYS_URL)}.`);
+        exit(0); // 0: the user chose to stop, that is not a failure
+      }
+      console.log(`  ${c.dim("Nothing entered. Paste the key (starts with ifu_), or Ctrl-C to stop.")}`);
+    }
   }
-  if (!key.startsWith("ifu_")) {
-    console.log(`${c.red("✗")} That doesn't look like an InferAll key (expected ifu_ prefix).`);
+  // 2026-07-25: this used to HARD-EXIT on anything without an ifu_ prefix, which
+  // was both wrong and redundant.
+  //
+  // Wrong: the gateway mints ifu_ today but auth.ts explicitly accepts ifu_,
+  // ifa_, kr_user_ and kr_proj_ ("Legacy kr_user_... keys remain valid"). So a
+  // legacy or project key — which works perfectly against the API — was told
+  // "that doesn't look like an InferAll key" and the wizard quit. `doctor` only
+  // warned on the same input, so the two commands disagreed about what a valid
+  // key is, and `init` was stricter than the system it configures.
+  //
+  // Redundant: the very next line verifies the key against the gateway, which
+  // is the actual authority. A client-side prefix test is a second copy of a
+  // rule enforced elsewhere, and second copies drift.
+  //
+  // Kept: a specific, useful hint when the key is recognisably ANOTHER
+  // provider's, because a bare 401 would not explain that.
+  const foreignKey =
+    key.startsWith("sk-ant-") ? "an Anthropic key (sk-ant-…)" :
+    key.startsWith("sk-or-") ? "an OpenRouter key (sk-or-…)" :
+    key.startsWith("sk-") ? "an OpenAI key (sk-…)" :
+    key.startsWith("AIzaSy") ? "a Google AI Studio key (AIzaSy…)" : null;
+  if (foreignKey) {
+    console.log(`${c.red("✗")} That looks like ${foreignKey}, not an InferAll key.`);
+    console.log(`  Mint one at ${c.cyan(KEYS_URL)}. InferAll keys start with ${c.bold("ifu_")}.`);
     exit(1);
   }
 
+  // 2026-07-25: this used to verify against /v1/models — which is PUBLIC.
+  // It returns 200 with a garbage key and 200 with no Authorization header at
+  // all, so "verifying key … ok" passed for literally any string and this step
+  // proved nothing. That is the vacuous-guard failure mode, in the one place a
+  // developer trusts us to tell them their key works before we rewrite their
+  // source files.
+  //
+  // /ai/v1/key/status runs authenticateRequest: 401 for a bad key, 200 for a
+  // good one (verified against production, including a fake ifu_-prefixed key).
   process.stdout.write(`  verifying key against ${API_BASE} … `);
-  const models = await apiGet("/models", key).catch(() => null);
-  if (!models || (models.status !== 200 && models.status !== 402)) {
-    console.log(c.red(`failed (${models ? `HTTP ${models.status}` : "network error"})`));
+  // 2026-07-30 tick 854: this used to `.catch(() => null)`, discarding the error,
+  // and then print "Check the key at <keys page> and re-run" for a NETWORK
+  // failure. Minting a new key cannot fix DNS, a closed port or a proxy that
+  // re-signs TLS. That is the tick 832 conflation, which was fixed in `doctor`
+  // and never applied here, one screen away, and the tick 852 cause-naming was
+  // built for `doctor` alone for the same reason. Both commands now share it.
+  const verify = await fetch(`${ANTHROPIC_BASE}/ai/v1/key/status`, {
+    signal: timeoutSignal(),
+    headers: { Authorization: `Bearer ${key}` },
+  }).then((res) => ({ res })).catch((err) => ({ err }));
+  if (verify.res && verify.res.status !== 401) {
+    // Same trap as doctor: a captive portal answers 200 with HTML, and the
+    // wizard would otherwise print "ok" and write the key as verified.
+    const parsedVerify = await readJsonBody(verify.res.clone());
+    if (parsedVerify.parseFailed) {
+      console.log(c.red("failed"));
+      for (const line of nonJsonLines(parsedVerify, "  ")) console.log(line);
+      exit(1);
+    }
+  }
+  if (verify.res?.status === 401) {
+    console.log(c.red("rejected"));
+    console.log(`  The gateway does not recognise that key. Mint one at ${KEYS_URL} and re-run.`);
+    exit(1);
+  }
+  if (verify.err) {
+    console.log(c.red("failed"));
+    // Same lines doctor prints, so the cause and its remedy are stated once.
+    for (const line of unreachableLines(verify.err)) console.log(`  ${line}`);
+    console.log(`  ${c.bold("Nothing was written.")} Your key was never checked, so this says nothing about it.`);
+    exit(1);
+  }
+  if (!verify.res.ok) {
+    console.log(c.red(`failed (HTTP ${verify.res.status})`));
     console.log(`  Check the key at ${KEYS_URL} and re-run.`);
     exit(1);
   }
   console.log(c.green("ok"));
 
   // --- env files ---
-  upsertEnvFile(root, key);
-  console.log(`  ${c.green("+")} INFERALL_API_KEY written to ${c.bold(".env")} (and .env.example placeholder)`);
+  // tick 820: never silently replace a credential, and never call a
+  // replacement an addition. --yes still replaces (the user opted in), but the
+  // message says so.
+  const existingKey = readEnvKey(root);
+  let writeKey = true;
+  if (existingKey && existingKey !== key) {
+    writeKey = await confirm(`  .env already has a DIFFERENT INFERALL_API_KEY (${maskKey(existingKey)}). Replace it?`);
+  }
+  // 2026-07-29 tick 850. Measured in a monorepo with the key at the repo root
+  // and the code in packages/api: running init from the sub-package wrote a
+  // SECOND .env with a different key and said nothing about the first. Two
+  // credentials for one repo, and which one the app uses depends on the
+  // directory it starts in.
+  //
+  // Deliberately a warning and not a refusal. A monorepo where each package
+  // genuinely has its own key is a real setup, and this command was given an
+  // explicit --key, so blocking it would break a legitimate case to prevent a
+  // confusing one. Naming the other file is enough to make the choice informed.
+  // Printed BEFORE the write so the ordering matches what happens on disk.
+  if (writeKey) {
+    const ancestor = findAncestorEnvKey(root);
+    if (ancestor) {
+      const rel = relative(root, ancestor.dir) || ".";
+      console.log(`  ${c.yellow("~")} ${c.bold(join(rel, ".env"))} already holds a key for this repo`);
+      console.log(`    Writing another one here. Your app will use whichever .env matches the`);
+      console.log(`    directory it runs from, so delete one if that is not what you intended.`);
+    }
+  }
+  const envResult = upsertEnvFile(root, key, { writeKey });
+  // 2026-07-27 tick 836: report what actually happened on disk. Previously a
+  // failing step threw a bare errno from inside upsertEnvFile, after the key had
+  // already been written, so the user got no file name, no cause, and no notice
+  // that a live credential was sitting unprotected.
+  for (const p of envResult.problems) {
+    console.log(`  ${c.red("✗")} ${p}`);
+  }
+  if (envResult.keyWritten && !envResult.gitignoreOk) {
+    // The security-relevant combination, and the reason this is not merely a
+    // tidier error message: the secret is on disk and nothing is ignoring it.
+    console.log(`  ${c.red("!")} your key is in ${c.bold(".env")} but ${c.bold(".gitignore")} could not be updated.`);
+    console.log(`    Add ${c.cyan(".env")} to .gitignore yourself before committing.`);
+  }
+  if (!envResult.keyWritten && writeKey) {
+    const dirBad = dirIsUnwritable(root);
+    console.log(
+      `  ${c.dim("The key was not saved. Pass it per run with")} ${c.bold("--key")}${c.dim(
+        dirBad ? ", or make this DIRECTORY writable: nothing can be created here." : ", or fix the file above.",
+      )}`,
+    );
+  }
+  if (existingKey && existingKey === key) {
+    console.log(`  ${c.green("=")} INFERALL_API_KEY in ${c.bold(".env")} already matches (unchanged)`);
+  } else if (existingKey && writeKey) {
+    console.log(`  ${c.yellow("!")} REPLACED a different INFERALL_API_KEY in ${c.bold(".env")} ${c.dim(`(was ${maskKey(existingKey)})`)}`);
+  } else if (existingKey) {
+    console.log(`  ${c.yellow("~")} kept your existing INFERALL_API_KEY in ${c.bold(".env")} ${c.dim("(this run used the key you supplied)")}`);
+  } else if (envResult.keyWritten) {
+    // tick 836: guarded. This line used to print unconditionally, so a failed
+    // write was announced as a success on the very next line after the error.
+    console.log(`  ${c.green("+")} INFERALL_API_KEY written to ${c.bold(".env")} (and .env.example placeholder)`);
+  }
 
   // --- integration ---
-  const usesSdk = project.sdks.some((s) => ["openai", "@anthropic-ai/sdk", "anthropic"].includes(s));
-  if (usesSdk) {
-    const sites = findCallSites(root).filter((s) => !s.alreadyPointed);
+  // Computed before the branch: a Vercel-AI project has no client constructor
+  // to rewrite, so without this the wizard would treat it as greenfield.
+  // .filter(!usesFactory) preserves the pre-tick-831 behaviour exactly: this
+  // list drives the "paste this snippet" guidance, and a file that already
+  // calls createOpenAI does not need the snippet, only a baseURL. doctor reads
+  // the same finder with a different filter (alreadyPointed).
+  const allVercelSites = project.kind === "node" ? findVercelAiSites(root) : [];
+  const vercelAiSites = allVercelSites.filter((s) => !s.usesFactory);
+  // Factory files that never got our baseURL. Separate list because the remedy
+  // is one argument, not the snippet, but they count the same in the sum below.
+  const vercelFactoryUnpointed = allVercelSites.filter((s) => s.usesFactory && !s.alreadyPointed);
+  // 2026-07-26 tick 805: this was a THIRD hardcoded list, narrower than the two
+  // detection lists above it. Fixing detection to recognise langchain-openai
+  // was not enough -- this gate still said "no SDK", the wizard still took the
+  // greenfield branch, and it still printed "Done. Your project is wired to
+  // InferAll" over an unmigrated file.
+  //
+  // That is the lesson from the whole t803-t805 run in one line: a claim can
+  // stay false after you fix the thing you thought was making it false. I
+  // verified detection (the step) and only caught this by running the flow end
+  // to end and reading the file afterwards.
+  //
+  // Derived from one place now. Anything whose constructors findCallSites can
+  // actually rewrite belongs here, so the two cannot drift apart again.
+  const CODEMODDABLE = ["openai", "@anthropic-ai/sdk", "anthropic",
+    "langchain-openai", "langchain_openai", "langchain-anthropic", "langchain_anthropic"];
+  const usesSdk = project.sdks.some((s) => CODEMODDABLE.includes(s));
+  // 2026-07-26 tick 816: computed BEFORE the green tick below, because the tick
+  // is exactly what was wrong. A notebook project lists `openai` in
+  // requirements.txt, so usesSdk is true, but findCallSites never opens .ipynb
+  // and returned zero, so the wizard reported "nothing to migrate" over a
+  // notebook still calling OpenAI directly.
+  // 2026-07-27 tick 830: filtered to cells that are NOT already pointed, which
+  // is what the findCallSites line below has always done. Without it, a user
+  // who had already made the manual edit was told on their next run to "add
+  // these two arguments" that were already there, and the cell still counted
+  // toward the sum that suppresses "Done. Your project is wired to InferAll" --
+  // so a fully wired project was reported as unfinished. Mirror image of the
+  // doctor bug fixed in the same tick: doctor could not see notebooks at all,
+  // init could not see that they were already done.
+  const notebookSites = findNotebookSites(root)
+    .map((s) => ({ ...s, hits: s.hits.filter((h) => !h.alreadyPointed) }))
+    .filter((s) => s.hits.length);
+  // Populated inside the codemod branch below; read by the closing line.
+  let unwritableCount = 0;
+  const cappedInit = [];
+  // 2026-08-01 tick 896. `usesSdk` reads the MANIFEST, and it used to gate the
+  // source scan entirely. Every earlier fix in this family (t803 monorepo, t804
+  // Vercel AI, t805 LangChain) added another NAME to the manifest scan, which by
+  // construction cannot reach the case where the SDK is not declared at all.
+  //
+  // MEASURED against the installed 0.2.1 artifact, on a project whose
+  // package.json had no dependencies and whose src/index.js read
+  // `new OpenAI({ apiKey: process.env.OPENAI_API_KEY })`:
+  //
+  //     detected: node project
+  //     Done. Your project is wired to InferAll.
+  //
+  // Nothing was rewritten and it reported success. Running `inferall init`
+  // before `npm install openai` is an ordinary ordering, so this is reachable
+  // rather than a corner.
+  //
+  // findCallSites reads the SOURCE, so it is the authoritative answer to "is
+  // there anything to rewrite" and it now decides. The manifest survives as a
+  // hint: an SDK that IS declared but has no constructors still gets its honest
+  // "no un-migrated client constructors found" line, which is why usesSdk stays
+  // in the condition. The tree is already walked unconditionally for notebooks
+  // a few lines above, so this adds no new cost class.
+  const sites = findCallSites(root, cappedInit).filter((s) => !s.alreadyPointed);
+  if (usesSdk || sites.length > 0) {
     if (sites.length === 0) {
-      console.log(`  ${c.green("✓")} AI SDK present but no un-migrated client constructors found.`);
+      // Only claim there is nothing to do when there is genuinely nothing to
+      // do. Notebooks are un-migrated code we simply cannot rewrite safely.
+      if (notebookSites.length === 0) {
+        console.log(`  ${c.green("✓")} AI SDK present but no un-migrated client constructors found.`);
+      } else {
+        console.log(`  ${c.yellow("~")} No rewritable client constructors, but notebooks below still call the provider directly.`);
+      }
     } else {
       console.log(`\n  Found ${c.bold(sites.length)} client constructor site(s):`);
       for (const s of sites) console.log(`    - ${relative(root, s.file)} ${c.dim(`(${s.sdk})`)}`);
+      // Files we detected, tried to rewrite, and could NOT write. They belong
+      // in the same bucket as Vercel/Gemini/notebook sites: detected, not
+      // changed, and therefore must suppress the "your project is wired"
+      // closing line (tick 816).
+      let unwritable = 0;
       if (await confirm(`  Point them at the InferAll gateway?`)) {
         for (const s of sites) {
           let patched = patchSite(s);
@@ -569,7 +2771,7 @@ async function main() {
             process.stdout.write(`    ${c.dim("AI-assist")} ${relative(root, s.file)} … `);
             const r = await aiSuggestPatch(key, s);
             if (r.status === 402) {
-              console.log(c.yellow("skipped (account not activated yet — see verify step below)"));
+              console.log(c.yellow("skipped (account not activated yet, see verify step below)"));
               continue;
             }
             patched = r.patched;
@@ -577,25 +2779,105 @@ async function main() {
             console.log(patched ? c.green("patch ready") : c.yellow("no confident patch"));
           }
           if (!patched) {
-            const manualBase = s.sdk === "Anthropic" ? ANTHROPIC_BASE : API_BASE;
-            console.log(`    ${c.yellow("~")} ${relative(root, s.file)}: couldn't patch automatically — set ${s.isPy ? `base_url="${manualBase}"` : `baseURL: "${manualBase}"`} on your ${s.sdk} client manually.`);
+            const manualBase = baseForSdk(s.sdk);
+            console.log(`    ${c.yellow("~")} ${relative(root, s.file)}: couldn't patch automatically. Set ${s.isPy ? `base_url="${manualBase}"` : `baseURL: "${manualBase}"`} on your ${s.sdk} client manually.`);
+            // 2026-07-31 tick 880: this `continue` did not count the site, so a
+            // file we detected and left untouched still ended with "Done. Your
+            // project is wired to InferAll." Only the EACCES branch below was
+            // counted, though the comment above this block already says
+            // detected-but-not-changed belongs in the same bucket. Tightening
+            // the AI patch check made this path common rather than rare.
+            unwritable++;
+            continue;
+          }
+          // Declining the rewrite also leaves the site unchanged, so it counts
+          // for the same reason.
+          if (via === "AI" && !(await confirm(`    Apply AI-suggested rewrite to ${relative(root, s.file)}?`))) {
+            unwritable++;
+            continue;
+          }
+          // 2026-07-27 tick 824: guarded. This write was bare, so a single
+          // unwritable file killed the whole wizard with a raw Node exception:
+          //
+          //   ✗ EACCES: permission denied, open '/abs/path/svc.ts'
+          //
+          // and it did so AFTER .env and .gitignore had been written, leaving a
+          // half-configured project, no summary, and no test call. One vendored
+          // read-only file in a monorepo cost the user the entire setup.
+          //
+          // To its credit it never claimed success, which is the failure this
+          // codebase keeps making. But "abort everything" is the wrong response
+          // to a per-file problem when a per-file fallback already exists three
+          // lines above. Route into it: report this file honestly, keep going.
+          try {
+            writeFileSync(s.file, preserveTrailingNewline(s.body ?? "", patched));
+          } catch (err) {
+            const why = err && err.code === "EACCES" ? "no write permission" : (err?.code || "write failed");
+            console.log(`    ${c.yellow("~")} ${relative(root, s.file)}: ${c.bold(why)}, left unchanged. Make it writable and re-run, or set ${s.isPy ? `base_url="${baseForSdk(s.sdk)}"` : `baseURL: "${baseForSdk(s.sdk)}"`} by hand.`);
+            unwritable++;
             continue;
           }
-          if (via === "AI" && !(await confirm(`    Apply AI-suggested rewrite to ${relative(root, s.file)}?`))) continue;
-          writeFileSync(s.file, patched);
+          // Post-patch self-check. A rewrite that points the client at InferAll
+          // but leaves a FOREIGN provider credential produces a project that
+          // fails on its first run — while this wizard prints "Done." That
+          // exact combination shipped until 2026-07-25 and is invisible to the
+          // verify step below, which calls the API with the key directly rather
+          // than through the code we just wrote. Never claim success on a file
+          // we can see is still mis-wired.
+          const stillForeign = /(?:process\.env\.|os\.environ\[\s*["']|os\.getenv\(\s*["'])(?:OPENAI|ANTHROPIC|GOOGLE|GEMINI|OPENROUTER)_API_KEY/.test(patched);
+          // tick 810: the same check, for a credential written inline. The env-var
+          // form above was the only one this warned about, so a client left
+          // holding apiKey: "sk-…", or a local-inference placeholder like
+          // "EMPTY" that we deliberately do not rewrite, printed a bare ✓ over
+          // a project that cannot authenticate.
+          const stillLiteral = /\b(?:api_key\s*=|apiKey\s*:)\s*(["'])(?!\s*\1)[^"']*\1/.test(patched)
+            && !/(?:os\.environ\[|os\.getenv\(|process\.env\.)\s*["']?INFERALL_API_KEY/.test(patched);
           console.log(`    ${c.green("✓")} ${relative(root, s.file)} ${c.dim(`(${via})`)}`);
+          if (stillForeign) {
+            console.log(`    ${c.yellow("!")} ${relative(root, s.file)} still reads another provider's API key env var.`);
+            console.log(`      Point it at ${c.bold(s.isPy ? 'os.environ["INFERALL_API_KEY"]' : "process.env.INFERALL_API_KEY")} or the first run will fail.`);
+          } else if (stillLiteral) {
+            console.log(`    ${c.yellow("!")} ${relative(root, s.file)} still passes a hardcoded API key literal.`);
+            console.log(`      Replace it with ${c.bold(s.isPy ? 'os.environ["INFERALL_API_KEY"]' : "process.env.INFERALL_API_KEY")} or the first run will fail.`);
+          }
         }
+        unwritableCount = unwritable;
       }
     }
-  } else {
+  } else if (vercelAiSites.length === 0 && notebookSites.length === 0) {
+    // Only treat this as a greenfield project when there is genuinely no AI
+    // code we recognised. Writing a hello-world next to un-migrated calls is
+    // what made the tick-804 report misleading. Notebooks count as recognised
+    // AI code (tick 816): a .ipynb calling OpenAI is not a blank slate.
     const example = writeExample(root, project.kind);
-    if (example) console.log(`  ${c.green("+")} example written: ${c.bold(relative(root, example))}`);
+    if (example.path) console.log(`  ${c.green("+")} example written: ${c.bold(relative(root, example.path))}`);
+    // tick 837: an unwritable example is a per-file degradation, not a crash.
+    // It also counts toward envResult.problems so the closing line cannot claim
+    // a clean setup while a step it announced never happened.
+    if (example.problem) {
+      console.log(`  ${c.red("✗")} ${example.problem}`);
+      envResult.problems.push(example.problem);
+    }
     if (project.kind === "node") console.log(`  ${c.dim("optional:")} npm install @inferall/sdk`);
     else console.log(`  ${c.dim("optional:")} pip install inferall-ai`);
   }
 
+  if (vercelAiSites.length) printVercelAiGuidance(root, vercelAiSites);
+  // 2026-07-27 tick 831: a file that calls createOpenAI WITHOUT an InferAll
+  // baseURL routes to the provider, and init used to say nothing about it and
+  // then print "Done. Your project is wired to InferAll". Measured: a one-file
+  // project in exactly that state got a clean Done while every request went to
+  // OpenAI. These need one argument, not the whole snippet, so they get their
+  // own line rather than being folded into the guidance above.
+  if (vercelFactoryUnpointed.length) {
+    console.log(`\n  ${c.bold("Vercel AI SDK factory")} without an InferAll baseURL in ${vercelFactoryUnpointed.length} file(s):`);
+    for (const s of vercelFactoryUnpointed) console.log(`    - ${relative(root, s.file)}`);
+    console.log(`  These were ${c.bold("NOT changed")}. Add one argument to the factory call:`);
+    console.log(c.cyan(`    baseURL: "${API_BASE}"`));
+  }
   const geminiSites = findGeminiSites(root);
   if (geminiSites.length) printGeminiGuidance(root, geminiSites);
+  if (notebookSites.length) printNotebookGuidance(root, notebookSites);
 
   // --- verify with a live call ---
   const testModel = flagValue("model") || FREE_MODEL;
@@ -603,33 +2885,162 @@ async function main() {
   const test = await apiChat(key, [{ role: "user", content: "Reply with the single word: ready" }], testModel);
   if (test.status === 200) {
     console.log(c.green("success ✓"));
-    console.log(`\n${c.green(c.bold("Done."))} Your project is wired to InferAll. Models list: ${API_BASE}/models\n`);
+    // 2026-07-26 tick 804: do not claim the project is wired when we have just
+    // printed guidance saying specific files were NOT changed. Saying "Done.
+    // Your project is wired to InferAll" directly under a list of un-migrated
+    // call sites is the same false-success the monorepo bug produced, only
+    // this time contradicted by our own output three lines earlier.
+    // 2026-07-26 tick 816: notebooks were missing from this sum, so the wizard
+    // printed "Done. Your project is wired to InferAll" three lines under its
+    // own "These were NOT changed" notebook list. The t804 fix was correct and
+    // simply did not know about a surface added later.
+    //
+    // THIS SUM MUST INCLUDE EVERY DETECTED-BUT-NOT-REWRITTEN SURFACE. It has
+    // now drifted once already, and it is the fourth time in this codebase that
+    // one fact spread across several places went stale in one of them
+    // (t811 base URLs, t813 the metrics filter, t815 three model call sites).
+    // Anything that prints "NOT changed" guidance belongs here, or the closing
+    // line contradicts it.
+    // 2026-07-30 tick 854. MEASURED: three identical call sites, one past the
+    // depth cap and one over the size cap, produced "Found 1 client constructor
+    // site(s)" and then "Done. Your project is wired to InferAll." while two
+    // files still called OpenAI directly. That is the tick 805 outcome exactly.
+    // A cap the user cannot see becomes a claim the tool cannot support, so an
+    // incomplete scan counts as outstanding work like any unwritable file.
+    const capInit = cappedSummary(cappedInit);
+    if (capInit) {
+      console.log(`  ${c.yellow("~")} ${capInit}, so there may be client code this did not see.`);
+      console.log(`    Wire any client in those paths by hand, or move it within 6 directory levels and re-run.`);
+    }
+    const manual = vercelAiSites.length + geminiSites.length + notebookSites.length + unwritableCount
+      + vercelFactoryUnpointed.length + (capInit ? 1 : 0);   // tick 831, see the note above this sum
+    // 2026-07-27 tick 836: a filesystem problem outranks the file counts. With
+    // .env unwritable the key never reached disk, so "Done. Your project is
+    // wired to InferAll" was flatly false -- the next run finds no key at all.
+    // With .gitignore unwritable the key IS on disk and unprotected, which is
+    // not "done" either. Both used to print Done and exit 0.
+    if (envResult.problems.length) {
+      const what = envResult.keyWritten
+        ? `Your key is in .env, but ${c.bold(".gitignore")} was not updated.`
+        : `${c.bold("Your key was not saved.")} Pass it with ${c.bold("--key")} until ${dirIsUnwritable(root) ? "this directory is writable" : "the file above is fixed"}.`;
+      console.log(`\n${c.yellow(c.bold("Setup incomplete."))} ${what}`);
+      console.log(`  The gateway accepted your key, so the account side is fine. Models list: ${API_BASE}/models\n`);
+      rl.close();
+      exit(1);
+    }
+    if (manual > 0) {
+      console.log(`\n${c.green(c.bold("Key verified and configured."))} ${c.yellow(`${manual} file(s) still need the one-line change above.`)}`);
+      console.log(`  Your key works and .env is set. Models list: ${API_BASE}/models\n`);
+    } else {
+      console.log(`\n${c.green(c.bold("Done."))} Your project is wired to InferAll. Models list: ${API_BASE}/models\n`);
+    }
   } else if (test.status === 402) {
     console.log(c.yellow("blocked (402)"));
     console.log(`\n  Everything is wired up, but your account isn't activated yet.`);
-    // Real account state beats a generic message — trial counter + whether a
+    // Real account state beats a generic message: trial counter + whether a
     // checkout was already started (settle vs start are different next steps).
     const st = await fetch(`${ANTHROPIC_BASE}/ai/v1/key/status`, {
+      signal: timeoutSignal(),
       headers: { Authorization: `Bearer ${key}` },
     }).then((r) => (r.ok ? r.json() : null)).catch(() => null);
     if (st?.trial) {
-      console.log(`  Trial: ${st.trial.used}/${st.trial.cap} free calls used${st.has_card ? c.dim(" · checkout started but not settled — finishing it activates you") : ""}.`);
+      console.log(`  Trial: ${st.trial.used}/${st.trial.cap} free calls used. ${st.trial.remaining === 0 ? "none left" : `${st.trial.remaining} still available`}${st.has_card ? c.dim(" · checkout started but not settled, and finishing it activates you") : ""}.`);
     }
-    console.log(`  InferAll charges ${c.bold("$0 markup")} — a one-time ${c.bold("$5 activation")} (it becomes spendable`);
-    console.log(`  balance, not a fee) unlocks every model, including the 118+ free NIM models.`);
+    // Same correction as printGeminiGuidance above; see the note there.
+  console.log(`  The 10+ free NIM models are ${c.bold("$0 in/out")}; premium tokens bill at InferAll's published per-token rate. A one-time ${c.bold("$5 activation")} (it becomes spendable`);
+    console.log(`  balance, not a fee) unlocks every model, including the 10+ free NIM models.`);
     console.log(`  Activate: ${c.cyan(BILLING_URL)}`);
-    console.log(`  The code changes above are done — the first call will work the moment you activate.`);
+    console.log(`  The code changes above are done. The first call will work the moment you activate.`);
     console.log(`  Check anytime: ${c.bold("npx @inferall/cli status")}\n`);
+  } else if (test.status === 401 || test.status === 403) {
+    // 2026-07-27 tick 826: this fell into the generic branch below, which
+    // printed a bare "HTTP 401", advised re-running init, and exited 0.
+    //
+    // Three separate things were wrong with that, in increasing order of harm.
+    // The wizard printed "verifying key ... ok" four lines earlier, so it
+    // contradicted its own output with no acknowledgement. Retrying an
+    // authentication failure with the same credential cannot succeed, so the
+    // remedy we printed was a dead end. And exiting 0 told every calling
+    // script that setup had worked, while the codemod had already repointed a
+    // working project at a gateway that rejects its key. A tool that breaks a
+    // project and reports success is the worst rung of the severity ladder,
+    // and this is the second time the exit status has been the tell (t824).
+    //
+    // The pre-flight hits /ai/v1/key/status and this hits /v1/chat/completions,
+    // so a key revoked between the two, or valid for a different account,
+    // produces exactly this split. Measured against a stub that answers 200 on
+    // status and 401 on chat.
+    console.log(c.red("rejected (401)"));
+    console.log(`\n  The gateway accepted this key a moment ago and has now rejected it.`);
+    console.log(`  That usually means the key was revoked or rotated between the two checks,`);
+    console.log(`  or that it belongs to a different account than the one you are setting up.`);
+    console.log(`\n  ${c.bold("Your files were already changed.")} The code and .env now point at InferAll,`);
+    console.log(`  so calls will keep failing until the key works. Re-running with the same key`);
+    console.log(`  cannot help.`);
+    console.log(`\n  Mint a fresh key at ${c.cyan(KEYS_URL)}, then re-run:`);
+    console.log(`    ${c.bold("npx @inferall/cli init --key ifu_your_new_key")}\n`);
+    rl.close();
+    exit(1);
   } else {
+    // Transient or unexpected. Retrying IS the right advice here, unlike the
+    // 401 case above, but the run still failed to verify so it must not exit 0.
     console.log(c.red(`HTTP ${test.status}`));
     console.log(`  ${JSON.stringify(test.body).slice(0, 300)}`);
     console.log(`  Setup files were written; re-run ${c.bold("npx @inferall/cli init")} to retry the verify step.\n`);
+    rl.close();
+    exit(1);
   }
   rl.close();
 }
 
-main().catch((err) => {
-  console.error(`${c.red("✗")} ${err?.message || err}`);
-  rl.close();
-  exit(1);
-});
+// Run only when invoked as the entry point. Before this guard the file executed
+// main() on import, so the codemod could not be unit-tested at all -- which is
+// exactly how the 2026-07-25 bug shipped: `init` rewrote a client to point at
+// InferAll while leaving the caller's OPENAI_API_KEY in place, printed "Done",
+// and left a project that threw on its first run.
+/**
+ * True when this file is being RUN, as opposed to imported by a test.
+ *
+ * argv[1] must be resolved through realpath first. npm installs a bin as a
+ * SYMLINK at node_modules/.bin/inferall, and when the shell execs that symlink
+ * via the shebang, argv[1] is the symlink path while import.meta.url is always
+ * the resolved real file. Comparing them unresolved is false for every
+ * npm-installed invocation, so main() never ran and the process exited 0 in
+ * silence: `npx @inferall/cli` did nothing at all.
+ *
+ * The tests could not catch it. They spawn `node <real path to bin/inferall.js>`,
+ * where argv[1] IS the real file and the comparison happens to hold. The guard
+ * was added in #114 to make this module importable BY those tests, so the change
+ * made for testability broke the only path a user actually takes.
+ */
+function isRunningAsEntrypoint(p) {
+  if (!p) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(p)).href;
+  } catch {
+    // A missing or unreadable argv[1] must not silently disable the CLI. Fall
+    // back to the unresolved comparison rather than returning false.
+    return import.meta.url === pathToFileURL(p).href;
+  }
+}
+const isEntrypoint = isRunningAsEntrypoint(argv[1]);
+if (isEntrypoint) {
+  main().catch((err) => {
+    // 2026-07-27 tick 832: an unreachable gateway reached here and printed
+    // Node's own words -- a bare "✗ fetch failed" with no URL, no cause and no
+    // next step. `models` offline was the measured case.
+    if (isNetworkError(err)) for (const line of unreachableLines(err)) console.error(line);
+    else if (err instanceof InputEndedError) {
+      // Naming the working command matters more than naming the fault. This
+      // exact invocation was verified end to end: it writes .env, gitignores
+      // it, rewrites the client constructors and makes a test call.
+      console.error(`${c.red("✗")} setup needs an answer but there is no more input to read.`);
+      console.error(`  Anything reported above already happened and is on disk.`);
+      console.error(`  For a non-interactive setup, pass the key and accept the defaults:`);
+      console.error(`    ${c.cyan("npx @inferall/cli init --key ifu_... --yes")}`);
+      console.error(`  Or run ${c.cyan("npx @inferall/cli init")} in a terminal to answer the prompts.`);
+    } else console.error(`${c.red("✗")} ${err?.message || err}`);
+    rl.close();
+    exit(1);
+  });
+}