stoaken 0.3.0 → 0.5.0

package/README.md

@@ -1,85 +1,127 @@
-# stoaken
-
-The official CLI for [Stoaken](https://www.stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
-
-## Quickstart
-
-```
-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`.
-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. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents (Claude Code, Cursor) explaining how to connect to this project's Stoaken 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.
-
-## 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.
-
-## Export your tokens as code
-
-`stoaken export` writes a theme's live release as a file: CSS variables, W3C JSON, Style
-Dictionary v4 JSON, or a JS/TS module. There are no timestamps in the output, so committed files
-give clean diffs.
-
-```sh
-npx stoaken export --theme Default --format css --out src/styles/tokens.css
-npx stoaken export --theme Default --format json-dtcg --mode color-scheme:dark --out tokens/dark.json
-npx stoaken export --theme Default --format ts --out src/tokens.ts
-npx stoaken export --theme Default --out -        # to stdout
-```
-
-| Option | |
-| --- | --- |
-| `--theme <name\|id>` | Which theme (needed when the Brand has more than one) |
-| `--format` | `css` (default), `json-dtcg`, `json-sd4`, `js`, `ts` |
-| `--mode <key>` | A mode combination for the one-mode formats; CSS includes every mode |
-| `--prefix <prefix>` | CSS only: a prefix for every variable name |
-| `--release <id>` | One release (e.g. one still in review) instead of the live one |
-| `--out <file\|->` | Where to write; default is the server's file name |
-| `--check` | Write nothing; exit 1 if the file on disk is out of date |
-
-Save your targets in `stoaken.config.json` and a plain `npx stoaken export` runs them all
-(`npx stoaken export --check` checks them all):
-
-```json
-{
-  "brandId": "…",
-  "brandName": "Acme",
-  "serverUrl": "https://www.stoaken.com",
-  "exports": [
-    { "theme": "Default", "format": "css", "out": "src/styles/tokens.css" },
-    { "theme": "Default", "format": "ts", "out": "src/tokens.ts" }
-  ]
-}
-```
-
-**In CI**, set `STOAKEN_TOKEN` to an API key (Settings > API keys); it's used instead of the
-sign-in saved by `stoaken init`. For example, to fail a build when the committed tokens are behind
-the live release:
-
-```sh
-STOAKEN_TOKEN=${{ secrets.STOAKEN_TOKEN }} npx stoaken export --check
-```
-
-## What this connects to
-
-Once set up, any MCP-capable client (Claude Code, Cursor, Claude Desktop) or a direct HTTP client can use the credential in `.stoaken/credentials.json` as a Bearer token against Stoaken's MCP server, which exposes four tools:
-
-- `list_brands` -- every Brand you hold at least Viewer on.
-- `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.
-- `list_releases(themeId)` -- a Theme's Releases with version, status, and change summary.
-- `propose_token_change(themeId, tokenSetId, document, version, versionType)` -- proposes a token change and submits it for approval. **This never publishes.** A human reviewer always approves through the Stoaken Command Center before it goes live.
-
-## Links
-
-- [Stoaken on GitHub](https://github.com/craig-astravale/stoaken)
-- [Report an issue](https://github.com/craig-astravale/stoaken/issues)
+# stoaken
+
+The official CLI for [Stoaken](https://www.stoaken.com) -- a design token management platform (Brands, Token Sets, Themes, DTCG-conformant token storage, versioned Releases with an approval gate) that AI coding agents and MCP-capable tools can read and propose changes to directly.
+
+## Quickstart
+
+```
+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`.
+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.
+
+## Connect an AI tool
+
+```
+npx stoaken init --client cursor
+```
+
+| `--client` | What init writes |
+| --- | --- |
+| `claude-code` | `.mcp.json` (`mcpServers.stoaken`, `type: http`) |
+| `cursor` | `.cursor/mcp.json` (`mcpServers.stoaken`) |
+| `codex` | `.codex/config.toml` (`[mcp_servers.stoaken]`; loads for trusted projects only) |
+| `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` 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,
+  `/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). 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.
+
+## Export your tokens as code
+
+`stoaken export` writes a theme's live release as a file: CSS variables, W3C JSON, Style
+Dictionary v4 JSON, or a JS/TS module. There are no timestamps in the output, so committed files
+give clean diffs.
+
+```sh
+npx stoaken export --theme Default --format css --out src/styles/tokens.css
+npx stoaken export --theme Default --format json-dtcg --mode color-scheme:dark --out tokens/dark.json
+npx stoaken export --theme Default --format ts --out src/tokens.ts
+npx stoaken export --theme Default --out -        # to stdout
+```
+
+| Option | |
+| --- | --- |
+| `--theme <name\|id>` | Which theme (needed when the Brand has more than one) |
+| `--format` | `css` (default), `json-dtcg`, `json-sd4`, `js`, `ts` |
+| `--mode <key>` | A mode combination for the one-mode formats; CSS includes every mode |
+| `--prefix <prefix>` | CSS only: a prefix for every variable name |
+| `--release <id>` | One release (e.g. one still in review) instead of the live one |
+| `--out <file\|->` | Where to write; default is the server's file name |
+| `--check` | Write nothing; exit 1 if the file on disk is out of date |
+
+Save your targets in `stoaken.config.json` and a plain `npx stoaken export` runs them all
+(`npx stoaken export --check` checks them all):
+
+```json
+{
+  "brandId": "…",
+  "brandName": "Acme",
+  "serverUrl": "https://www.stoaken.com",
+  "exports": [
+    { "theme": "Default", "format": "css", "out": "src/styles/tokens.css" },
+    { "theme": "Default", "format": "ts", "out": "src/tokens.ts" }
+  ]
+}
+```
+
+**In CI**, set `STOAKEN_TOKEN` to an API key (Settings > API keys); it's used instead of the
+sign-in saved by `stoaken init`. For example, to fail a build when the committed tokens are behind
+the live release:
+
+```sh
+STOAKEN_TOKEN=${{ secrets.STOAKEN_TOKEN }} npx stoaken export --check
+```
+
+`--check` ignores CRLF vs LF line endings (unreleased change, Stage 332), so Windows runners
+that check files out as CRLF don't fail it. Ready-made pipelines for GitHub Actions, GitLab CI,
+Bitbucket Pipelines, Azure Pipelines and Vercel builds: see /docs/webhooks#ci and /docs/cli#ci.
+
+## What this connects to
+
+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.
+- `list_releases(themeId)` -- a Theme's Releases with version, status, and change summary.
+- `propose_token_change(themeId, tokenSetId, document, version, versionType)` -- proposes a token change and submits it for approval. **This never publishes.** A human reviewer always approves through the Stoaken Command Center before it goes live.
+
+## Links
+
+- [Stoaken on GitHub](https://github.com/craig-astravale/stoaken)
+- [Report an issue](https://github.com/craig-astravale/stoaken/issues)

package/dist/index.js

@@ -209,13 +209,12 @@ async function promptForApiKey() {
 }
 
 // src/mcp-client.ts
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 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.3.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.5.0" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -229,16 +228,306 @@ async function listBrands(serverUrl, credential) {
   }
 }
 
+// src/client-config.ts
+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 = {
+  "claude-code": "Claude Code",
+  "claude-desktop": "Claude Desktop / claude.ai",
+  cursor: "Cursor",
+  codex: "OpenAI Codex",
+  copilot: "GitHub Copilot (VS Code)",
+  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 {
+        file: ".mcp.json",
+        nextSteps: auth === "oauth" ? ["Start Claude Code, approve the project server, then run /mcp and choose stoaken to sign in."] : [keyStep, "Start Claude Code and approve the project server."]
+      };
+    case "cursor":
+      return {
+        file: ".cursor/mcp.json",
+        nextSteps: auth === "oauth" ? ["Open Cursor Settings > MCP, enable stoaken and click Connect to sign in."] : [keyStep, "Restart Cursor so it picks up the variable, then enable stoaken in Settings > MCP."]
+      };
+    case "codex":
+      return {
+        file: ".codex/config.toml",
+        nextSteps: auth === "oauth" ? ["Trust this project in Codex (project config only loads for trusted projects).", "Run: codex mcp login stoaken"] : [keyStep, "Trust this project in Codex (project config only loads for trusted projects)."]
+      };
+    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."],
+        keyNote: "VS Code asks for the key once and stores it securely"
+      };
+    case "claude-desktop":
+      return {
+        file: null,
+        nextSteps: [
+          "Claude Desktop and claude.ai add remote servers as connectors, not through a project file.",
+          "Customize > Connectors > + Add > Add custom connector.",
+          `Name: Stoaken. URL: ${url}. Sign in with OAuth (Register automatically), or add the header Authorization: Bearer <API key>.`,
+          "On Team/Enterprise only an Owner can add it. Connections come from Anthropic's cloud, so this needs the public server."
+        ]
+      };
+    case "v0":
+      return {
+        file: null,
+        nextSteps: [
+          "v0 adds MCP servers in its own UI, not through a project file.",
+          "In a v0 chat: + > MCPs > custom server.",
+          `URL: ${url}. Auth: OAuth, or Bearer Token with an API key from Settings > API keys.`,
+          "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}}` } };
+  }
+  if (client === "cursor") {
+    return auth === "oauth" ? { url } : { url, headers: { Authorization: `Bearer \${env:${API_KEY_ENV}}` } };
+  }
+  return auth === "oauth" ? { type: "http", url } : { type: "http", url, headers: { Authorization: "Bearer ${input:stoaken-api-key}" } };
+}
+var ConfigMergeError = class extends Error {
+};
+function parseObject(existing, file) {
+  if (existing === null || existing.trim() === "") return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    throw new ConfigMergeError(`${file} isn't plain JSON (comments?), so it was left alone. Add the stoaken entry by hand.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ConfigMergeError(`${file} isn't a JSON object, so it was left alone.`);
+  }
+  return parsed;
+}
+var COPILOT_INPUT = {
+  type: "promptString",
+  id: "stoaken-api-key",
+  description: "Stoaken API key (Settings > API keys)",
+  password: true
+};
+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 = 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.`);
+  }
+  doc[key] = { ...current, [SERVER_NAME]: jsonEntry(client, auth, serverUrl) };
+  if (client === "copilot") {
+    const inputs = Array.isArray(doc.inputs) ? doc.inputs : [];
+    const others = inputs.filter((i) => !(typeof i === "object" && i !== null && i.id === COPILOT_INPUT.id));
+    if (auth === "api_key") doc.inputs = [...others, COPILOT_INPUT];
+    else if (doc.inputs !== void 0) doc.inputs = others;
+  }
+  return `${JSON.stringify(doc, null, 2)}
+`;
+}
+function codexTable(auth, serverUrl) {
+  const lines = [`[mcp_servers.${SERVER_NAME}]`, `url = ${JSON.stringify(mcpUrl(serverUrl))}`];
+  if (auth === "api_key") lines.push(`bearer_token_env_var = "${API_KEY_ENV}"`);
+  return `${lines.join("\n")}
+`;
+}
+function mergeCodexToml(existing, auth, serverUrl) {
+  const table = codexTable(auth, serverUrl);
+  if (existing === null || existing.trim() === "") return table;
+  const header = /^\s*\[\s*mcp_servers\.(?:stoaken|"stoaken")\s*(?:\]|\.)/;
+  const anyHeader = /^\s*\[/;
+  const kept = [];
+  let skipping = false;
+  for (const line of existing.split("\n")) {
+    if (header.test(line)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && anyHeader.test(line)) skipping = false;
+    if (!skipping) kept.push(line);
+  }
+  const body = kept.join("\n").replace(/\n+$/, "");
+  return body === "" ? table : `${body}
+
+${table}`;
+}
+
 // src/skill-template.ts
-function generateSkillFile(config) {
+function connectSection(target, serverUrl) {
+  if (!target) {
+    return `Connect with the credential in \`.stoaken/credentials.json\` as a Bearer token (never commit that
+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" : 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}
+
+${plan.nextSteps.map((step) => `- ${step}`).join("\n")}
+`;
+}
+function generateSkillFile(config, client) {
   return `# Working with Stoaken
 
 This project is connected to the **${config.brandName}** Brand on Stoaken (\`${config.serverUrl}\`).
 
-Stoaken's MCP server exposes the tools below. Connect to it at \`${config.serverUrl}/mcp\` using
-the credential in \`.stoaken/credentials.json\` as a Bearer token (never commit that file --
-it's already in \`.gitignore\`).
-
+Stoaken's MCP server exposes the tools below at \`${mcpUrl(config.serverUrl)}\`.
+${connectSection(client, config.serverUrl)}
 ## Tools
 
 - **list_brands** -- every Brand you hold at least Viewer on.
@@ -283,6 +572,9 @@ Re-run \`stoaken init\` if you need to switch Brands or re-authenticate.
 }
 
 // src/commands/init.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname, join as join2 } from "path";
 var DEFAULT_SERVER_URL = "https://www.stoaken.com";
 async function runInit(options) {
   const cwd = process.cwd();
@@ -378,13 +670,49 @@ async function runInit(options) {
   };
   await writeConfig(cwd, config);
   await ensureGitignored(cwd);
-  await writeSkillFile(cwd, generateSkillFile(config));
+  let client = null;
+  if (options.client) {
+    client = options.client;
+  } else {
+    const pick = await p2.select({
+      message: "Which AI tool should connect to Stoaken?",
+      options: [
+        ...CLIENTS.map((c) => ({ value: c, label: CLIENT_LABELS[c] })),
+        { value: "none", label: "None for now (just write .stoaken/SKILL.md)" }
+      ]
+    });
+    if (p2.isCancel(pick)) {
+      p2.cancel("Cancelled.");
+      return;
+    }
+    client = pick === "none" ? null : pick;
+  }
+  const auth = (await readCredentials(cwd))?.kind === "api_key" ? "api_key" : "oauth";
+  if (client) {
+    const plan = planFor(client, auth, serverUrl);
+    if (plan.file) {
+      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");
+        p2.log.success(`${existingText === null ? "Wrote" : "Updated"} ${plan.file} (other servers kept).`);
+      } catch (error) {
+        if (!(error instanceof ConfigMergeError)) throw error;
+        p2.log.warn(error.message);
+      }
+    }
+    p2.note(plan.nextSteps.map((s) => `- ${s}`).join("\n"), `Next, in ${CLIENT_LABELS[client]}`);
+  }
+  await writeSkillFile(cwd, generateSkillFile(config, client ? { client, auth } : void 0));
   p2.outro(`Done -- this project is set up for ${config.brandName}.`);
 }
 
 // src/commands/export.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { dirname, relative, resolve } from "path";
+import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, relative, resolve } from "path";
 import * as p3 from "@clack/prompts";
 
 // src/api.ts
@@ -400,7 +728,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.3.0" }
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.5.0" }
     });
   } catch (error) {
     throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
@@ -562,6 +890,11 @@ function problemMessage(problem, context) {
       return `Stoaken answered ${problem.status}${problem.detail ? `: ${problem.detail}` : problem.title ? `: ${problem.title}` : "."}`;
   }
 }
+function isUpToDate(onDisk, live) {
+  if (onDisk === null) return false;
+  const lf = (s) => s.replace(/\r\n/g, "\n");
+  return lf(onDisk) === lf(live);
+}
 function formatBytes(n) {
   return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
 }
@@ -659,17 +992,17 @@ async function exportOne(serverUrl, token, target, theme, check, cwd) {
   if (check) {
     let current = null;
     try {
-      current = await readFile2(path, "utf8");
+      current = await readFile3(path, "utf8");
     } catch {
     }
-    if (current !== file.text) {
+    if (!isUpToDate(current, file.text)) {
       throw new ExportUsageError(`${shown} is out of date with ${label}${current === null ? " (it doesn't exist)" : ""}. Run "stoaken export" and commit the result.`);
     }
     say(`\u2714 ${shown} is up to date with ${label}`);
     return;
   }
-  await mkdir2(dirname(path), { recursive: true });
-  await writeFile2(path, file.text, "utf8");
+  await mkdir3(dirname2(path), { recursive: true });
+  await writeFile3(path, file.text, "utf8");
   say(`\u2714 ${label} \u2192 ${shown} (${target.format}, ${formatBytes(Buffer.byteLength(file.text))})${warnings}`);
 }
 function describe(error, themeName, usingEnvToken) {
@@ -684,9 +1017,16 @@ function flagValue(args, name) {
   return index === -1 ? void 0 : args[index + 1];
 }
 switch (command) {
-  case "init":
-    await runInit({ server: flagValue(rest, "server") });
+  case "init": {
+    const client = flagValue(rest, "client");
+    if (client !== void 0 && !isClient(client)) {
+      p4.log.error(`Unknown --client "${client}". Use one of: ${CLIENTS.join(", ")}`);
+      process.exitCode = 1;
+      break;
+    }
+    await runInit({ server: flagValue(rest, "server"), client });
     break;
+  }
   case "export":
     process.exitCode = await runExport(rest);
     break;
@@ -698,7 +1038,9 @@ switch (command) {
         "stoaken -- Stoaken CLI",
         "",
         "Usage:",
-        "  stoaken init [--server <url>]   Authenticate, pick a Brand, and set up this project",
+        "  stoaken init [--server <url>] [--client <name>]",
+        "                                  Authenticate, 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,51 +1,51 @@
-{
-  "name": "stoaken",
-  "version": "0.3.0",
-  "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "bin": {
-    "stoaken": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/craig-astravale/stoaken.git",
-    "directory": "cli"
-  },
-  "bugs": {
-    "url": "https://github.com/craig-astravale/stoaken/issues"
-  },
-  "homepage": "https://github.com/craig-astravale/stoaken/tree/main/cli#readme",
-  "keywords": [
-    "design-tokens",
-    "dtcg",
-    "mcp",
-    "model-context-protocol",
-    "cli",
-    "design-system"
-  ],
-  "author": "Stoaken",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --clean --shims",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.8.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "open": "^11.0.2"
-  },
-  "devDependencies": {
-    "@types/node": "^26.5.0",
-    "tsup": "^8.5.1",
-    "tsx": "^4.23.13",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "stoaken",
+  "version": "0.5.0",
+  "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "stoaken": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/craig-astravale/stoaken.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/craig-astravale/stoaken/issues"
+  },
+  "homepage": "https://github.com/craig-astravale/stoaken/tree/main/cli#readme",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "design-system"
+  ],
+  "author": "Stoaken",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --shims",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "open": "^11.0.2",
+    "@modelcontextprotocol/client": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}