premanmcp 0.4.0 → 0.5.0

package/README.md

@@ -4,26 +4,33 @@ Turn your APIs into MCP tools that coding agents can discover, call, test, and a
 
 PreMan is agent-first API infrastructure. It lets backend teams expose endpoints to AI coding agents through MCP, add an auth layer around those tools, and see exactly which agent called what.
 
-## Install
+## Connect
 
 ```bash
-npm exec -y premanmcp@latest -- install
+npx premanmcp@latest connect
 ```
 
+Pick your coding agent from the list — Cursor, Claude Code, or Codex — and PreMan
+writes that agent's MCP config for you. No hand-edited config anywhere.
+
 Local development form:
 
 ```bash
-node bin/cli.js install
+node bin/cli.js connect
 ```
 
-First-time users are prompted for email, OTP, and password directly in the terminal. PreMan creates or connects the account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a `preman` MCP server into `~/.cursor/mcp.json`:
+First-time users are prompted for email, OTP, and password directly in the terminal.
+PreMan creates or connects the account, generates an API key, saves it to
+`~/.preman/credentials.json`, then writes a `preman` MCP server into the config your
+agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
+`~/.codex/config.toml`):
 
 ```json
 {
   "mcpServers": {
     "preman": {
-      "command": "npm",
-      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
+      "command": "npx",
+      "args": ["-y", "premanmcp@latest"],
       "env": {
         "PREMAN_BACKEND": "https://api.preman.live",
         "PREMAN_FRONTEND": "https://app.preman.live"
@@ -33,9 +40,21 @@ First-time users are prompted for email, OTP, and password directly in the termi
 }
 ```
 
-Restart Cursor or toggle the MCP server off/on after install. The MCP server loads the saved key automatically.
+Restart your agent afterwards, then ask it to `run preman_status` to finish linking.
+
+Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
+project-local config, `--print` shows the config without writing it.
+
+`preman install` still exists and does the Cursor-only half of this.
+
+### Cloud dispatch (optional)
 
-You can also create or connect your account before install:
+`connect` offers to store a coding-agent credential — a Cursor API key, or a Claude
+Code routine token and id. With one saved, PreMan can start an agent run for you when
+it finds a failing endpoint instead of handing back a prompt to paste. Press Enter to
+skip; everything else still works.
+
+You can also create or connect your account first:
 
 ```bash
 npm exec -y premanmcp@latest -- login
@@ -44,13 +63,13 @@ npm exec -y premanmcp@latest -- login
 You can also pass the key directly:
 
 ```bash
-npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
+npx premanmcp@latest connect --api-key pm_live_xxx
 ```
 
-For project-local installation:
+For project-local config:
 
 ```bash
-npm exec -y premanmcp@latest -- install --project
+npx premanmcp@latest connect --project
 ```
 
 ## What It Does
@@ -94,20 +113,18 @@ Pull my pending PreMan fix tasks and fix the failing endpoint.
 
 ## Cursor
 
-The installer targets Cursor by default:
-
 ```bash
-npm exec -y premanmcp@latest -- install
+npx premanmcp@latest connect --agent cursor
 ```
 
-Manual Cursor config:
+Manual Cursor config, if you would rather write it yourself:
 
 ```json
 {
   "mcpServers": {
     "preman": {
-      "command": "npm",
-      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"]
+      "command": "npx",
+      "args": ["-y", "premanmcp@latest"]
     }
   }
 }
@@ -116,18 +133,33 @@ Manual Cursor config:
 ## Claude Code
 
 ```bash
-claude mcp add preman -- npm exec -y --package premanmcp@latest -- premanmcp
+npx premanmcp@latest connect --agent claude-code
 ```
 
+Equivalent manual command:
+
+```bash
+claude mcp add preman -- npx -y premanmcp@latest
+```
+
+## Codex
+
+```bash
+npx premanmcp@latest connect --agent codex
+```
+
+Writes an `[mcp_servers.preman]` block into `~/.codex/config.toml`.
+
 ## CLI
 
 ```bash
-npm exec -y premanmcp@latest --       # Start the MCP server
-npm exec -y premanmcp@latest -- login # Create/login and generate a PreMan API key
-npm exec -y premanmcp@latest -- install          # Install Cursor MCP config
-npm exec -y premanmcp@latest -- install --project # Write .cursor/mcp.json in current repo
-npm exec -y premanmcp@latest -- install --print   # Print config without writing
-npm exec -y premanmcp@latest -- install --api-key KEY # Install with your PreMan API key
+npx premanmcp@latest connect            # Pick an agent and connect it
+npx premanmcp@latest connect --agent codex   # Skip the picker
+npx premanmcp@latest connect --project  # Write project-local config
+npx premanmcp@latest connect --print    # Print config without writing
+npm exec -y premanmcp@latest --         # Start the MCP server
+npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API key
+npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```
 
 Options:

package/bin/cli.js

@@ -11,20 +11,26 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import { CONNECT_HELP, connectCommand, writeCursorConfig } from "./connect.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+import {
+  CREDENTIALS_FILE,
+  DEFAULT_BACKEND,
+  DEFAULT_FRONTEND,
+  authenticateTerminal,
+  buildServerConfig,
+  hasKeyAvailable,
+  makeArgs,
+  readStoredCredentials,
+} from "./shared.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
-const DEFAULT_BACKEND = "https://api.preman.live";
-const DEFAULT_FRONTEND = "https://app.preman.live";
-const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
-const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 
 const args = process.argv.slice(2);
 const command = args[0] === "--help" || args[0] === "-h"
@@ -33,31 +39,31 @@ const command = args[0] === "--help" || args[0] === "-h"
     ? args[0]
     : "start";
 const commandArgs = command === "start" ? args : args.slice(1);
+const cliArgs = makeArgs(commandArgs);
 
 function argValue(name, fallback = "") {
-  const index = commandArgs.indexOf(name);
-  if (index === -1) return fallback;
-  return commandArgs[index + 1] || fallback;
+  return cliArgs.value(name, fallback);
 }
 
 function hasFlag(name) {
-  return commandArgs.includes(name);
+  return cliArgs.has(name);
 }
 
 function printHelp() {
   process.stdout.write(`PreMan MCP
 
 Usage:
+  preman connect [options]                           Pick a coding agent and connect it
   npm exec -y premanmcp@latest -- login              Create/login to PreMan from the terminal
   npm exec -y premanmcp@latest -- install [options]  Install PreMan into Cursor MCP config
   npm exec -y premanmcp@latest --                    Start the PreMan MCP server
   preman link|tools|run ...                          Drive a published hosted MCP
-
+${CONNECT_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
 
-Install options:
+Install options (Cursor only — prefer 'preman connect'):
   --api-key <key>       PreMan API key. If omitted, stored CLI credentials are used
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
   --frontend <url>      PreMan frontend URL. Defaults to ${DEFAULT_FRONTEND}
@@ -68,296 +74,15 @@ Install options:
   --print               Print the config instead of writing it
 
 Examples:
+  npx premanmcp@latest connect
+  preman connect --agent claude-code
   npm exec -y premanmcp@latest -- login
-  npm exec -y premanmcp@latest -- install
-  npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
   npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
 ${HOSTED_HELP}`);
 }
 
-function readJsonFile(filePath) {
-  if (!existsSync(filePath)) return {};
-  const raw = readFileSync(filePath, "utf8").trim();
-  if (!raw) return {};
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`Could not parse ${filePath}: ${error.message}`);
-  }
-}
-
-function readStoredCredentials() {
-  try {
-    const raw = readFileSync(CREDENTIALS_FILE, "utf8").trim();
-    if (!raw) return null;
-    const creds = JSON.parse(raw);
-    if (creds && typeof creds.api_key === "string" && creds.api_key.startsWith("pm_live_")) {
-      return creds;
-    }
-  } catch {
-    // No stored credentials yet.
-  }
-  return null;
-}
-
-function saveStoredCredentials(creds) {
-  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
-  writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
-}
-
-function backendUrl() {
-  return argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
-}
-
-async function promptText(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    return (await rl.question(question)).trim();
-  } finally {
-    rl.close();
-  }
-}
-
-async function promptSecret(question) {
-  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
-    return promptText(question);
-  }
-
-  return new Promise((resolve) => {
-    const stdin = process.stdin;
-    const stdout = process.stdout;
-    const wasRaw = stdin.isRaw;
-    let value = "";
-
-    function cleanup() {
-      stdin.off("data", onData);
-      stdin.setRawMode(Boolean(wasRaw));
-      stdin.pause();
-    }
-
-    function onData(chunk) {
-      const text = String(chunk);
-      if (text === "\u0003") {
-        stdout.write("\n");
-        cleanup();
-        process.exit(130);
-      }
-      if (text === "\r" || text === "\n" || text === "\u0004") {
-        stdout.write("\n");
-        cleanup();
-        resolve(value);
-        return;
-      }
-      if (text === "\u007f" || text === "\b") {
-        if (value.length) {
-          value = value.slice(0, -1);
-          stdout.write("\b \b");
-        }
-        return;
-      }
-      value += text;
-      stdout.write("*");
-    }
-
-    stdout.write(question);
-    stdin.setRawMode(true);
-    stdin.resume();
-    stdin.setEncoding("utf8");
-    stdin.on("data", onData);
-  });
-}
-
-async function promptPasswordTwice() {
-  const password = await promptSecret("Create password: ");
-  if (!password || password.length < 6) {
-    throw new Error("Password must be at least 6 characters.");
-  }
-  const confirm = await promptSecret("Confirm password: ");
-  if (password !== confirm) {
-    throw new Error("Passwords do not match.");
-  }
-  return password;
-}
-
-async function callBackendJson(method, routePath, { json, token, query } = {}) {
-  const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl()}/`);
-  if (query) {
-    for (const [key, value] of Object.entries(query)) {
-      if (value != null && value !== "") url.searchParams.set(key, String(value));
-    }
-  }
-
-  const headers = { Accept: "application/json" };
-  const hasBody = json !== undefined && json !== null;
-  if (hasBody) headers["Content-Type"] = "application/json";
-  if (token) headers.Authorization = `Bearer ${token}`;
-
-  const resp = await fetch(url, {
-    method,
-    headers,
-    body: hasBody ? JSON.stringify(json) : undefined,
-  });
-  const text = await resp.text();
-  let body = {};
-  try {
-    body = text ? JSON.parse(text) : {};
-  } catch {
-    body = { raw: text };
-  }
-  return {
-    status_code: resp.status,
-    ok: resp.ok,
-    ...body,
-  };
-}
-
-function assertOk(result, action) {
-  if (result.ok) return;
-  const detail = result.detail || result.message || result.raw || `${action} failed`;
-  throw new Error(`${action} failed: ${result.status_code} ${detail}`);
-}
-
-async function verifyUnconfirmedAccount(email) {
-  process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
-  const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
-  assertOk(resend, "resend OTP");
-  const otp = await promptText("Verification code: ");
-  const verified = await callBackendJson("POST", "/auth/verify-otp", { json: { email, otp } });
-  assertOk(verified, "verify OTP");
-  return verified.access_token;
-}
-
-async function createAccountFromTerminal(email) {
-  const signup = await callBackendJson("POST", "/auth/start-signup", {
-    json: { email },
-  });
-
-  if (signup.ok) {
-    process.stdout.write("Verification code sent. Check your email.\n");
-    const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson("POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    return String(setPassword.access_token || "");
-  }
-
-  if (signup.status_code !== 404) {
-    assertOk(signup, "start signup");
-  }
-
-  process.stdout.write(
-    "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
-  );
-  const password = await promptPasswordTwice();
-  const legacySignup = await callBackendJson("POST", "/auth/signup", {
-    json: { email, password },
-  });
-  assertOk(legacySignup, "signup");
-  process.stdout.write("Verification code sent. Check your email.\n");
-  const otp = await promptText("Verification code: ");
-  const verified = await callBackendJson("POST", "/auth/verify-otp", {
-    json: { email, otp },
-  });
-  assertOk(verified, "verify OTP");
-  return String(verified.access_token || "");
-}
-
-async function authenticateTerminal() {
-  const explicitKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
-  if (explicitKey && explicitKey.startsWith("pm_live_")) {
-    const creds = {
-      api_key: explicitKey,
-      backend_url: backendUrl(),
-      user_email: argValue("--email", ""),
-      device_name: os.hostname(),
-      created_at: new Date().toISOString(),
-    };
-    saveStoredCredentials(creds);
-    return creds;
-  }
-
-  const email = (argValue("--email", "") || await promptText("Email: ")).trim().toLowerCase();
-  if (!email) throw new Error("Email is required.");
-
-  process.stdout.write(`Checking PreMan account for ${email}...\n`);
-  const account = await callBackendJson("GET", "/auth/needs-password", { query: { email } });
-  assertOk(account, "check account");
-
-  let accessToken = "";
-
-  if (!account.exists) {
-    process.stdout.write("No PreMan account found. Creating one now.\n");
-    accessToken = await createAccountFromTerminal(email);
-  } else if (account.needs_password) {
-    process.stdout.write("This account needs a password. Sending an OTP first.\n");
-    const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
-    assertOk(resend, "resend OTP");
-    const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson("POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    accessToken = String(setPassword.access_token || "");
-  } else {
-    const password = await promptSecret("Password: ");
-    const login = await callBackendJson("POST", "/auth/login", {
-      json: { email, password },
-    });
-    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
-      accessToken = await verifyUnconfirmedAccount(email);
-    } else {
-      assertOk(login, "login");
-      accessToken = String(login.access_token || "");
-    }
-  }
-
-  if (!accessToken) throw new Error("PreMan did not return an access token.");
-
-  const keyName = `PreMan MCP CLI (${os.hostname()})`;
-  const key = await callBackendJson("POST", "/api-keys", {
-    token: accessToken,
-    json: { name: keyName },
-  });
-  assertOk(key, "create API key");
-  if (!key.key || !String(key.key).startsWith("pm_live_")) {
-    throw new Error("PreMan did not return a valid API key.");
-  }
-
-  const creds = {
-    api_key: String(key.key),
-    backend_url: backendUrl(),
-    user_email: email,
-    device_name: os.hostname(),
-    created_at: new Date().toISOString(),
-  };
-  saveStoredCredentials(creds);
-  return creds;
-}
-
-function buildServerConfig() {
-  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
-  const backend = argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND);
-  const frontend = argValue("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND);
-  const env = {
-    PREMAN_BACKEND: backend,
-    PREMAN_FRONTEND: frontend,
-  };
-  if (apiKey) {
-    env.PREMAN_API_KEY = apiKey;
-  }
-
-  return {
-    command: "npm",
-    args: ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
-    env,
-  };
-}
-
 async function loginCommand() {
-  const creds = await authenticateTerminal();
+  const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
 Email: ${creds.user_email || "unknown"}
@@ -366,61 +91,47 @@ API key: ${creds.api_key}
 Saved to: ${CREDENTIALS_FILE}
 
 You can now run:
-  npm exec -y premanmcp@latest -- install
+  preman connect
 `);
 }
 
+/**
+ * Cursor-only installer, kept for the documented `install` flow. `connect` is
+ * the same write plus agent choice, pairing, and dispatch setup.
+ */
 async function installCursorMcp() {
   const serverName = argValue("--name", "preman");
   const projectInstall = hasFlag("--project");
 
-  if (
-    !hasFlag("--print") &&
-    !hasFlag("--skip-login") &&
-    !argValue("--api-key", "") &&
-    !process.env.PREMAN_API_KEY &&
-    !readStoredCredentials()
-  ) {
+  if (!hasFlag("--print") && !hasFlag("--skip-login") && !hasKeyAvailable(cliArgs)) {
     process.stdout.write("First, let's create or connect your PreMan account.\n");
-    await authenticateTerminal();
+    await authenticateTerminal(cliArgs);
     process.stdout.write("\n");
   }
 
-  const serverConfig = buildServerConfig();
+  const serverConfig = buildServerConfig(cliArgs);
 
   if (hasFlag("--print")) {
     process.stdout.write(`${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`);
     return;
   }
 
-  const configPath = projectInstall
-    ? path.join(process.cwd(), ".cursor", "mcp.json")
-    : path.join(os.homedir(), ".cursor", "mcp.json");
-
-  const config = {
-    ...readJsonFile(configPath),
-  };
-  config.mcpServers = {
-    ...(config.mcpServers || {}),
-    [serverName]: serverConfig,
-  };
+  const written = writeCursorConfig({ serverName, serverConfig, projectInstall });
 
-  const rendered = `${JSON.stringify(config, null, 2)}\n`;
-  mkdirSync(path.dirname(configPath), { recursive: true });
-  writeFileSync(configPath, rendered, { mode: 0o600 });
-
-  const hasInlineKey = Boolean(config.mcpServers[serverName].env.PREMAN_API_KEY);
+  const hasInlineKey = Boolean(serverConfig.env.PREMAN_API_KEY);
   const hasStoredKey = Boolean(readStoredCredentials());
-  process.stdout.write(`PreMan MCP installed in ${configPath}
+  process.stdout.write(`PreMan MCP installed in ${written.path}
 
 Server name: ${serverName}
-Backend: ${config.mcpServers[serverName].env.PREMAN_BACKEND}
+Backend: ${serverConfig.env.PREMAN_BACKEND}
 
 Next steps:
 1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run npm exec -y premanmcp@latest -- login to create/connect your account and generate an API key."}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
 3. In your API repo, ask your coding agent:
    "Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet."
+
+Tip: 'preman connect' also supports Claude Code and Codex, and links the agent to your account.
 `);
 }
 
@@ -454,6 +165,8 @@ function startServer() {
 async function main() {
   if (command === "login") {
     await loginCommand();
+  } else if (command === "connect") {
+    await connectCommand(commandArgs);
   } else if (command === "install") {
     await installCursorMcp();
   } else if (command === "link") {

package/bin/connect.js

@@ -0,0 +1,432 @@
+/**
+ * `preman connect` — pick a coding agent and get connected, in one command.
+ *
+ * Replaces the hand-edited MCP config: the user picks Cursor / Claude Code /
+ * Codex from a list, PreMan logs them in if needed, writes that agent's config
+ * itself, and binds the connection to their account with a pair code.
+ *
+ * Optionally captures a cloud-dispatch credential in the same pass so PreMan can
+ * start agent runs for them later (SCRUM-124). That step is always skippable and
+ * never fails the connect.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  assertOk,
+  authenticateTerminal,
+  backendUrl,
+  buildServerConfig,
+  callBackendJson,
+  hasKeyAvailable,
+  makeArgs,
+  promptSecret,
+  promptText,
+  readJsonFile,
+  resolveApiKey,
+  writeJsonFile,
+} from "./shared.js";
+
+const EXIT_USAGE = 2;
+
+class ConnectError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Supported agents. `id` matches the backend's normalize_agent() vocabulary so
+ * the link record and this CLI cannot disagree about who is connected.
+ */
+const AGENTS = [
+  {
+    id: "cursor",
+    label: "Cursor",
+    aliases: ["cursor"],
+    dispatch: { credential: "Cursor API key", needsRoutine: false },
+  },
+  {
+    id: "claude_code",
+    label: "Claude Code",
+    aliases: ["claude", "claude-code", "claude_code", "claudecode"],
+    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    aliases: ["codex", "openai-codex", "openai_codex"],
+    dispatch: null, // No public fire API; stays on the copy-paste path.
+  },
+];
+
+function findAgent(value) {
+  const raw = String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
+  return AGENTS.find((a) => a.id === raw || a.aliases.includes(raw)) || null;
+}
+
+function onPath(binary) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [binary], {
+    stdio: "ignore",
+  });
+  return probe.status === 0;
+}
+
+/** Best guess at which agent this machine actually uses, for the default pick. */
+function detectAgents() {
+  const home = os.homedir();
+  return {
+    cursor: existsSync(path.join(home, ".cursor")) || Boolean(process.env.CURSOR_TRACE_ID),
+    claude_code: onPath("claude") || existsSync(path.join(home, ".claude.json")),
+    codex: onPath("codex") || existsSync(process.env.CODEX_HOME || path.join(home, ".codex")),
+  };
+}
+
+async function promptAgentChoice(detected) {
+  process.stdout.write("Which coding agent?\n");
+  AGENTS.forEach((agent, index) => {
+    const mark = detected[agent.id] ? "  (detected)" : "";
+    process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
+  });
+
+  const defaultIndex = Math.max(
+    0,
+    AGENTS.findIndex((a) => detected[a.id])
+  );
+  const answer = await promptText(`Pick [${defaultIndex + 1}]: `);
+  if (!answer) return AGENTS[defaultIndex];
+
+  const byNumber = Number.parseInt(answer, 10);
+  if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= AGENTS.length) {
+    return AGENTS[byNumber - 1];
+  }
+  const byName = findAgent(answer);
+  if (byName) return byName;
+  throw new ConnectError(`Not a valid choice: ${answer}`, EXIT_USAGE);
+}
+
+// ── Config writers ──────────────────────────────────────────────────────
+
+function cursorConfigPath(projectInstall) {
+  return projectInstall
+    ? path.join(process.cwd(), ".cursor", "mcp.json")
+    : path.join(os.homedir(), ".cursor", "mcp.json");
+}
+
+export function writeCursorConfig({ serverName, serverConfig, projectInstall }) {
+  const configPath = cursorConfigPath(projectInstall);
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+  return { path: configPath, how: "wrote" };
+}
+
+/**
+ * Claude Code owns ~/.claude.json, so prefer its own CLI. Fall back to writing
+ * the config directly when `claude` is not installed — a user can connect before
+ * installing the agent.
+ */
+export function writeClaudeConfig({ serverName, serverConfig, projectInstall }) {
+  if (onPath("claude")) {
+    const envArgs = Object.entries(serverConfig.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+    const args = [
+      "mcp",
+      "add",
+      serverName,
+      "--scope",
+      projectInstall ? "project" : "user",
+      ...envArgs,
+      "--",
+      serverConfig.command,
+      ...serverConfig.args,
+    ];
+    try {
+      execFileSync("claude", args, { stdio: "pipe" });
+      return { path: projectInstall ? ".mcp.json" : "Claude Code user config", how: "registered via claude mcp add" };
+    } catch (error) {
+      const detail = error?.stderr?.toString().trim() || error.message;
+      process.stdout.write(`Note: claude mcp add failed (${detail}); writing the config directly.\n`);
+    }
+  }
+
+  if (projectInstall) {
+    const configPath = path.join(process.cwd(), ".mcp.json");
+    const config = { ...readJsonFile(configPath) };
+    config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+    writeJsonFile(configPath, config);
+    return { path: configPath, how: "wrote" };
+  }
+
+  // Merge only mcpServers: the user config holds a lot of unrelated state.
+  // CLAUDE_CONFIG_DIR relocates that file, and writing to ~ when it is set
+  // produces a config Claude Code never reads.
+  const configPath = path.join(process.env.CLAUDE_CONFIG_DIR || os.homedir(), ".claude.json");
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+  return { path: configPath, how: "wrote" };
+}
+
+/**
+ * Render the `[mcp_servers.<name>]` block for Codex's TOML config. Only strings
+ * and string arrays appear here, so a hand-rolled writer is enough — no TOML
+ * dependency for one fixed shape.
+ */
+export function renderCodexToml(serverName, serverConfig) {
+  const str = (value) => JSON.stringify(String(value));
+  const lines = [
+    `[mcp_servers.${serverName}]`,
+    `command = ${str(serverConfig.command)}`,
+    `args = [${serverConfig.args.map(str).join(", ")}]`,
+  ];
+  const env = Object.entries(serverConfig.env);
+  if (env.length) {
+    lines.push("", `[mcp_servers.${serverName}.env]`);
+    for (const [key, value] of env) lines.push(`${key} = ${str(value)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Replace an existing preman block, or append a new one, leaving the rest alone. */
+export function upsertCodexToml(existing, serverName, block) {
+  const header = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`, "m");
+  if (!header.test(existing)) {
+    const separator = existing.trim() ? "\n" : "";
+    return `${existing.trimEnd()}${separator}\n${block}`;
+  }
+
+  const lines = existing.split("\n");
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    const isOurHeader = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`).test(line);
+    if (isOurHeader) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\[/.test(line) && !isOurHeader) skipping = false;
+    if (!skipping) out.push(line);
+  }
+  return `${out.join("\n").trimEnd()}\n\n${block}`;
+}
+
+export function writeCodexConfig({ serverName, serverConfig }) {
+  const configPath = path.join(
+    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+    "config.toml"
+  );
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const next = upsertCodexToml(existing, serverName, renderCodexToml(serverName, serverConfig));
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, next, { mode: 0o600 });
+  chmodSync(configPath, 0o600); // mode above is ignored for an existing file
+  return { path: configPath, how: "wrote" };
+}
+
+const WRITERS = {
+  cursor: writeCursorConfig,
+  claude_code: writeClaudeConfig,
+  codex: writeCodexConfig,
+};
+
+// ── Pairing ─────────────────────────────────────────────────────────────
+
+async function startPairing(args, agent, apiKey) {
+  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent", {
+    token: apiKey,
+    json: { agent: agent.id, project_path: process.cwd(), start_pairing: true },
+  });
+  if (!result.ok) {
+    process.stdout.write(
+      `Note: could not start pairing (${result.status_code}); the config still works, ` +
+        "your agent will link on its first PreMan call.\n"
+    );
+    return "";
+  }
+  return String(result.pair_code || "");
+}
+
+async function waitForConnection(args, apiKey, { intervalMs = 3000, timeoutMs = 300000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let interrupted = false;
+  const onInterrupt = () => {
+    interrupted = true;
+  };
+  process.on("SIGINT", onInterrupt);
+
+  try {
+    while (Date.now() < deadline && !interrupted) {
+      const status = await callBackendJson(args, "GET", "/workbench/coding-agent", {
+        token: apiKey,
+      });
+      if (status.ok && status.connected) return true;
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  } finally {
+    process.off("SIGINT", onInterrupt);
+  }
+  return false;
+}
+
+// ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
+
+async function captureDispatchCredential(args, agent, apiKey) {
+  if (!agent.dispatch) return;
+  if (args.has("--skip-dispatch-credential")) return;
+
+  let secret = args.value("--dispatch-credential", "");
+  let routineId = args.value("--routine-id", "");
+
+  if (!secret) {
+    if (!process.stdin.isTTY) return;
+    process.stdout.write(
+      `\nOptional: paste a ${agent.dispatch.credential} so PreMan can start ${agent.label} runs for you.\n`
+    );
+    secret = await promptSecret("(Enter to skip): ");
+    if (!secret) return;
+    if (agent.dispatch.needsRoutine && !routineId) {
+      routineId = await promptText("Routine id or URL: ");
+    }
+  }
+
+  if (agent.dispatch.needsRoutine && !routineId) {
+    process.stdout.write("Skipped: a routine id is required alongside the token.\n");
+    return;
+  }
+
+  const body = agent.dispatch.needsRoutine
+    ? { provider: agent.id, secret, routine_id: extractRoutineId(routineId) }
+    : { provider: agent.id, secret };
+
+  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent/dispatch", {
+    token: apiKey,
+    json: body,
+  });
+
+  if (result.ok) {
+    process.stdout.write("Cloud dispatch enabled — PreMan can now start runs for you.\n");
+  } else if (result.status_code === 404 || result.status_code === 405) {
+    process.stdout.write("Note: this PreMan backend does not support cloud dispatch yet; skipped.\n");
+  } else {
+    process.stdout.write(`Note: could not save the credential (${result.status_code}); skipped.\n`);
+  }
+}
+
+/** Accept either a bare trig_… id or the routine URL it appears in. */
+export function extractRoutineId(value) {
+  const raw = String(value || "").trim();
+  const match = raw.match(/trig_[A-Za-z0-9]+/);
+  return match ? match[0] : raw;
+}
+
+// ── Command ─────────────────────────────────────────────────────────────
+
+export const CONNECT_HELP = `
+Connect options:
+  --agent <name>              cursor | claude-code | codex (skips the picker)
+  --project                   Write project-local config instead of the user config
+  --api-key <key>             PreMan API key. If omitted, stored credentials are used
+  --email <email>             Pre-fill the email prompt when logging in
+  --backend <url>             PreMan backend URL
+  --frontend <url>            PreMan frontend URL
+  --name <name>               MCP server name. Defaults to preman
+  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
+  --routine-id <id>           Claude Code routine id, with --dispatch-credential
+  --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
+  --skip-login                Write config without interactive terminal auth
+  --no-pair                   Do not mint a pair code
+  --no-wait                   Do not wait for the agent to check in
+  --print                     Print the config instead of writing it
+`;
+
+export async function connectCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const serverName = args.value("--name", "preman");
+  const projectInstall = args.has("--project");
+  const printOnly = args.has("--print");
+  const interactive = Boolean(process.stdin.isTTY);
+
+  let agent = findAgent(args.value("--agent", ""));
+  if (!agent && args.value("--agent", "")) {
+    throw new ConnectError(
+      `Unknown agent: ${args.value("--agent", "")}. Use cursor, claude-code, or codex.`,
+      EXIT_USAGE
+    );
+  }
+
+  if (!agent) {
+    if (!interactive) {
+      throw new ConnectError(
+        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+          "and --api-key pm_live_… (or --print).",
+        EXIT_USAGE
+      );
+    }
+    agent = await promptAgentChoice(detectAgents());
+  }
+
+  if (printOnly) {
+    const serverConfig = buildServerConfig(args);
+    if (agent.id === "codex") {
+      process.stdout.write(renderCodexToml(serverName, serverConfig));
+    } else {
+      process.stdout.write(`${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`);
+    }
+    return;
+  }
+
+  if (!args.has("--skip-login") && !hasKeyAvailable(args)) {
+    if (!interactive) {
+      throw new ConnectError(
+        "No PreMan credentials. Pass --api-key pm_live_… or set PREMAN_API_KEY.",
+        EXIT_USAGE
+      );
+    }
+    process.stdout.write("First, let's connect your PreMan account.\n");
+    await authenticateTerminal(args);
+    process.stdout.write("\n");
+  }
+
+  const apiKey = resolveApiKey(args);
+
+  let pairCode = "";
+  if (apiKey && !args.has("--no-pair")) {
+    pairCode = await startPairing(args, agent, apiKey);
+  }
+
+  const serverConfig = buildServerConfig(args, { pairCode });
+  const written = WRITERS[agent.id]({ serverName, serverConfig, projectInstall });
+
+  process.stdout.write(
+    `\n${agent.label} connected: ${written.how} ${written.path}\n` +
+      `Server name: ${serverName}\n` +
+      `Backend: ${serverConfig.env.PREMAN_BACKEND}\n`
+  );
+
+  // Not gated on TTY: --dispatch-credential is the non-interactive path, and the
+  // prompt inside only runs when there is a terminal to prompt on.
+  await captureDispatchCredential(args, agent, apiKey);
+
+  if (!pairCode || args.has("--no-wait") || !interactive) {
+    process.stdout.write(
+      `\nRestart ${agent.label}, then ask it: "run preman_status" to finish linking.\n`
+    );
+    return;
+  }
+
+  process.stdout.write(
+    `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
+      "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
+  );
+  const connected = await waitForConnection(args, apiKey);
+  process.stdout.write(
+    connected
+      ? `Connected as ${agent.label}.\n`
+      : `No check-in yet. Open ${agent.label} and ask it to "run preman_status" — ` +
+        "it will link on its first PreMan call.\n"
+  );
+}

package/bin/shared.js

@@ -0,0 +1,348 @@
+/**
+ * Shared CLI helpers: prompts, credential storage, backend calls, terminal auth.
+ *
+ * Extracted from bin/cli.js so `connect` and `install` can use the same login
+ * and config-writing behavior instead of growing a second copy. Every function
+ * that reads flags takes an `args` accessor (see makeArgs) rather than closing
+ * over a module-level argv, so a command can pass its own slice.
+ */
+
+import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+export const DEFAULT_BACKEND = "https://api.preman.live";
+export const DEFAULT_FRONTEND = "https://app.preman.live";
+export const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
+export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+
+/** Wrap a raw argv slice in the positional lookup the CLI has always used. */
+export function makeArgs(commandArgs = []) {
+  return {
+    raw: commandArgs,
+    value(name, fallback = "") {
+      const index = commandArgs.indexOf(name);
+      if (index === -1) return fallback;
+      return commandArgs[index + 1] || fallback;
+    },
+    has(name) {
+      return commandArgs.includes(name);
+    },
+  };
+}
+
+export function readJsonFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Could not parse ${filePath}: ${error.message}`);
+  }
+}
+
+export function writeJsonFile(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  // writeFileSync's mode only applies when it creates the file, and these
+  // configs can hold a pm_live_ key — tighten an existing file explicitly.
+  chmodSync(filePath, 0o600);
+}
+
+export function readStoredCredentials() {
+  try {
+    const raw = readFileSync(CREDENTIALS_FILE, "utf8").trim();
+    if (!raw) return null;
+    const creds = JSON.parse(raw);
+    if (creds && typeof creds.api_key === "string" && creds.api_key.startsWith("pm_live_")) {
+      return creds;
+    }
+  } catch {
+    // No stored credentials yet.
+  }
+  return null;
+}
+
+export function saveStoredCredentials(creds) {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function backendUrl(args) {
+  return args.value("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+}
+
+export function frontendUrl(args) {
+  return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
+}
+
+export async function promptText(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    return promptText(question);
+  }
+
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const wasRaw = stdin.isRaw;
+    let value = "";
+
+    function cleanup() {
+      stdin.off("data", onData);
+      stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+    }
+
+    function onData(chunk) {
+      const text = String(chunk);
+      if (text === "\u0003") {
+        stdout.write("\n");
+        cleanup();
+        process.exit(130);
+      }
+      if (text === "\r" || text === "\n" || text === "\u0004") {
+        stdout.write("\n");
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (text === "\u007f" || text === "\b") {
+        if (value.length) {
+          value = value.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+      value += text;
+      stdout.write("*");
+    }
+
+    stdout.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+
+export async function promptPasswordTwice() {
+  const password = await promptSecret("Create password: ");
+  if (!password || password.length < 6) {
+    throw new Error("Password must be at least 6 characters.");
+  }
+  const confirm = await promptSecret("Confirm password: ");
+  if (password !== confirm) {
+    throw new Error("Passwords do not match.");
+  }
+  return password;
+}
+
+export async function callBackendJson(args, method, routePath, { json, token, query } = {}) {
+  const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl(args)}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value != null && value !== "") url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers = { Accept: "application/json" };
+  const hasBody = json !== undefined && json !== null;
+  if (hasBody) headers["Content-Type"] = "application/json";
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const resp = await fetch(url, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(json) : undefined,
+  });
+  const text = await resp.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return {
+    status_code: resp.status,
+    ok: resp.ok,
+    ...body,
+  };
+}
+
+export function assertOk(result, action) {
+  if (result.ok) return;
+  const detail = result.detail || result.message || result.raw || `${action} failed`;
+  throw new Error(`${action} failed: ${result.status_code} ${detail}`);
+}
+
+async function verifyUnconfirmedAccount(args, email) {
+  process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
+  const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+  assertOk(resend, "resend OTP");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", { json: { email, otp } });
+  assertOk(verified, "verify OTP");
+  return verified.access_token;
+}
+
+async function createAccountFromTerminal(args, email) {
+  const signup = await callBackendJson(args, "POST", "/auth/start-signup", {
+    json: { email },
+  });
+
+  if (signup.ok) {
+    process.stdout.write("Verification code sent. Check your email.\n");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+
+  if (signup.status_code !== 404) {
+    assertOk(signup, "start signup");
+  }
+
+  process.stdout.write(
+    "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
+  );
+  const password = await promptPasswordTwice();
+  const legacySignup = await callBackendJson(args, "POST", "/auth/signup", {
+    json: { email, password },
+  });
+  assertOk(legacySignup, "signup");
+  process.stdout.write("Verification code sent. Check your email.\n");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
+/**
+ * Get a usable pm_live_ key: an explicit one, or by logging in / signing up
+ * right here in the terminal. Always persists to ~/.preman/credentials.json.
+ */
+export async function authenticateTerminal(args) {
+  const explicitKey = args.value("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicitKey && explicitKey.startsWith("pm_live_")) {
+    const creds = {
+      api_key: explicitKey,
+      backend_url: backendUrl(args),
+      user_email: args.value("--email", ""),
+      device_name: os.hostname(),
+      created_at: new Date().toISOString(),
+    };
+    saveStoredCredentials(creds);
+    return creds;
+  }
+
+  const email = (args.value("--email", "") || await promptText("Email: ")).trim().toLowerCase();
+  if (!email) throw new Error("Email is required.");
+
+  process.stdout.write(`Checking PreMan account for ${email}...\n`);
+  const account = await callBackendJson(args, "GET", "/auth/needs-password", { query: { email } });
+  assertOk(account, "check account");
+
+  let accessToken = "";
+
+  if (!account.exists) {
+    process.stdout.write("No PreMan account found. Creating one now.\n");
+    accessToken = await createAccountFromTerminal(args, email);
+  } else if (account.needs_password) {
+    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+    assertOk(resend, "resend OTP");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    accessToken = String(setPassword.access_token || "");
+  } else {
+    const password = await promptSecret("Password: ");
+    const login = await callBackendJson(args, "POST", "/auth/login", {
+      json: { email, password },
+    });
+    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+      accessToken = await verifyUnconfirmedAccount(args, email);
+    } else {
+      assertOk(login, "login");
+      accessToken = String(login.access_token || "");
+    }
+  }
+
+  if (!accessToken) throw new Error("PreMan did not return an access token.");
+
+  const keyName = `PreMan MCP CLI (${os.hostname()})`;
+  const key = await callBackendJson(args, "POST", "/api-keys", {
+    token: accessToken,
+    json: { name: keyName },
+  });
+  assertOk(key, "create API key");
+  if (!key.key || !String(key.key).startsWith("pm_live_")) {
+    throw new Error("PreMan did not return a valid API key.");
+  }
+
+  const creds = {
+    api_key: String(key.key),
+    backend_url: backendUrl(args),
+    user_email: email,
+    device_name: os.hostname(),
+    created_at: new Date().toISOString(),
+  };
+  saveStoredCredentials(creds);
+  return creds;
+}
+
+/** Does this invocation already have a key, without prompting for one? */
+export function hasKeyAvailable(args) {
+  return Boolean(
+    args.value("--api-key", "") || process.env.PREMAN_API_KEY || readStoredCredentials()
+  );
+}
+
+/** Resolve the key to embed in a written config, if any. */
+export function resolveApiKey(args) {
+  const explicit = args.value("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicit) return explicit;
+  const stored = readStoredCredentials();
+  return stored ? stored.api_key : "";
+}
+
+/**
+ * The MCP server block written into every agent's config.
+ *
+ * Matches the backend's install snippets (`build_install_snippets`) so the
+ * copy-paste path and this writer cannot drift.
+ */
+export function buildServerConfig(args, { pairCode = "" } = {}) {
+  const env = {
+    PREMAN_BACKEND: backendUrl(args),
+    PREMAN_FRONTEND: frontendUrl(args),
+  };
+  const apiKey = resolveApiKey(args);
+  if (apiKey) env.PREMAN_API_KEY = apiKey;
+  if (pairCode) env.PREMAN_PAIR_CODE = pairCode;
+
+  return {
+    command: "npx",
+    args: ["-y", "premanmcp@latest"],
+    env,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {