@the-meridian/cli 1.2.0 → 1.4.0

package/dist/index.js

@@ -2,12 +2,12 @@
 
 // src/index.ts
 import { realpathSync } from "fs";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
 // src/commands/db.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { join as join6 } from "path";
+import { readFileSync as readFileSync6 } from "fs";
+import { join as join5 } from "path";
 
 // src/version.ts
 import { createRequire } from "module";
@@ -81,9 +81,9 @@ var devDatabaseSchema = z.object({
   /** Set by the API only while `status` is `error`; surfaced verbatim to the developer. */
   error_message: z.string().nullish(),
   /**
-   * How the CLI reaches the database: `gateway` (the Meridian database
-   * gateway with a per-developer certificate) or `proxy` (cloud-sql-proxy).
-   * Absent from an API older than the gateway, which means `proxy`.
+   * How the CLI reaches the database. The API always reports `gateway` (the
+   * Meridian database gateway with a per-developer certificate) since
+   * MER-823; the CLI no longer reads it.
    */
   access: devDatabaseAccessSchema.nullish()
 }).loose();
@@ -111,11 +111,6 @@ var devCredentialsSchema = z.object({
   /** Echoed from the (nullable) dev-database column, so it can be null. */
   instance_connection_name: z.string().nullish()
 }).loose();
-var proxyTokenSchema = z.object({
-  access_token: z.string(),
-  expires_at: z.string().nullish(),
-  instance_connection_name: z.string().nullish()
-}).loose();
 var migrationRunInputSchema = z.object({
   command: z.string(),
   status: z.enum(["success", "failed", "rolled_back"]),
@@ -350,13 +345,6 @@ var ApiClient = class _ApiClient {
       `/app/cli/apps/${encodePathSegment(appId)}/dev-database/credentials`
     );
   }
-  async issueProxyToken(appId) {
-    return this.request(
-      proxyTokenSchema,
-      "POST",
-      `/app/cli/apps/${encodePathSegment(appId)}/dev-database/proxy-token`
-    );
-  }
   /**
    * Signs `publicKeyPem` (SPKI) as this developer's client certificate for the
    * database gateway. Each call replaces the previous certificate server-side.
@@ -592,9 +580,6 @@ function meridianHome() {
 function globalConfigPath() {
   return join(meridianHome(), "config.json");
 }
-function proxyBinDir() {
-  return join(meridianHome(), "bin");
-}
 function projectStateDir(root) {
   return join(root, ".meridian");
 }
@@ -688,6 +673,16 @@ function resolveApiBaseUrl(override) {
   }
   return normalizeApiBaseUrl(DEFAULT_API_BASE_URL);
 }
+function storedTokenApiBaseUrl(config = readConfig()) {
+  return normalizeApiBaseUrl(
+    config.api_base_url !== void 0 && config.api_base_url !== "" ? config.api_base_url : DEFAULT_API_BASE_URL
+  );
+}
+function tokenMismatchError(baseUrl, tokenBaseUrl) {
+  return new CliError(`Your Meridian CLI token was issued by ${tokenBaseUrl}, not ${baseUrl}, so it was not sent.`, {
+    hint: `Unset MERIDIAN_API_URL (or --api-url) to use ${tokenBaseUrl}, or run \`meridian login\` to sign in to ${baseUrl}.`
+  });
+}
 function getAuth() {
   const config = readConfig();
   if (config.token === void 0) return null;
@@ -726,8 +721,13 @@ function workingDirectory() {
 function createApiClient(options = {}) {
   const requireAuth = options.requireAuth ?? true;
   const baseUrl = resolveApiBaseUrl(options.apiUrl ?? getGlobalOptions().apiUrl);
-  const token = options.token ?? getAuth()?.token;
+  const storedToken = getAuth()?.token;
+  const token = options.token ?? storedToken;
   if (requireAuth && token === void 0) throw notLoggedInError();
+  if (token !== void 0 && token === storedToken) {
+    const tokenBaseUrl = storedTokenApiBaseUrl();
+    if (tokenBaseUrl !== baseUrl) throw tokenMismatchError(baseUrl, tokenBaseUrl);
+  }
   return new ApiClient({
     baseUrl,
     userAgent: USER_AGENT,
@@ -747,8 +747,8 @@ function connectionInfoFromCredentials(credentials, proxy) {
   };
 }
 var createSqlConnection = async (info, options) => {
-  const { createConnection: createConnection2 } = await import("mysql2/promise");
-  const connection = await createConnection2({
+  const { createConnection } = await import("mysql2/promise");
+  const connection = await createConnection({
     host: info.host,
     port: info.port,
     user: info.user,
@@ -832,7 +832,7 @@ function toDatabaseError(error2, info) {
   if (code === "ECONNREFUSED") {
     return build(
       `Could not reach ${target} (${code}).`,
-      "Nothing is listening on that port. `meridian dev` and `meridian migrate` start the Cloud SQL Auth Proxy for you; start it first if you are connecting by hand."
+      "Nothing is listening on that port. `meridian dev` and `meridian migrate` start the database connection for you; start one of them first if you are connecting by hand."
     );
   }
   if (code === "ETIMEDOUT" || code === "PROTOCOL_SEQUENCE_TIMEOUT") {
@@ -2569,7 +2569,7 @@ async function findFreePort(options = {}) {
   }
   const ephemeral = await bindEphemeralPort(host);
   if (ephemeral === null) {
-    throw new CliError("Could not find a free local port for the Cloud SQL Auth Proxy.", {
+    throw new CliError("Could not find a free local port for the database gateway forwarder.", {
       hint: "Close other applications using local ports and try again."
     });
   }
@@ -2782,513 +2782,6 @@ function diagnoseMigrationFailure(root) {
   return offender === null ? null : foreignDialectExplanation(offender);
 }
 
-// src/lib/proxy/binary.ts
-import { createHash as createHash2 } from "crypto";
-import { chmodSync as chmodSync3, existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync6, renameSync as renameSync3, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
-import { join as join4 } from "path";
-var PROXY_VERSION = "2.24.1";
-var PROXY_CHECKSUMS = Object.freeze({
-  "cloud-sql-proxy.darwin.amd64": "67a38444d03fe77a8b11036f96fe5d2379640088bb6e338737fb48d97c58cf48",
-  "cloud-sql-proxy.darwin.arm64": "fd374545705f2aa687d8e525a2efcbb9d356cc8af60d4dfa1a330cb59a7f9450",
-  "cloud-sql-proxy.linux.386": "cf731f4becfb5a2de61f2998b2d660c5fb8f3067cbd3b86f5783ae9049c06f24",
-  "cloud-sql-proxy.linux.amd64": "fae2766aac9d614a2bdef2f2a7778f3d054f3acd5ff07a81a9e300bd471512eb",
-  "cloud-sql-proxy.linux.arm64": "da49fd73b0d33c0ab8e5dfc19dfb104cdd969ebd355eef8fd3b079c20a723c82",
-  "cloud-sql-proxy.x64.exe": "01ec54c69dbb8118c0b181c33ff1469a5cdb2dddb49eb86b0b173f6c55dea0bc",
-  "cloud-sql-proxy.x86.exe": "98c3b1897c80f2bc0b241b4452c18557a00cd86f89e4d7449c4ff1316e243c44"
-});
-var ASSET_NAME_BY_PLATFORM_ARCH = Object.freeze({
-  "darwin:arm64": "cloud-sql-proxy.darwin.arm64",
-  "darwin:x64": "cloud-sql-proxy.darwin.amd64",
-  "linux:x64": "cloud-sql-proxy.linux.amd64",
-  "linux:arm64": "cloud-sql-proxy.linux.arm64",
-  "linux:ia32": "cloud-sql-proxy.linux.386",
-  "win32:x64": "cloud-sql-proxy.x64.exe",
-  "win32:ia32": "cloud-sql-proxy.x86.exe"
-});
-function defaultVersion() {
-  const override = process.env.MERIDIAN_PROXY_VERSION;
-  if (override !== void 0 && override !== "") return override;
-  return PROXY_VERSION;
-}
-function resolveProxyAsset(options) {
-  const platform = options?.platform ?? process.platform;
-  const arch = options?.arch ?? process.arch;
-  const version = options?.version ?? defaultVersion();
-  const assetName = ASSET_NAME_BY_PLATFORM_ARCH[`${platform}:${arch}`];
-  if (assetName === void 0) {
-    throw new CliError(`The Cloud SQL Auth Proxy has no published build for ${platform}/${arch}.`, {
-      hint: "Set MERIDIAN_PROXY_PATH to the path of a proxy binary you install yourself."
-    });
-  }
-  const downloadUrl = `https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v${version}/${assetName}`;
-  const sha256Value = version === PROXY_VERSION ? PROXY_CHECKSUMS[assetName] : void 0;
-  const fileName = `cloud-sql-proxy-${version}-${platform}-${arch}${platform === "win32" ? ".exe" : ""}`;
-  return {
-    version,
-    assetName,
-    downloadUrl,
-    ...sha256Value !== void 0 ? { sha256: sha256Value } : {},
-    fileName
-  };
-}
-function sha256(data) {
-  return createHash2("sha256").update(data).digest("hex");
-}
-var CHECKSUM_ROW_PATTERN = /\[([^\]]+)]\([^)]*\)\s*\|\s*([0-9a-fA-F]{64})/g;
-function parseChecksumTable(releaseBody) {
-  const table = {};
-  for (const match of releaseBody.matchAll(CHECKSUM_ROW_PATTERN)) {
-    const name = match[1];
-    const hash = match[2];
-    if (name !== void 0 && hash !== void 0) table[name] = hash.toLowerCase();
-  }
-  return table;
-}
-var RELEASE_API_URL = "https://api.github.com/repos/GoogleCloudPlatform/cloud-sql-proxy/releases/tags";
-var checksumCache = /* @__PURE__ */ new Map();
-async function resolveExpectedChecksum(asset, fetchImpl) {
-  if (asset.sha256 !== void 0) return asset.sha256;
-  const cacheKey = `${asset.version}:${asset.assetName}`;
-  const cached = checksumCache.get(cacheKey);
-  if (cached !== void 0) return cached;
-  const skipAllowed = process.env.MERIDIAN_PROXY_SKIP_CHECKSUM === "1";
-  const url = `${RELEASE_API_URL}/v${asset.version}`;
-  let response;
-  try {
-    response = await fetchImpl(url, { headers: { Accept: "application/vnd.github+json" } });
-  } catch (error2) {
-    if (skipAllowed) return void 0;
-    throw new CliError(`Could not reach ${url} to look up the checksum for cloud-sql-proxy v${asset.version}.`, {
-      hint: "Check your network connection, or set MERIDIAN_PROXY_SKIP_CHECKSUM=1 to install without verifying the checksum, at your own risk.",
-      cause: error2
-    });
-  }
-  if (!response.ok) {
-    if (skipAllowed) return void 0;
-    throw new CliError(
-      `Could not determine the sha256 checksum for cloud-sql-proxy v${asset.version} (GitHub release lookup for ${url} returned HTTP ${response.status}).`,
-      {
-        hint: "Set MERIDIAN_PROXY_SKIP_CHECKSUM=1 to install without verifying the checksum, at your own risk."
-      }
-    );
-  }
-  const rawBody = await response.text();
-  let releaseNotes = rawBody;
-  try {
-    const parsed = JSON.parse(rawBody);
-    if (typeof parsed === "object" && parsed !== null && "body" in parsed && typeof parsed.body === "string") {
-      releaseNotes = parsed.body;
-    }
-  } catch {
-  }
-  const checksum = parseChecksumTable(releaseNotes)[asset.assetName];
-  if (checksum !== void 0) {
-    checksumCache.set(cacheKey, checksum);
-    return checksum;
-  }
-  if (skipAllowed) return void 0;
-  throw new CliError(
-    `Could not find a published sha256 checksum for ${asset.assetName} in the cloud-sql-proxy v${asset.version} release notes.`,
-    { hint: "Set MERIDIAN_PROXY_SKIP_CHECKSUM=1 to install without verifying the checksum, at your own risk." }
-  );
-}
-function parseContentLength(header) {
-  if (header === null) return void 0;
-  const value = Number(header);
-  return Number.isFinite(value) ? value : void 0;
-}
-async function readResponseBody(response, onProgress) {
-  const total = parseContentLength(response.headers.get("content-length"));
-  if (response.body === null) {
-    const buffer = Buffer.from(await response.arrayBuffer());
-    onProgress?.(buffer.byteLength, total);
-    return buffer;
-  }
-  const reader = response.body.getReader();
-  const chunks = [];
-  let received = 0;
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value !== void 0) {
-      chunks.push(value);
-      received += value.byteLength;
-      onProgress?.(received, total);
-    }
-  }
-  return Buffer.concat(chunks);
-}
-async function ensureProxyBinary(options = {}) {
-  const overridePath = process.env.MERIDIAN_PROXY_PATH;
-  if (overridePath !== void 0 && overridePath !== "") {
-    if (!existsSync4(overridePath)) {
-      throw new CliError(`MERIDIAN_PROXY_PATH is set to ${overridePath}, but that file does not exist.`, {
-        hint: "Fix or unset MERIDIAN_PROXY_PATH."
-      });
-    }
-    return overridePath;
-  }
-  const asset = resolveProxyAsset(options.version !== void 0 ? { version: options.version } : {});
-  const dir = options.dir ?? proxyBinDir();
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const targetPath = join4(dir, asset.fileName);
-  mkdirSync4(dir, { recursive: true });
-  if (!options.force && existsSync4(targetPath)) {
-    const cached = readFileSync6(targetPath);
-    const expected2 = await resolveExpectedChecksum(asset, fetchImpl);
-    if (expected2 === void 0 || sha256(cached) === expected2) return targetPath;
-    rmSync2(targetPath, { force: true });
-  }
-  const response = await fetchImpl(asset.downloadUrl);
-  if (!response.ok) {
-    throw new CliError(
-      `Failed to download the Cloud SQL Auth Proxy v${asset.version} from ${asset.downloadUrl} (HTTP ${response.status}).`,
-      {
-        hint: "Check your network connection (and any corporate proxy settings), or set MERIDIAN_PROXY_PATH to a proxy binary you install yourself."
-      }
-    );
-  }
-  const buffer = await readResponseBody(response, options.onProgress);
-  const expected = await resolveExpectedChecksum(asset, fetchImpl);
-  const actual = sha256(buffer);
-  if (expected !== void 0 && actual !== expected) {
-    throw new CliError(
-      `Checksum mismatch for ${asset.assetName}: expected ${expected.slice(0, 12)}..., got ${actual.slice(0, 12)}....`,
-      {
-        hint: "This can happen after a corrupted download or an untrusted network. Try again; if it persists, report this."
-      }
-    );
-  }
-  const tmpPath = join4(dir, `.${asset.fileName}.${process.pid}.tmp`);
-  writeFileSync5(tmpPath, buffer);
-  chmodSync3(tmpPath, 493);
-  renameSync3(tmpPath, targetPath);
-  return targetPath;
-}
-
-// src/lib/proxy/proxy.ts
-import { spawn } from "child_process";
-import { createConnection } from "net";
-var PROBE_INTERVAL_MS = 150;
-var KILL_GRACE_MS = 2e3;
-var CRASH_BACKOFFS_MS = [200, 1e3, 3e3];
-var MAX_CRASH_RESTARTS = CRASH_BACKOFFS_MS.length;
-var REFRESH_RETRY_BACKOFFS_MS2 = [3e4, 6e4, 12e4];
-var MIN_REFRESH_DELAY_MS2 = 6e4;
-var LOG_RING_SIZE = 20;
-var STDERR_TAIL_LINES = 10;
-function buildProxyArgs(input2) {
-  return ["--address", input2.host, "--port", String(input2.port), input2.instanceConnectionName];
-}
-function buildProxyEnv(accessToken, base = process.env) {
-  return { ...base, CSQL_PROXY_TOKEN: accessToken };
-}
-function defaultProbe(host, port) {
-  return new Promise((resolve2) => {
-    const socket = createConnection({ host, port });
-    const finish = (ok) => {
-      socket.removeAllListeners();
-      socket.destroy();
-      resolve2(ok);
-    };
-    socket.once("connect", () => finish(true));
-    socket.once("error", () => finish(false));
-    socket.setTimeout(1e3, () => finish(false));
-  });
-}
-function computeRefreshDelayMs(token, refreshSkewMs, assumedLifetimeMs) {
-  let expiresAtMs;
-  if (token.expires_at !== void 0) {
-    const parsed = new Date(token.expires_at).getTime();
-    if (!Number.isNaN(parsed)) expiresAtMs = parsed;
-  }
-  const effectiveExpiryMs = expiresAtMs ?? Date.now() + assumedLifetimeMs;
-  return Math.max(effectiveExpiryMs - Date.now() - refreshSkewMs, MIN_REFRESH_DELAY_MS2);
-}
-function buildStartupFailureError(code, signal, lastLines) {
-  const tail = lastLines.slice(-STDERR_TAIL_LINES).join("\n");
-  const lower = tail.toLowerCase();
-  let hint2 = "Run `meridian dev` again; if this keeps happening, check the instance connection name and your network.";
-  if (lower.includes("iam") || lower.includes("permission") || lower.includes("forbidden")) {
-    hint2 = "The Meridian API's service account may be missing roles/cloudsql.client on the dev Cloud SQL instance. Contact Meridian support.";
-  } else if (lower.includes("invalid token") || lower.includes("401") || lower.includes("unauthorized")) {
-    hint2 = "The access token appears to have expired. Retry `meridian dev` to mint a fresh one.";
-  } else if (lower.includes("address already in use")) {
-    hint2 = "Another process is already listening on that port. Free it up, or retry with a different port.";
-  }
-  const summary = `The Cloud SQL Auth Proxy exited before it was ready (code ${code ?? "null"}, signal ${signal ?? "null"}).`;
-  return new CliError(tail === "" ? summary : `${summary}
-${tail}`, { hint: hint2 });
-}
-function waitForReady(child, probeImpl, host, port, timeoutMs, setTimeoutImpl, getLastLines) {
-  return new Promise((resolve2, reject) => {
-    let settled = false;
-    let pollTimer;
-    let timeoutTimer;
-    const cleanup = () => {
-      if (pollTimer !== void 0) clearTimeout(pollTimer);
-      if (timeoutTimer !== void 0) clearTimeout(timeoutTimer);
-      child.off("exit", onExit);
-    };
-    function onExit(code, signal) {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(buildStartupFailureError(code, signal, getLastLines()));
-    }
-    function poll() {
-      if (settled) return;
-      probeImpl(host, port).then((ok) => {
-        if (settled) return;
-        if (ok) {
-          settled = true;
-          cleanup();
-          resolve2();
-        } else {
-          pollTimer = setTimeoutImpl(poll, PROBE_INTERVAL_MS);
-        }
-      }).catch(() => {
-        if (!settled) pollTimer = setTimeoutImpl(poll, PROBE_INTERVAL_MS);
-      });
-    }
-    child.on("exit", onExit);
-    timeoutTimer = setTimeoutImpl(() => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(
-        new CliError(`Timed out after ${timeoutMs}ms waiting for the Cloud SQL Auth Proxy to accept connections.`, {
-          hint: "The instance may be slow to reach, or readyTimeoutMs may need to be raised."
-        })
-      );
-    }, timeoutMs);
-    poll();
-  });
-}
-async function startProxy(options) {
-  const host = options.host ?? "127.0.0.1";
-  const spawnImpl = options.spawnImpl ?? spawn;
-  const probeImpl = options.probeImpl ?? defaultProbe;
-  const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
-  const refreshSkewMs = options.refreshSkewMs ?? 5 * 6e4;
-  const assumedLifetimeMs = options.assumedLifetimeMs ?? 55 * 6e4;
-  const readyTimeoutMs = options.readyTimeoutMs ?? 3e4;
-  const emit = (event) => options.onEvent?.(event);
-  let stopped = false;
-  let running = false;
-  let expectingExit = false;
-  let currentToken = options.token;
-  let child;
-  let refreshTimer;
-  let crashTimer;
-  let refreshBackoffIndex = 0;
-  let crashRestartsRemaining = MAX_CRASH_RESTARTS;
-  let attemptCounter = 0;
-  let cleanupFns = [];
-  const knownTokens = /* @__PURE__ */ new Set();
-  const logRing = [];
-  function trackToken(token) {
-    if (token.access_token !== "") knownTokens.add(token.access_token);
-  }
-  function redact(text) {
-    let result = text;
-    for (const token of knownTokens) result = result.split(token).join("<redacted>");
-    return result;
-  }
-  function pushLog(line) {
-    const safeLine = redact(line);
-    logRing.push(safeLine);
-    if (logRing.length > LOG_RING_SIZE) logRing.shift();
-    emit({ type: "log", line: safeLine });
-  }
-  function wireOutput(c) {
-    for (const stream of [c.stdout, c.stderr]) {
-      if (stream === null) continue;
-      let buffer = "";
-      const onData = (chunk) => {
-        buffer += chunk.toString();
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) pushLog(line);
-      };
-      stream.on("data", onData);
-      cleanupFns.push(() => stream.off("data", onData));
-    }
-  }
-  function wireExit(c) {
-    c.once("exit", (code, signal) => {
-      if (child !== c) return;
-      const wasRunning = running;
-      const wasExpected = expectingExit;
-      running = false;
-      expectingExit = false;
-      emit({ type: "exit", code, signal });
-      if (stopped || wasExpected || !wasRunning) return;
-      void handleCrash();
-    });
-  }
-  async function spawnChild() {
-    attemptCounter += 1;
-    emit({ type: "starting", attempt: attemptCounter });
-    const args = buildProxyArgs({
-      instanceConnectionName: options.instanceConnectionName,
-      host,
-      port: options.port
-    });
-    const c = spawnImpl(options.binaryPath, args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      env: buildProxyEnv(currentToken.access_token, options.env)
-    });
-    child = c;
-    wireOutput(c);
-    wireExit(c);
-    try {
-      await waitForReady(c, probeImpl, host, options.port, readyTimeoutMs, setTimeoutImpl, () => logRing.slice());
-    } catch (error2) {
-      expectingExit = true;
-      await killChild(c);
-      if (child === c) child = void 0;
-      throw error2;
-    }
-    emit({ type: "ready", port: options.port });
-  }
-  function killChild(c) {
-    if (c.exitCode !== null || c.signalCode !== null) return Promise.resolve();
-    return new Promise((resolve2) => {
-      let settled = false;
-      let killTimer;
-      const onExit = () => {
-        if (settled) return;
-        settled = true;
-        if (killTimer !== void 0) clearTimeout(killTimer);
-        resolve2();
-      };
-      c.once("exit", onExit);
-      c.kill("SIGTERM");
-      killTimer = setTimeoutImpl(() => {
-        if (!settled) c.kill("SIGKILL");
-      }, KILL_GRACE_MS);
-    });
-  }
-  function scheduleRefresh(token) {
-    if (stopped || options.refreshToken === void 0) return;
-    if (refreshTimer !== void 0) clearTimeout(refreshTimer);
-    const delayMs = computeRefreshDelayMs(token, refreshSkewMs, assumedLifetimeMs);
-    refreshTimer = setTimeoutImpl(() => {
-      refreshTimer = void 0;
-      void handleRefreshFire();
-    }, delayMs);
-  }
-  function scheduleRefreshRetry() {
-    if (stopped) return;
-    const delayMs = REFRESH_RETRY_BACKOFFS_MS2[Math.min(refreshBackoffIndex, REFRESH_RETRY_BACKOFFS_MS2.length - 1)] ?? 12e4;
-    refreshBackoffIndex += 1;
-    if (refreshTimer !== void 0) clearTimeout(refreshTimer);
-    refreshTimer = setTimeoutImpl(() => {
-      refreshTimer = void 0;
-      void handleRefreshFire();
-    }, delayMs);
-  }
-  async function handleRefreshFire() {
-    if (stopped || options.refreshToken === void 0) return;
-    let newToken;
-    try {
-      newToken = await options.refreshToken();
-    } catch (error2) {
-      emit({ type: "error", message: redact(`Token refresh failed: ${describeError(error2)}`) });
-      scheduleRefreshRetry();
-      return;
-    }
-    if (stopped) return;
-    trackToken(newToken);
-    currentToken = newToken;
-    expectingExit = true;
-    emit({ type: "restarting", reason: "token-refresh" });
-    try {
-      const previous = child;
-      if (previous !== void 0) await killChild(previous);
-      await spawnChild();
-    } catch (error2) {
-      emit({ type: "error", message: redact(`Restart after token refresh failed: ${describeError(error2)}`) });
-      scheduleRefreshRetry();
-      return;
-    }
-    running = true;
-    refreshBackoffIndex = 0;
-    emit({ type: "token-refreshed", ...newToken.expires_at !== void 0 ? { expiresAt: newToken.expires_at } : {} });
-    scheduleRefresh(newToken);
-  }
-  async function handleCrash() {
-    if (stopped) return;
-    if (crashRestartsRemaining <= 0) {
-      const tail = logRing.slice(-STDERR_TAIL_LINES).join("\n");
-      emit({
-        type: "error",
-        message: `The Cloud SQL Auth Proxy crashed repeatedly and could not be restarted.${tail === "" ? "" : `
-${tail}`}`
-      });
-      return;
-    }
-    const attemptIndex = MAX_CRASH_RESTARTS - crashRestartsRemaining;
-    const delayMs = CRASH_BACKOFFS_MS[attemptIndex] ?? (CRASH_BACKOFFS_MS[CRASH_BACKOFFS_MS.length - 1] ?? 3e3);
-    crashRestartsRemaining -= 1;
-    emit({ type: "restarting", reason: "crash" });
-    crashTimer = setTimeoutImpl(() => {
-      crashTimer = void 0;
-      if (stopped) return;
-      spawnChild().then(() => {
-        running = true;
-      }).catch((error2) => {
-        emit({ type: "error", message: redact(describeError(error2)) });
-        void handleCrash();
-      });
-    }, delayMs);
-  }
-  async function refresh() {
-    if (stopped) return;
-    if (options.refreshToken === void 0) {
-      throw new CliError("Cannot refresh the Cloud SQL Auth Proxy token: no refreshToken() was configured.");
-    }
-    if (refreshTimer !== void 0) {
-      clearTimeout(refreshTimer);
-      refreshTimer = void 0;
-    }
-    refreshBackoffIndex = 0;
-    await handleRefreshFire();
-  }
-  async function stop() {
-    if (stopped) return;
-    stopped = true;
-    if (refreshTimer !== void 0) clearTimeout(refreshTimer);
-    refreshTimer = void 0;
-    if (crashTimer !== void 0) clearTimeout(crashTimer);
-    crashTimer = void 0;
-    for (const cleanup of cleanupFns) cleanup();
-    cleanupFns = [];
-    const current2 = child;
-    if (current2 !== void 0) {
-      expectingExit = true;
-      await killChild(current2);
-    }
-    running = false;
-    child = void 0;
-  }
-  trackToken(currentToken);
-  await spawnChild();
-  running = true;
-  scheduleRefresh(currentToken);
-  return {
-    host,
-    port: options.port,
-    instanceConnectionName: options.instanceConnectionName,
-    get running() {
-      return running;
-    },
-    refresh,
-    stop
-  };
-}
-
 // src/lib/signals.ts
 var SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 var SIGNAL_EXIT_CODES = {
@@ -3379,8 +2872,6 @@ function defaultSleep(ms) {
 }
 function resolveDeps(overrides) {
   return {
-    ensureProxyBinary,
-    startProxy,
     issueGatewayCertificate,
     startGatewayForwarder,
     findFreePort,
@@ -3453,15 +2944,6 @@ async function ensureDevDatabaseReady(client, appId, options = {}) {
     { success: (db) => `Developer database "${db.database}" is ready.` }
   );
 }
-function toProxyToken(token) {
-  return {
-    access_token: token.access_token,
-    ...typeof token.expires_at === "string" ? { expires_at: token.expires_at } : {}
-  };
-}
-function formatMb(bytes) {
-  return (bytes / (1024 * 1024)).toFixed(1);
-}
 function firstNonEmpty(...values) {
   for (const value of values) {
     if (typeof value === "string" && value.trim() !== "") return value;
@@ -3483,32 +2965,6 @@ function logEnvPatch(result, databaseUrl, wroteShadow) {
   }
   if (result.backedUp) detail(`Backed up the previous file to ${result.path}.backup`);
 }
-function handleProxyEvent(event) {
-  switch (event.type) {
-    case "starting":
-      debug(`Starting the Cloud SQL Auth Proxy (attempt ${event.attempt}).`);
-      return;
-    case "ready":
-      debug(`Cloud SQL Auth Proxy listening on port ${event.port}.`);
-      return;
-    case "log":
-      debug(event.line);
-      return;
-    case "token-refreshed":
-      step("Refreshed the Cloud SQL Auth Proxy token.");
-      return;
-    case "restarting":
-      if (event.reason === "crash") warn("The Cloud SQL Auth Proxy crashed; restarting it.");
-      else debug("Restarting the Cloud SQL Auth Proxy with a refreshed token...");
-      return;
-    case "exit":
-      debug(`Cloud SQL Auth Proxy exited (code ${event.code ?? "null"}, signal ${event.signal ?? "null"}).`);
-      return;
-    case "error":
-      warn(`Cloud SQL Auth Proxy error: ${event.message} Restart \`meridian dev\` if the database becomes unreachable.`);
-      return;
-  }
-}
 async function pickLocalPort(options, deps) {
   const findPortOptions = { start: DEFAULT_PORT_START };
   if (options.port !== void 0) findPortOptions.preferred = options.port;
@@ -3520,50 +2976,6 @@ async function pickLocalPort(options, deps) {
   }
   return port;
 }
-async function startProxyEndpoint(client, appId, devDatabase, credentials, options, deps) {
-  const proxyToken = await withSpinner(
-    "Requesting a Cloud SQL Auth Proxy token...",
-    () => client.issueProxyToken(appId),
-    { success: "Issued a Cloud SQL Auth Proxy token." }
-  );
-  const binaryPath = await withSpinner(
-    "Preparing the Cloud SQL Auth Proxy...",
-    (spinner2) => {
-      const ensureOptions = {
-        onProgress: (received, total) => {
-          spinner2.update(
-            total !== void 0 ? `Downloading the Cloud SQL Auth Proxy... (${formatMb(received)}/${formatMb(total)} MB)` : `Downloading the Cloud SQL Auth Proxy... (${formatMb(received)} MB)`
-          );
-        }
-      };
-      return deps.ensureProxyBinary(ensureOptions);
-    },
-    { success: "Cloud SQL Auth Proxy is ready." }
-  );
-  const port = await pickLocalPort(options, deps);
-  const instanceConnectionName = firstNonEmpty(
-    credentials.instance_connection_name,
-    proxyToken.instance_connection_name,
-    devDatabase.instance_connection_name
-  );
-  if (instanceConnectionName === void 0) {
-    throw new CliError("The Meridian API did not return a Cloud SQL instance connection name.", {
-      hint: "Try again, or contact Meridian support if this persists."
-    });
-  }
-  return withSpinner(
-    `Starting the Cloud SQL Auth Proxy on 127.0.0.1:${port}...`,
-    () => deps.startProxy({
-      binaryPath,
-      instanceConnectionName,
-      token: toProxyToken(proxyToken),
-      port,
-      ...options.refreshToken !== false ? { refreshToken: async () => toProxyToken(await client.issueProxyToken(appId)) } : {},
-      onEvent: handleProxyEvent
-    }),
-    { success: `Cloud SQL Auth Proxy listening on 127.0.0.1:${port}.` }
-  );
-}
 function handleForwarderEvent(event) {
   switch (event.type) {
     case "ready":
@@ -3616,8 +3028,8 @@ async function startDevSession(options = {}) {
         success: (creds) => `Fetched credentials for database "${creds.database}"${typeof creds.expires_at === "string" ? ` (expire ${creds.expires_at})` : ""}.`
       }
     );
-    const access = devDatabase.access === "gateway" ? "gateway" : "proxy";
-    proxy = access === "gateway" ? await startGatewayEndpoint(client, appId, credentials, options, deps) : await startProxyEndpoint(client, appId, devDatabase, credentials, options, deps);
+    const access = "gateway";
+    proxy = await startGatewayEndpoint(client, appId, credentials, options, deps);
     const connection = connectionInfoFromCredentials(credentials, { host: proxy.host, port: proxy.port });
     if (options.waitForDb !== false) {
       await withSpinner(
@@ -3918,7 +3330,7 @@ function registerDbCredentialCommand(db) {
 
 // src/commands/db-shell-repl.ts
 import { accessSync, constants as fsConstants } from "fs";
-import { delimiter as delimiter2, join as join5 } from "path";
+import { delimiter as delimiter2, join as join4 } from "path";
 import { createInterface } from "readline";
 function candidateNames(name) {
   if (process.platform !== "win32") return [name];
@@ -3933,7 +3345,7 @@ function findExecutable(name) {
   const candidates = candidateNames(name);
   for (const dir of dirs) {
     for (const candidate of candidates) {
-      const fullPath = join5(dir, candidate);
+      const fullPath = join4(dir, candidate);
       try {
         accessSync(fullPath, fsConstants.X_OK);
         return fullPath;
@@ -4068,7 +3480,7 @@ function defaultDbDeps() {
 function hasSeedConfigured(root) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync7(join6(root, "package.json"), "utf8"));
+    parsed = JSON.parse(readFileSync6(join5(root, "package.json"), "utf8"));
   } catch {
     return false;
   }
@@ -4247,7 +3659,7 @@ function registerDbCommand(program) {
   db.action(() => {
     db.outputHelp();
   });
-  db.command("reset").description("Drop and recreate every table in the developer database (keeps the MySQL user).").option("--migrate", "run `npx prisma migrate deploy` afterwards, without asking").option("--seed", "run `npx prisma db seed` afterwards, without asking").option("--port <port>", "local port for the Cloud SQL Auth Proxy", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to update (defaults to .env)").action(async (opts) => {
+  db.command("reset").description("Drop and recreate every table in the developer database (keeps the MySQL user).").option("--migrate", "run `npx prisma migrate deploy` afterwards, without asking").option("--seed", "run `npx prisma db seed` afterwards, without asking").option("--port <port>", "local port for the database gateway forwarder", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to update (defaults to .env)").action(async (opts) => {
     await runAndSetExitCode2(
       () => runDbReset({
         ...opts.migrate === true ? { migrate: true } : {},
@@ -4257,7 +3669,7 @@ function registerDbCommand(program) {
       })
     );
   });
-  db.command("seed").description("Run `npx prisma db seed` with the Cloud SQL Auth Proxy up and DATABASE_URL set.").option("--port <port>", "local port for the Cloud SQL Auth Proxy", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to update (defaults to .env)").passThroughOptions().argument("[args...]", "extra arguments forwarded to `npx prisma db seed` (put them after `--`)").action(async (args, opts) => {
+  db.command("seed").description("Run `npx prisma db seed` with the database connection up and DATABASE_URL set.").option("--port <port>", "local port for the database gateway forwarder", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to update (defaults to .env)").passThroughOptions().argument("[args...]", "extra arguments forwarded to `npx prisma db seed` (put them after `--`)").action(async (args, opts) => {
     await runAndSetExitCode2(
       () => runDbSeed({
         ...opts.port !== void 0 ? { port: opts.port } : {},
@@ -4266,7 +3678,7 @@ function registerDbCommand(program) {
       })
     );
   });
-  db.command("shell").description("Open a SQL shell against the developer database (the `mysql` client if available, otherwise a built-in REPL).").option("--port <port>", "local port for the Cloud SQL Auth Proxy", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to read/patch (defaults to .env)").option("--repl", "force the built-in SQL REPL even when `mysql` is on PATH").option("-e, --execute <sql>", "run one SQL statement and exit").option("--no-env", "do not patch DATABASE_URL into the project's .env file").action(async (opts) => {
+  db.command("shell").description("Open a SQL shell against the developer database (the `mysql` client if available, otherwise a built-in REPL).").option("--port <port>", "local port for the database gateway forwarder", (value) => parsePortOption(value)).option("--env-file <file>", "project .env file to read/patch (defaults to .env)").option("--repl", "force the built-in SQL REPL even when `mysql` is on PATH").option("-e, --execute <sql>", "run one SQL statement and exit").option("--no-env", "do not patch DATABASE_URL into the project's .env file").action(async (opts) => {
     await runAndSetExitCode2(
       () => runDbShell({
         ...opts.port !== void 0 ? { port: opts.port } : {},
@@ -4405,7 +3817,7 @@ async function runDev(options = {}) {
   }
 }
 function registerDevCommand(program) {
-  program.command("dev").description("Run the managed developer database proxy and your app's dev server together.").option("--port <port>", "preferred local port for the Cloud SQL Auth Proxy").option("--env-file <file>", "the .env file to patch, relative to the project root (default .env)").option("--no-env", "don't touch any .env file; just print the DATABASE_URL for manual use").argument("[command...]", "run this instead of the app's dev script, e.g. `meridian dev -- next dev`").passThroughOptions().action(async (command, opts) => {
+  program.command("dev").description("Run the managed developer database proxy and your app's dev server together.").option("--port <port>", "preferred local port for the database gateway forwarder").option("--env-file <file>", "the .env file to patch, relative to the project root (default .env)").option("--no-env", "don't touch any .env file; just print the DATABASE_URL for manual use").argument("[command...]", "run this instead of the app's dev script, e.g. `meridian dev -- next dev`").passThroughOptions().action(async (command, opts) => {
     const port = parsePortOption(opts.port);
     const code = await runDev({
       ...command.length > 0 ? { command } : {},
@@ -4418,8 +3830,8 @@ function registerDevCommand(program) {
 }
 
 // src/commands/link.ts
-import { existsSync as existsSync5 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { join as join6 } from "path";
 function defaultDeps3() {
   return { createClient: createApiClient };
 }
@@ -4438,7 +3850,7 @@ async function runLink(options = {}) {
   const deps = { ...defaultDeps3(), ...options.deps };
   const json = isJsonOutput();
   const root = resolveProjectRoot(workingDirectory()) ?? workingDirectory();
-  if (!existsSync5(join7(root, "package.json"))) {
+  if (!existsSync4(join6(root, "package.json"))) {
     log(`No package.json found in ${style.path(root)}.`);
     const proceed = await confirmAction({
       message: "Link this directory to a Meridian app anyway?",
@@ -4656,7 +4068,8 @@ async function runLogin(options = {}) {
   const json = isJsonOutput();
   if (options.force !== true) {
     const auth = getAuth();
-    if (auth !== null) {
+    const sameApi = auth !== null && storedTokenApiBaseUrl() === resolveApiBaseUrl(getGlobalOptions().apiUrl);
+    if (auth !== null && sameApi) {
       const client2 = deps.createClient({ requireAuth: false, token: auth.token });
       try {
         const me = await client2.getMe();
@@ -4683,7 +4096,9 @@ async function runLogin(options = {}) {
     hostname,
     onCode: async (code) => {
       const target = code.verification_uri_complete ?? code.verification_uri;
-      if (!json) {
+      if (json) {
+        hint(`Enter the code ${formatUserCode(code.user_code)} at ${code.verification_uri} to approve this login.`);
+      } else {
         log();
         log(`  ${style.bold(formatUserCode(code.user_code))}`);
         log();
@@ -4709,12 +4124,11 @@ async function runLogin(options = {}) {
   });
   wait.stop();
   const user = toConfigUser(tokenResponse.user);
-  const storeApiBaseUrl = client.baseUrl !== DEFAULT_API_BASE_URL;
   updateConfig({
     token: tokenResponse.token,
     ...tokenResponse.expires_at !== void 0 ? { token_expires_at: tokenResponse.expires_at } : {},
     user,
-    ...storeApiBaseUrl ? { api_base_url: client.baseUrl } : {}
+    api_base_url: client.baseUrl
   });
   if (json) {
     printLoginJson(user, tokenResponse.expires_at, client.baseUrl);
@@ -4752,7 +4166,7 @@ function registerLogoutCommand(program) {
 
 // src/lib/db/snapshot.ts
 import { mkdir, readFile, readdir, rm, stat } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join7 } from "path";
 function snapshotFileName(date = /* @__PURE__ */ new Date()) {
   return `${date.toISOString().replace(/[:.]/g, "-")}.sql`;
 }
@@ -4771,7 +4185,7 @@ async function createSnapshot(info, options) {
   }
   const dump = options.dumpImpl ?? await loadMysqldump();
   await mkdir(options.dir, { recursive: true });
-  const path = join8(options.dir, snapshotFileName(createdAt));
+  const path = join7(options.dir, snapshotFileName(createdAt));
   try {
     await dump({
       connection: {
@@ -4977,7 +4391,7 @@ async function listSnapshots(dir) {
   const names = entries.filter((name) => name.endsWith(".sql")).sort().reverse();
   const results = [];
   for (const name of names) {
-    const path = join8(dir, name);
+    const path = join7(dir, name);
     const { size } = await stat(path);
     results.push({ path, name, bytes: size, createdAt: parseSnapshotDate(name) });
   }
@@ -5173,7 +4587,7 @@ function registerMigrateCommand(program) {
   ).option("--skip-snapshot", "run without a pre-migration snapshot (no rollback is possible)").option(
     "--allow-foreign-migrations",
     "run even when prisma/migrations was generated for SQLite or Postgres and cannot apply to MySQL"
-  ).option("--no-rollback", "keep a snapshot but do not automatically restore it after a failed migration").option("--keep-snapshots <n>", "number of recent snapshots to keep after a successful migration", "5").option("--port <port>", "preferred local port for the Cloud SQL Auth Proxy").option("--env-file <file>", "path (relative to the project root) of the .env file to patch with DATABASE_URL").argument("[prismaArgs...]", "extra arguments forwarded to `prisma migrate dev` verbatim, after --").passThroughOptions().action(async (prismaArgs, opts) => {
+  ).option("--no-rollback", "keep a snapshot but do not automatically restore it after a failed migration").option("--keep-snapshots <n>", "number of recent snapshots to keep after a successful migration", "5").option("--port <port>", "preferred local port for the database gateway forwarder").option("--env-file <file>", "path (relative to the project root) of the .env file to patch with DATABASE_URL").argument("[prismaArgs...]", "extra arguments forwarded to `prisma migrate dev` verbatim, after --").passThroughOptions().action(async (prismaArgs, opts) => {
     const keepSnapshots = parseIntegerOption(opts.keepSnapshots, "--keep-snapshots", { min: 0 });
     const port = parsePortOption(opts.port);
     const exitCode = await runMigrate({
@@ -5189,6 +4603,208 @@ function registerMigrateCommand(program) {
   });
 }
 
+// src/commands/skills.ts
+import { cpSync, existsSync as existsSync5, mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname5, join as join8, relative as relative2 } from "path";
+import { fileURLToPath } from "url";
+var MCP_SERVER_URL = "https://mcp.the-meridian.ai/mcp";
+var SERVER_NAME = "meridian";
+var AGENT_IDS = ["claude", "codex", "cursor"];
+var AGENTS = {
+  claude: {
+    label: "Claude Code",
+    skillDir: ".claude/skills/meridian",
+    markers: [".claude", "CLAUDE.md", ".mcp.json"],
+    mcpConfig: ".mcp.json",
+    connectStep: "In Claude Code, run `/mcp` and approve Meridian in the browser."
+  },
+  codex: {
+    label: "Codex",
+    skillDir: ".agents/skills/meridian",
+    markers: [".codex", ".agents", "AGENTS.md"],
+    mcpConfig: ".codex/config.toml",
+    connectStep: "Trust this project in Codex, then run `codex mcp login meridian`."
+  },
+  cursor: {
+    label: "Cursor",
+    skillDir: ".cursor/skills/meridian",
+    markers: [".cursor", ".cursorrules"],
+    mcpConfig: ".cursor/mcp.json",
+    connectStep: "In Cursor, open Customize in the sidebar (Settings > Tools & MCP before Cursor 3) and connect Meridian."
+  }
+};
+function bundledSkillDir() {
+  const candidates = [
+    new URL("./skill", import.meta.url),
+    new URL("../../../skill/plugins/meridian/skills/meridian", import.meta.url)
+  ].map((url) => fileURLToPath(url));
+  const found = candidates.find((dir) => existsSync5(join8(dir, "SKILL.md")));
+  if (found === void 0) {
+    throw new CliError("This build of the Meridian CLI does not include the agent skill.", {
+      hint: "Reinstall it with `npm install -g @the-meridian/cli@latest`."
+    });
+  }
+  return found;
+}
+function parseAgents(raw) {
+  const names = raw.split(",").map((name) => name.trim().toLowerCase()).filter((name) => name !== "");
+  if (names.includes("all")) return [...AGENT_IDS];
+  const unknown = names.filter((name) => !AGENT_IDS.includes(name));
+  if (unknown.length > 0 || names.length === 0) {
+    throw new CliError(`Unknown agent: ${unknown.join(", ") || raw}.`, {
+      hint: `Use one or more of ${AGENT_IDS.join(", ")}, comma-separated, or \`all\`.`
+    });
+  }
+  return [...new Set(names)];
+}
+function detectAgents(root) {
+  const detected = AGENT_IDS.filter((id) => AGENTS[id].markers.some((marker) => existsSync5(join8(root, marker))));
+  return detected.length > 0 ? detected : [...AGENT_IDS];
+}
+function listFiles(dir, base = dir) {
+  return readdirSync2(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join8(dir, entry.name);
+    return entry.isDirectory() ? listFiles(path, base) : [relative2(base, path)];
+  }).sort();
+}
+function sameTree(a, b) {
+  const filesA = listFiles(a);
+  const filesB = listFiles(b);
+  if (filesA.join("\n") !== filesB.join("\n")) return false;
+  return filesA.every((file) => readFileSync7(join8(a, file)).equals(readFileSync7(join8(b, file))));
+}
+async function installSkill(root, agent, sourceDir, confirmImpl) {
+  const target = join8(root, AGENTS[agent].skillDir);
+  if (existsSync5(target)) {
+    if (sameTree(sourceDir, target)) return "unchanged";
+    const replace = await confirmAction({
+      message: `Replace ${AGENTS[agent].skillDir} with this CLI's version? Changes made in that folder are lost.`,
+      default: true,
+      ...confirmImpl !== void 0 ? { promptImpl: confirmImpl } : {}
+    });
+    if (!replace) return "skipped";
+    rmSync2(target, { recursive: true, force: true });
+    cpSync(sourceDir, target, { recursive: true });
+    return "updated";
+  }
+  mkdirSync4(dirname5(target), { recursive: true });
+  cpSync(sourceDir, target, { recursive: true });
+  return "created";
+}
+function readJsonObject(path) {
+  if (!existsSync5(path)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync7(path, "utf8"));
+  } catch {
+    throw new CliError(`${path} is not valid JSON, so the Meridian MCP server was not added to it.`, {
+      hint: "Fix the file, or rerun with `--no-mcp` and add the server by hand."
+    });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${path} does not hold a JSON object, so the Meridian MCP server was not added to it.`, {
+      hint: "Fix the file, or rerun with `--no-mcp` and add the server by hand."
+    });
+  }
+  return parsed;
+}
+function mergeJsonServer(path, server) {
+  const config = readJsonObject(path);
+  const existing = config.mcpServers;
+  const servers = existing !== null && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+  const current2 = servers[SERVER_NAME];
+  if (current2 !== void 0) {
+    const url = current2?.url;
+    return url === MCP_SERVER_URL ? "present" : "conflict";
+  }
+  config.mcpServers = { ...servers, [SERVER_NAME]: server };
+  mkdirSync4(dirname5(path), { recursive: true });
+  writeFileSync5(path, `${JSON.stringify(config, null, 2)}
+`);
+  return "added";
+}
+function mergeTomlServer(path) {
+  const current2 = existsSync5(path) ? readFileSync7(path, "utf8") : "";
+  if (/^\s*\[mcp_servers\.meridian\]\s*$/m.test(current2)) {
+    return current2.includes(`"${MCP_SERVER_URL}"`) ? "present" : "conflict";
+  }
+  const separator = current2 === "" || current2.endsWith("\n\n") ? "" : current2.endsWith("\n") ? "\n" : "\n\n";
+  mkdirSync4(dirname5(path), { recursive: true });
+  writeFileSync5(path, `${current2}${separator}[mcp_servers.meridian]
+url = "${MCP_SERVER_URL}"
+`);
+  return "added";
+}
+function installMcp(root, agent) {
+  const path = join8(root, AGENTS[agent].mcpConfig);
+  switch (agent) {
+    case "claude":
+      return mergeJsonServer(path, { type: "http", url: MCP_SERVER_URL });
+    case "cursor":
+      return mergeJsonServer(path, { url: MCP_SERVER_URL });
+    case "codex":
+      return mergeTomlServer(path);
+  }
+}
+var SKILL_MESSAGES = {
+  created: "installed",
+  updated: "updated",
+  unchanged: "already up to date",
+  skipped: "left as it was"
+};
+async function runSkillsInstall(options = {}) {
+  const json = isJsonOutput();
+  const root = readProject(workingDirectory())?.root ?? workingDirectory();
+  const sourceDir = options.deps?.sourceDir ?? bundledSkillDir();
+  const agents = options.agents ?? detectAgents(root);
+  const result = { root, skills: [], mcp: [] };
+  for (const agent of agents) {
+    const status = await installSkill(root, agent, sourceDir, options.deps?.confirmImpl);
+    result.skills.push({ agent, path: AGENTS[agent].skillDir, status });
+  }
+  if (options.mcp !== false) {
+    for (const agent of agents) {
+      result.mcp.push({ agent, path: AGENTS[agent].mcpConfig, status: installMcp(root, agent) });
+    }
+  }
+  if (json) {
+    printJson(result);
+    return result;
+  }
+  for (const skill of result.skills) {
+    success(`${AGENTS[skill.agent].label}: skill ${SKILL_MESSAGES[skill.status]} in ${skill.path}`);
+  }
+  for (const entry of result.mcp) {
+    const label = AGENTS[entry.agent].label;
+    if (entry.status === "conflict") {
+      warn(`${label}: ${entry.path} already has a "${SERVER_NAME}" server with another URL. It was left alone.`);
+    } else {
+      success(`${label}: Meridian MCP server ${entry.status === "added" ? "added to" : "already in"} ${entry.path}`);
+    }
+  }
+  const toConnect = result.mcp.filter((entry) => entry.status === "added");
+  if (toConnect.length > 0) {
+    log();
+    for (const entry of toConnect) hint(AGENTS[entry.agent].connectStep);
+  }
+  hint("Commit these folders so your teammates' agents get the skill too.");
+  return result;
+}
+function registerSkillsCommand(program) {
+  const skills = program.command("skills").description("Install the Meridian agent skill for Claude Code, Codex and Cursor.");
+  skills.action(() => {
+    skills.outputHelp();
+  });
+  skills.command("install").description(
+    "Write the Meridian skill into this project and add the Meridian MCP server to each agent's config. Run it again after upgrading the CLI to update the skill."
+  ).option("--agent <agents>", `agents to install for: ${AGENT_IDS.join(", ")} or all (default: the ones this project uses)`).option("--no-mcp", "install the skill only, without the MCP server config").action(async (opts) => {
+    await runSkillsInstall({
+      ...opts.agent !== void 0 ? { agents: parseAgents(opts.agent) } : {},
+      ...opts.mcp === false ? { mcp: false } : {}
+    });
+  });
+}
+
 // src/commands/unlink.ts
 async function runUnlink(options = {}) {
   const deps = { ...options.deps };
@@ -5421,6 +5037,7 @@ function buildProgram() {
   registerDevCommand(program);
   registerMigrateCommand(program);
   registerDbCommand(program);
+  registerSkillsCommand(program);
   addGlobalFlagsToSubcommands(program);
   return program;
 }
@@ -5436,7 +5053,7 @@ function isMainModule() {
   const entry = process.argv[1];
   if (entry === void 0) return false;
   try {
-    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    return realpathSync(entry) === realpathSync(fileURLToPath2(import.meta.url));
   } catch {
     return false;
   }