stoaken 0.4.0 → 0.5.1

package/README.md

@@ -10,13 +10,13 @@ npx stoaken init
 
 Run it in the root of the project you want connected to a Stoaken Brand. It will:
 
-1. Ask how you'd like to sign in -- open your browser for a real OAuth 2.1 login, or let you paste an API key you've already created at `/settings/api-keys`.
+1. Ask how you'd like to sign in -- in your browser (OAuth 2.1), or by pasting an API key you've already created in Settings › API keys.
 2. List the real Brands your account can see, and let you pick one.
 3. Write `stoaken.config.json` (which Brand, which server -- safe to commit, holds no secret) and `.stoaken/credentials.json` (your bearer credential, `chmod 600`, automatically added to `.gitignore`).
 4. Ask which AI tool to connect (or take `--client`) and write that tool's MCP config.
 5. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents explaining how this project connects to Stoaken's MCP server and what its tools do.
 
-Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
+Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or sign in again.
 
 ## Connect an AI tool
 
@@ -32,22 +32,42 @@ npx stoaken init --client cursor
 | `copilot` | `.vscode/mcp.json` (`servers.stoaken`, VS Code agent mode) |
 | `claude-desktop` | Nothing: prints the steps to add a custom connector (Customize > Connectors) |
 | `v0` | Nothing: prints the steps to add a custom MCP server in v0 (+ > MCPs) |
+| `windsurf` | `.devin/mcp_config.json` (`mcpServers.stoaken`, URL only). Windsurf is now Devin Desktop; this is for its Devin Local agent and Devin CLI |
+| `zed` | `.zed/settings.json` (`context_servers.stoaken`, URL only; OAuth). With an API key: nothing, prints how to add it to your user settings |
+| `gemini-cli` | `.gemini/settings.json` (`mcpServers.stoaken.httpUrl`; loads in trusted folders only) |
+| `jetbrains` | `.junie/mcp/mcp.json` (`mcpServers.stoaken`, URL only; Junie). With an API key: nothing, prints how to add it to `~/.junie/mcp/mcp.json` |
+| `cline` | Nothing: prints the steps for Cline's Remote Servers tab |
+| `lovable` | Nothing: prints the steps to add a custom MCP server (Connectors > Add custom) |
+| `bolt` | Nothing: prints the steps to add a custom connector (+ > Connectors) |
+| `replit` | Nothing: prints a one-click Replit install link and the manual steps |
 
 init merges: other servers in the file are kept and only the `stoaken` entry is replaced. If the
-file isn't plain JSON (for example `.vscode/mcp.json` with comments) it is left alone and you're told.
-No secret goes into these files, so they are safe to commit:
+file isn't plain JSON (for example `.vscode/mcp.json` or `.zed/settings.json` with comments) it is
+left alone and you're told. No secret goes into these files, so they are safe to commit:
 
 - Signed in with the browser: the entry has just the URL, and the tool signs you in itself with
-  OAuth (Claude Code `/mcp`, Cursor Connect, `codex mcp login stoaken`, VS Code Start).
+  OAuth (Claude Code `/mcp`, Cursor Connect, `codex mcp login stoaken`, VS Code Start,
+  `/mcp auth stoaken` in Gemini CLI, Authenticate in Devin Local, Zed's sign-in prompt, Junie's
+  `/mcp` Authorize).
 - Pasted an API key: the entry reads the `STOAKEN_API_KEY` environment variable (VS Code instead
-  asks for the key once and stores it securely).
+  asks for the key once and stores it securely). Devin Local, Zed and Junie document no variable
+  expansion in headers, so init never writes the key for them: Devin gets a gitignored
+  `.devin/mcp_config.local.json` override (`devin mcp add -s local ... -H`), and Zed and Junie are
+  told to use a user-level file outside the repo.
 
 ## Authentication
 
 Two paths, both landing on the same bearer credential:
 
-- **Log in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata), registers itself as an OAuth client on first run, and opens your browser to sign in.
-- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one at `/settings/api-keys` in the Stoaken app.
+- **Sign in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata) and opens your browser. You sign in as you do on the web, then a consent screen asks whether **Stoaken CLI** may use your account: check the name, then allow it. The terminal then says `Signed in as you@example.com.`
+  - From 0.5.1 the CLI identifies itself with a Client ID Metadata Document (`https://www.stoaken.com/oauth/cli-client.json`), so nothing is registered; if the server doesn't support that, it registers itself once (Dynamic Client Registration) and reuses that registration. Its redirect is `http://127.0.0.1:51820/callback`.
+  - It asks for a token for `https://www.stoaken.com/mcp` with `offline_access`, and saves the refresh token (with the server it came from) in `.stoaken/credentials.json`, `chmod 600`. `stoaken export` renews an expired sign-in itself; when that's no longer possible it says "Your Stoaken sign-in ended." Run `stoaken init` to sign in again.
+  - Browser sign-in has to be switched on for Stoaken's sign-in service. Until it is, use an API key.
+- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one in Settings › API keys in the Stoaken app.
+
+## Changes
+
+- **0.5.1** -- Browser sign-in uses a Client ID Metadata Document (Dynamic Client Registration as the fallback), asks for the /mcp resource and a refresh token, and renews itself. "Sign in" wording throughout.
 
 ## Export your tokens as code
 
@@ -101,7 +121,7 @@ Bitbucket Pipelines, Azure Pipelines and Vercel builds: see /docs/webhooks#ci an
 
 ## What this connects to
 
-Once set up, any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Copilot, v0) or a direct HTTP client can reach Stoaken's MCP server at `/mcp`. Its main tools (full list at /docs/mcp):
+Once set up, any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Copilot, v0, Devin Desktop, Zed, Gemini CLI, Junie, Cline, Lovable, Bolt, Replit) or a direct HTTP client can reach Stoaken's MCP server at `/mcp`. Its main tools (full list at /docs/mcp):
 
 - `list_brands` -- every Brand you hold at least Viewer on.
 - `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.

package/dist/index.js

@@ -14,7 +14,7 @@ import open from "open";
 
 // src/config.ts
 import { existsSync } from "fs";
-import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
+import { appendFile, chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { join } from "path";
 var CONFIG_FILE = "stoaken.config.json";
 var STOAKEN_DIR = ".stoaken";
@@ -40,9 +40,14 @@ async function ensureStoakenDir(cwd) {
 }
 async function writeCredentials(cwd, credentials) {
   await ensureStoakenDir(cwd);
-  const path = join(cwd, CREDENTIALS_FILE);
-  await writeFile(path, `${JSON.stringify(credentials, null, 2)}
-`, { encoding: "utf8", mode: 384 });
+  await writePrivate(join(cwd, CREDENTIALS_FILE), `${JSON.stringify(credentials, null, 2)}
+`);
+}
+async function writePrivate(path, text) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, text, { encoding: "utf8", mode: 384, flag: "wx" });
+  await chmod(tmp, 384);
+  await rename(tmp, path);
 }
 async function readCredentials(cwd) {
   try {
@@ -52,18 +57,23 @@ async function readCredentials(cwd) {
     return null;
   }
 }
-async function readOAuthClient(cwd) {
+async function readOAuthClient(cwd, authServer) {
   try {
     const raw = await readFile(join(cwd, OAUTH_CLIENT_FILE), "utf8");
-    return JSON.parse(raw);
+    const client = JSON.parse(raw);
+    return client.clientId && sameServer(client.authServer, authServer) ? client : null;
   } catch {
     return null;
   }
 }
 async function writeOAuthClient(cwd, client) {
   await ensureStoakenDir(cwd);
-  await writeFile(join(cwd, OAUTH_CLIENT_FILE), `${JSON.stringify(client, null, 2)}
-`, "utf8");
+  await writePrivate(join(cwd, OAUTH_CLIENT_FILE), `${JSON.stringify(client, null, 2)}
+`);
+}
+function sameServer(a, b) {
+  const norm = (u) => (u ?? "").trim().replace(/\/+$/, "").toLowerCase();
+  return Boolean(norm(a)) && norm(a) === norm(b);
 }
 async function writeSkillFile(cwd, content) {
   await ensureStoakenDir(cwd);
@@ -86,9 +96,18 @@ async function ensureGitignored(cwd) {
 `, "utf8");
 }
 
-// src/auth.ts
+// src/oauth-client.ts
 var CALLBACK_PORT = 51820;
 var REDIRECT_URI = `http://127.0.0.1:${CALLBACK_PORT}/callback`;
+var CLIENT_METADATA_PATH = "/oauth/cli-client.json";
+function cimdClientId(origin) {
+  return `${new URL(origin).origin}${CLIENT_METADATA_PATH}`;
+}
+var OAUTH_SCOPE = "openid offline_access";
+
+// src/auth.ts
+var SIGN_IN_ENDED = 'Your Stoaken sign-in ended. Run "stoaken init" to sign in again, or set STOAKEN_TOKEN to an API key.';
+var CALLBACK_TIMEOUT_MS = 5 * 60 * 1e3;
 async function discoverAuthorizationServer(serverUrl) {
   const metadataUrl = new URL("/.well-known/oauth-protected-resource", serverUrl);
   const response = await fetch(metadataUrl);
@@ -96,26 +115,44 @@ async function discoverAuthorizationServer(serverUrl) {
     throw new Error(`Failed to discover the authorization server (${response.status}) at ${metadataUrl}`);
   }
   const metadata = await response.json();
-  const authServer = metadata.authorization_servers?.[0];
-  if (!authServer) {
+  const issuer = metadata.authorization_servers?.[0]?.replace(/\/+$/, "");
+  if (!issuer) {
     throw new Error(`${metadataUrl} did not name an authorization server`);
   }
-  return authServer;
+  const as = await authServerMetadata(issuer);
+  return {
+    issuer,
+    resource: metadata.resource || new URL("/mcp", serverUrl).toString(),
+    authorize: as.authorization_endpoint ?? `${issuer}/oauth2/authorize`,
+    token: as.token_endpoint ?? `${issuer}/oauth2/token`,
+    register: as.registration_endpoint ?? `${issuer}/oauth2/register`,
+    cimd: as.client_id_metadata_document_supported
+  };
+}
+async function authServerMetadata(issuer) {
+  try {
+    const response = await fetch(`${issuer}/.well-known/oauth-authorization-server`);
+    return response.ok ? await response.json() : {};
+  } catch {
+    return {};
+  }
 }
-async function registerOAuthClient(authServer) {
-  const response = await fetch(`${authServer}/oauth2/register`, {
+var RegistrationRefused = class extends Error {
+};
+async function registerOAuthClient(server) {
+  const response = await fetch(server.register, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       client_name: "Stoaken CLI",
       redirect_uris: [REDIRECT_URI],
-      grant_types: ["authorization_code"],
+      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none"
     })
   });
   if (!response.ok) {
-    throw new Error(`Dynamic Client Registration failed (${response.status}): ${await response.text()}`);
+    throw new RegistrationRefused(`Dynamic Client Registration failed (${response.status}): ${await response.text()}`);
   }
   const data = await response.json();
   return data.client_id;
@@ -128,8 +165,15 @@ function generatePkce() {
   const challenge = base64url(createHash("sha256").update(verifier).digest());
   return { verifier, challenge };
 }
-function waitForCallback() {
+var ClientRefused = class extends Error {
+};
+var CLIENT_ERRORS = /* @__PURE__ */ new Set(["invalid_client", "unauthorized_client"]);
+function waitForCallback(state) {
   return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error('Sign-in timed out. Run "stoaken init" to try again.'));
+    }, CALLBACK_TIMEOUT_MS);
     const server = createServer((req, res) => {
       const url = new URL(req.url ?? "/", REDIRECT_URI);
       if (url.pathname !== "/callback") {
@@ -138,64 +182,148 @@ function waitForCallback() {
       }
       const code = url.searchParams.get("code");
       const error = url.searchParams.get("error");
+      if (url.searchParams.get("state") !== state) {
+        res.writeHead(400, { "Content-Type": "text/html" }).end("<p>That isn't the answer to this sign-in.</p>");
+        return;
+      }
       res.writeHead(200, { "Content-Type": "text/html" });
       res.end(
-        error ? "<p>Login failed. You can close this tab and return to the terminal.</p>" : "<p>Login complete -- you can close this tab and return to the terminal.</p>"
+        error || !code ? "<p>Sign-in failed. You can close this tab and return to the terminal.</p>" : "<p>Signed in. You can close this tab and return to the terminal.</p>"
       );
+      clearTimeout(timer);
       server.close();
       if (error) {
-        reject(new Error(`WorkOS returned an error: ${error}`));
+        const why = `WorkOS returned an error: ${error}`;
+        reject(CLIENT_ERRORS.has(error) ? new ClientRefused(why) : new Error(why));
       } else if (!code) {
         reject(new Error("No authorization code in the callback"));
       } else {
         resolve2(code);
       }
     });
-    server.on("error", reject);
+    server.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
     server.listen(CALLBACK_PORT, "127.0.0.1");
   });
 }
-async function exchangeCodeForToken(authServer, clientId, code, verifier) {
-  const response = await fetch(`${authServer}/oauth2/token`, {
+async function tokenRequest(server, params) {
+  const response = await fetch(server.token, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      grant_type: "authorization_code",
-      code,
-      redirect_uri: REDIRECT_URI,
-      client_id: clientId,
-      code_verifier: verifier
-    })
+    body: new URLSearchParams({ ...params, resource: server.resource })
   });
   if (!response.ok) {
-    throw new Error(`Token exchange failed (${response.status}): ${await response.text()}`);
+    const text = await response.text();
+    const why = `Token exchange failed (${response.status}): ${text}`;
+    throw CLIENT_ERRORS.has(errorCode(text)) ? new ClientRefused(why) : new Error(why);
   }
-  const data = await response.json();
-  return data.access_token;
+  return await response.json();
 }
-async function loginWithBrowser(cwd, serverUrl) {
-  const authServer = await discoverAuthorizationServer(serverUrl);
-  let clientId = (await readOAuthClient(cwd))?.clientId;
-  if (!clientId) {
-    clientId = await registerOAuthClient(authServer);
-    await writeOAuthClient(cwd, { clientId });
+function errorCode(text) {
+  try {
+    return String(JSON.parse(text).error ?? "");
+  } catch {
+    return "";
+  }
+}
+function credentialsFrom(data, server, clientId, serverUrl, now = Date.now()) {
+  return {
+    kind: "oauth",
+    token: data.access_token,
+    ...data.refresh_token ? { refreshToken: data.refresh_token } : {},
+    ...typeof data.expires_in === "number" ? { expiresAt: now + data.expires_in * 1e3 } : {},
+    authServer: server.issuer,
+    clientId,
+    serverUrl
+  };
+}
+function tokenEmail(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+    return typeof payload.email === "string" ? payload.email : null;
+  } catch {
+    return null;
   }
+}
+async function authorizeWith(server, clientId) {
   const { verifier, challenge } = generatePkce();
-  const authorizeUrl = new URL("/oauth2/authorize", authServer);
+  const state = base64url(randomBytes(16));
+  const authorizeUrl = new URL(server.authorize);
   authorizeUrl.searchParams.set("client_id", clientId);
   authorizeUrl.searchParams.set("redirect_uri", REDIRECT_URI);
   authorizeUrl.searchParams.set("response_type", "code");
   authorizeUrl.searchParams.set("code_challenge", challenge);
   authorizeUrl.searchParams.set("code_challenge_method", "S256");
-  const callbackPromise = waitForCallback();
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("scope", OAUTH_SCOPE);
+  authorizeUrl.searchParams.set("resource", server.resource);
+  const callbackPromise = waitForCallback(state);
   await open(authorizeUrl.toString());
-  p.log.info(`Opened your browser to sign in. Waiting for you to finish...`);
-  const code = await callbackPromise;
-  return exchangeCodeForToken(authServer, clientId, code, verifier);
+  return { code: await callbackPromise, verifier };
+}
+async function dcrClient(cwd, server) {
+  const cached = await readOAuthClient(cwd, server.issuer);
+  if (cached) return cached.clientId;
+  let clientId;
+  try {
+    clientId = await registerOAuthClient(server);
+  } catch (error) {
+    if (error instanceof RegistrationRefused) {
+      throw new Error("Browser sign-in isn't switched on for this Stoaken server yet. Paste an API key instead (Settings \u203A API keys).");
+    }
+    throw error;
+  }
+  await writeOAuthClient(cwd, { clientId, authServer: server.issuer });
+  return clientId;
+}
+async function loginWithBrowser(cwd, serverUrl) {
+  const server = await discoverAuthorizationServer(serverUrl);
+  const signIn = async (clientId) => {
+    const { code, verifier } = await authorizeWith(server, clientId);
+    const data = await tokenRequest(server, { grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI, client_id: clientId, code_verifier: verifier });
+    return credentialsFrom(data, server, clientId, serverUrl);
+  };
+  let credentials;
+  if (server.cimd) {
+    try {
+      credentials = await signIn(cimdClientId(new URL(server.resource).origin));
+    } catch (error) {
+      if (!(error instanceof ClientRefused)) throw error;
+      p.log.info("Stoaken's sign-in didn't accept the CLI's published client. Trying again with a registered one...");
+      credentials = await signIn(await dcrClient(cwd, server));
+    }
+  } else {
+    credentials = await signIn(await dcrClient(cwd, server));
+  }
+  return { credentials, email: tokenEmail(credentials.token) };
+}
+function needsRefresh(credentials, now = Date.now()) {
+  return credentials.kind === "oauth" && typeof credentials.expiresAt === "number" && now >= credentials.expiresAt - 6e4;
+}
+async function freshCredentials(cwd, serverUrl) {
+  const saved = await readCredentials(cwd);
+  if (!saved || saved.kind !== "oauth") return saved;
+  if (saved.serverUrl && !sameServer(saved.serverUrl, serverUrl)) {
+    throw new Error(`Your saved sign-in is for ${saved.serverUrl}, not ${serverUrl}. Run "stoaken init" to sign in again, or set STOAKEN_TOKEN to an API key.`);
+  }
+  if (!needsRefresh(saved)) return saved;
+  if (!saved.refreshToken || !saved.authServer || !saved.clientId) throw new Error(SIGN_IN_ENDED);
+  try {
+    const server = await discoverAuthorizationServer(saved.serverUrl ?? serverUrl);
+    if (!sameServer(server.issuer, saved.authServer)) throw new Error("authorization server changed");
+    const data = await tokenRequest(server, { grant_type: "refresh_token", refresh_token: saved.refreshToken, client_id: saved.clientId });
+    const next = credentialsFrom({ refresh_token: saved.refreshToken, ...data }, server, saved.clientId, saved.serverUrl ?? serverUrl);
+    await writeCredentials(cwd, next);
+    return next;
+  } catch {
+    throw new Error(SIGN_IN_ENDED);
+  }
 }
 async function promptForApiKey() {
   const key = await p.password({
-    message: "Paste your Stoaken API key (from /settings/api-keys):",
+    message: "Paste your Stoaken API key (Settings \u203A API keys):",
     validate: (value) => {
       if (!value?.startsWith("stk_") && !value?.startsWith("twk_")) {
         return "That doesn't look like a Stoaken API key (should start with stk_)";
@@ -214,7 +342,7 @@ async function listBrands(serverUrl, credential) {
   const transport = new StreamableHTTPClientTransport(new URL("/mcp", serverUrl), {
     requestInit: { headers: { Authorization: `Bearer ${credential}` } }
   });
-  const client = new Client({ name: "stoaken-cli", version: "0.4.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.5.1" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -229,7 +357,22 @@ async function listBrands(serverUrl, credential) {
 }
 
 // src/client-config.ts
-var CLIENTS = ["claude-code", "claude-desktop", "cursor", "codex", "copilot", "v0"];
+var CLIENTS = [
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "codex",
+  "copilot",
+  "v0",
+  "windsurf",
+  "zed",
+  "gemini-cli",
+  "jetbrains",
+  "cline",
+  "lovable",
+  "bolt",
+  "replit"
+];
 var SERVER_NAME = "stoaken";
 var API_KEY_ENV = "STOAKEN_API_KEY";
 var CLIENT_LABELS = {
@@ -238,17 +381,43 @@ var CLIENT_LABELS = {
   cursor: "Cursor",
   codex: "OpenAI Codex",
   copilot: "GitHub Copilot (VS Code)",
-  v0: "v0 (Vercel)"
+  v0: "v0 (Vercel)",
+  windsurf: "Windsurf / Devin Desktop",
+  zed: "Zed",
+  "gemini-cli": "Gemini CLI",
+  jetbrains: "JetBrains (Junie)",
+  cline: "Cline",
+  lovable: "Lovable",
+  bolt: "Bolt (bolt.new)",
+  replit: "Replit Agent"
+};
+var JSON_CLIENTS = ["claude-code", "cursor", "copilot", "windsurf", "zed", "gemini-cli", "jetbrains"];
+var SERVERS_KEY = {
+  "claude-code": "mcpServers",
+  cursor: "mcpServers",
+  copilot: "servers",
+  windsurf: "mcpServers",
+  zed: "context_servers",
+  "gemini-cli": "mcpServers",
+  jetbrains: "mcpServers"
 };
 function isClient(value) {
   return CLIENTS.includes(value);
 }
+function isJsonClient(client) {
+  return JSON_CLIENTS.includes(client);
+}
 function mcpUrl(serverUrl) {
   return `${serverUrl.replace(/\/+$/, "")}/mcp`;
 }
+function replitInstallLink(serverUrl) {
+  const json = JSON.stringify({ displayName: "Stoaken", baseUrl: mcpUrl(serverUrl) });
+  return `https://replit.com/integrations?mcp=${Buffer.from(json, "utf8").toString("base64")}`;
+}
 function planFor(client, auth, serverUrl) {
   const url = mcpUrl(serverUrl);
   const keyStep = `Set ${API_KEY_ENV} in your shell to an API key from Settings > API keys (never commit it).`;
+  const oauthInstead = "Or run init again, sign in with the browser, and use OAuth instead.";
   switch (client) {
     case "claude-code":
       return {
@@ -268,7 +437,8 @@ function planFor(client, auth, serverUrl) {
     case "copilot":
       return {
         file: ".vscode/mcp.json",
-        nextSteps: auth === "oauth" ? ["In VS Code open .vscode/mcp.json, click Start above stoaken and sign in in the browser.", "Use Copilot Chat in Agent mode."] : ["In VS Code open .vscode/mcp.json, click Start above stoaken and paste an API key when asked (VS Code stores it securely).", "Use Copilot Chat in Agent mode."]
+        nextSteps: auth === "oauth" ? ["In VS Code open .vscode/mcp.json, click Start above stoaken and sign in in the browser.", "Use Copilot Chat in Agent mode."] : ["In VS Code open .vscode/mcp.json, click Start above stoaken and paste an API key when asked (VS Code stores it securely).", "Use Copilot Chat in Agent mode."],
+        keyNote: "VS Code asks for the key once and stores it securely"
       };
     case "claude-desktop":
       return {
@@ -290,10 +460,104 @@ function planFor(client, auth, serverUrl) {
           "v0 uses the tools while it generates; the app it builds cannot call them."
         ]
       };
+    case "windsurf":
+      return {
+        file: ".devin/mcp_config.json",
+        nextSteps: auth === "oauth" ? [
+          "Open this project in Devin Desktop (formerly Windsurf) with the Devin Local agent. Devin CLI reads the same file.",
+          "When stoaken shows Needs auth in the MCP list, click Authenticate (or run: devin mcp login stoaken)."
+        ] : [
+          keyStep,
+          `Devin documents no variable expansion in MCP headers, so add the key to the gitignored local override: devin mcp add -s local stoaken ${url} -H "Authorization: Bearer $${API_KEY_ENV}"`,
+          "That override replaces the project entry for you only. The legacy Cascade agent ignores project files (see the guide)."
+        ],
+        keyNote: "the key goes in the gitignored `.devin/mcp_config.local.json` override"
+      };
+    case "zed":
+      return auth === "oauth" ? {
+        file: ".zed/settings.json",
+        nextSteps: [
+          "Trust this project in Zed: in Restricted Mode project settings and their MCP servers don't load.",
+          "Zed asks you to sign in to stoaken (MCP OAuth). Settings > AI > MCP Servers shows a green dot when it's active."
+        ]
+      } : {
+        file: null,
+        nextSteps: [
+          "Zed documents no variable expansion in headers, so the key can't go in a project file.",
+          `Run "zed: open settings file" and add under "context_servers": "stoaken": { "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`,
+          oauthInstead
+        ]
+      };
+    case "gemini-cli":
+      return {
+        file: ".gemini/settings.json",
+        nextSteps: auth === "oauth" ? ["Trust this folder (gemini trust): untrusted folders ignore .gemini/settings.json.", "In Gemini CLI run /mcp auth stoaken to sign in in the browser."] : [keyStep, "Trust this folder (gemini trust): untrusted folders ignore .gemini/settings.json."]
+      };
+    case "jetbrains":
+      return auth === "oauth" ? {
+        file: ".junie/mcp/mcp.json",
+        nextSteps: [
+          "Junie in the IDE: Settings > Tools > Junie > MCP Settings lists stoaken and its status.",
+          "Junie CLI: run /mcp, select stoaken, choose Authorize and sign in in the browser."
+        ]
+      } : {
+        file: null,
+        nextSteps: [
+          "Junie has no secret storage or variable expansion for MCP configs, so the key can't go in a project file.",
+          `In your user file ~/.junie/mcp/mcp.json, under "mcpServers", add "stoaken": { "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`,
+          oauthInstead
+        ]
+      };
+    case "cline":
+      return {
+        file: null,
+        nextSteps: [
+          "Cline keeps MCP servers in its own settings, not a project file.",
+          ...auth === "oauth" ? [
+            `Cline panel > MCP Servers > Remote Servers: name stoaken, URL ${url}, transport Streamable HTTP, Add Server.`,
+            "If it asks you to authenticate, sign in in the browser (Cline CLI: cline mcp > Authorize OAuth)."
+          ] : [
+            `Cline panel > MCP Servers > Configure > Configure MCP Servers, and add under "mcpServers": "stoaken": { "type": "streamableHttp", "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`
+          ]
+        ]
+      };
+    case "lovable":
+      return {
+        file: null,
+        nextSteps: [
+          "Lovable adds MCP servers in its own UI, not through a project file.",
+          "Connectors > Add custom > MCP server. Server name: Stoaken.",
+          `Server URL: ${url}. Authentication: OAuth (Add & authorize), or Bearer token with an API key.`,
+          "The connection is yours alone and only for Lovable's chat; the app it publishes can't call it."
+        ]
+      };
+    case "bolt":
+      return {
+        file: null,
+        nextSteps: [
+          "Bolt adds MCP servers in its own UI, not through a project file.",
+          "In the chatbox: + > Connectors > Manage connectors > Custom MCP server.",
+          `Name: Stoaken. URL: ${url}. Transport type: HTTP. Authentication: MCP OAuth.`,
+          "Then turn the connector on for the project (+ > Connectors)."
+        ]
+      };
+    case "replit":
+      return {
+        file: null,
+        nextSteps: [
+          "Replit adds MCP servers in its own UI, not through a project file.",
+          `Open ${replitInstallLink(serverUrl)} (or Integrations > MCP Servers > + Add MCP server, URL ${url}).`,
+          auth === "oauth" ? "Click Test & save and sign in when Replit runs the OAuth flow." : "Under Advanced settings add the header Authorization: Bearer <API key>, then Test & save."
+        ]
+      };
   }
 }
 function jsonEntry(client, auth, serverUrl) {
   const url = mcpUrl(serverUrl);
+  if (client === "windsurf" || client === "zed" || client === "jetbrains") return { url };
+  if (client === "gemini-cli") {
+    return auth === "oauth" ? { httpUrl: url } : { httpUrl: url, headers: { Authorization: `Bearer \${${API_KEY_ENV}}` } };
+  }
   if (client === "claude-code") {
     return auth === "oauth" ? { type: "http", url } : { type: "http", url, headers: { Authorization: `Bearer \${${API_KEY_ENV}}` } };
   }
@@ -325,8 +589,9 @@ var COPILOT_INPUT = {
 };
 function mergeJsonConfig(client, existing, auth, serverUrl) {
   const file = planFor(client, auth, serverUrl).file;
+  if (file === null) throw new ConfigMergeError(`${CLIENT_LABELS[client]} gets no project file with an API key; follow the steps instead.`);
   const doc = parseObject(existing, file);
-  const key = client === "copilot" ? "servers" : "mcpServers";
+  const key = SERVERS_KEY[client];
   const current = doc[key];
   if (current !== void 0 && (typeof current !== "object" || current === null || Array.isArray(current))) {
     throw new ConfigMergeError(`${file} has a "${key}" that isn't an object, so it was left alone.`);
@@ -377,7 +642,7 @@ file -- it's already in \`.gitignore\`).
   }
   const { client, auth } = target;
   const plan = planFor(client, auth, serverUrl);
-  const how = auth === "oauth" ? "the client signs in with OAuth" : `it reads the \`${API_KEY_ENV}\` environment variable`;
+  const how = auth === "oauth" ? "the client signs in with OAuth" : plan.keyNote ?? `it reads the \`${API_KEY_ENV}\` environment variable`;
   const where = plan.file ? `It is configured for ${CLIENT_LABELS[client]} in \`${plan.file}\` (no secret in that file: ${how}).` : `${CLIENT_LABELS[client]} connects through its own settings, not a project file.`;
   return `${where}
 
@@ -451,7 +716,7 @@ async function runInit(options) {
       options: [
         { value: "continue", label: `Continue with ${existing.brandName}` },
         { value: "switch", label: "Switch Brand" },
-        { value: "reauth", label: "Re-authenticate" }
+        { value: "reauth", label: "Sign in again" }
       ]
     });
     if (p2.isCancel(choice)) {
@@ -462,13 +727,12 @@ async function runInit(options) {
       skipToWrite = { brandId: existing.brandId, brandName: existing.brandName };
     }
   }
-  let credential;
-  let credentialKind;
+  let saved;
   if (!skipToWrite) {
     const authChoice = await p2.select({
       message: "How would you like to sign in?",
       options: [
-        { value: "browser", label: "Log in with browser" },
+        { value: "browser", label: "Sign in with browser" },
         { value: "key", label: "Paste an API key" }
       ]
     });
@@ -477,12 +741,13 @@ async function runInit(options) {
       return;
     }
     if (authChoice === "browser") {
+      p2.log.info("Opening your browser to sign in to Stoaken. It will ask whether Stoaken CLI may use your account. Check the name, then allow it.");
       const s2 = p2.spinner();
       s2.start("Waiting for you to finish signing in...");
       try {
-        credential = await loginWithBrowser(cwd, serverUrl);
-        credentialKind = "oauth";
-        s2.stop("Signed in.");
+        const { credentials, email } = await loginWithBrowser(cwd, serverUrl);
+        saved = credentials;
+        s2.stop(email ? `Signed in as ${email}.` : "Signed in.");
       } catch (error) {
         s2.stop("Sign-in failed.");
         p2.log.error(error instanceof Error ? error.message : String(error));
@@ -494,14 +759,13 @@ async function runInit(options) {
         p2.cancel("Cancelled.");
         return;
       }
-      credential = key;
-      credentialKind = "api_key";
+      saved = { kind: "api_key", token: key };
     }
     const s = p2.spinner();
     s.start("Fetching your Brands...");
     let brands;
     try {
-      brands = await listBrands(serverUrl, credential);
+      brands = await listBrands(serverUrl, saved.token);
     } catch (error) {
       s.stop("Failed to reach Stoaken.");
       p2.log.error(error instanceof Error ? error.message : String(error));
@@ -521,7 +785,7 @@ async function runInit(options) {
       return;
     }
     const brand = brands.find((b) => b.id === brandChoice);
-    await writeCredentials(cwd, { kind: credentialKind, token: credential });
+    await writeCredentials(cwd, saved);
     skipToWrite = { brandId: brand.id, brandName: brand.name };
   }
   const keepExports = existing?.brandId === skipToWrite.brandId && existing.exports !== void 0;
@@ -557,6 +821,7 @@ async function runInit(options) {
       const path = join2(cwd, plan.file);
       const existingText = existsSync2(path) ? await readFile2(path, "utf8") : null;
       try {
+        if (client !== "codex" && !isJsonClient(client)) throw new Error(`No file writer for ${client}.`);
         const next = client === "codex" ? mergeCodexToml(existingText, auth, serverUrl) : mergeJsonConfig(client, existingText, auth, serverUrl);
         await mkdir2(dirname(path), { recursive: true });
         await writeFile2(path, next, "utf8");
@@ -590,7 +855,7 @@ async function call(serverUrl, token, path) {
   let response;
   try {
     response = await fetch(new URL(path, serverUrl), {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.4.0" }
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.5.1" }
     });
   } catch (error) {
     throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
@@ -795,7 +1060,7 @@ async function runExport(argv) {
     if (!config) throw new ExportUsageError('No stoaken.config.json here. Run "stoaken init" in your project first.');
     const serverUrl = args.server ?? config.serverUrl;
     const envToken = process.env.STOAKEN_TOKEN?.trim();
-    const token = envToken || (await readCredentials(cwd))?.token;
+    const token = envToken || (await freshCredentials(cwd, serverUrl))?.token;
     if (!token) throw new ExportUsageError('No credentials. Run "stoaken init", or set STOAKEN_TOKEN to an API key.');
     const targets = args.target ? [args.target] : readSavedTargets(config.exports);
     if (targets.length === 0) targets.push({ format: "css" });
@@ -901,7 +1166,7 @@ switch (command) {
         "",
         "Usage:",
         "  stoaken init [--server <url>] [--client <name>]",
-        "                                  Authenticate, pick a Brand, and connect an AI tool",
+        "                                  Sign in, pick a Brand, and connect an AI tool",
         `                                  (${CLIENTS.join(", ")})`,
         "  stoaken export [options]        Write your tokens as code (stoaken export --help)"
       ].join("\n")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stoaken",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
   "license": "UNLICENSED",
   "type": "module",
@@ -39,13 +39,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
-    "open": "^11.0.2",
-    "@modelcontextprotocol/client": "^2.4.0"
+    "@modelcontextprotocol/client": "^2.4.0",
+    "open": "^11.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.5.0",
-    "tsup": "^8.5.1",
+    "tsup": "^9.0.0",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2"
+  },
+  "overrides": {
+    "esbuild": "0.28.2"
   }
 }