@cubis/foundry 0.3.21 → 0.3.23

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.3.23] - 2026-02-26
+
+### Added
+
+- Added a root `CHANGELOG.md` and npm-visible changelog section in `README.md`.
+- Included `CHANGELOG.md` in published npm package files.
+
+## [0.3.22] - 2026-02-26
+
+### Added
+
+- Added Antigravity-only default `StitchMCP` runtime setup in Gemini settings.
+- Added `--stitch-api-key` and `STITCH_API_KEY` support for Stitch MCP config.
+- Added managed Stitch MCP definition output in `.cbx/mcp/antigravity/stitch.json`.
+- Added Stitch and Postman API key setup links and guidance in `README.md`.
+
+## [0.3.21] - 2026-02-26
+
+### Changed
+
+- Split Postman MCP management from skill folder into managed `.cbx/mcp/<platform>/postman.json`.
+- Added centralized Postman config via `cbx_config.json`.
+- Added MCP scope controls (`project/workspace/global/user`) with platform-aware runtime placement.
+- Kept rules/engineering artifacts in workspace scope while defaulting skills/powers install to global scope.

package/README.md

@@ -9,6 +9,11 @@ Primary support in this release:
 - Codex
 - Copilot (VS Code Chat + Copilot CLI)
 
+## Changelog
+
+- Latest release notes are visible here on npm and tracked in [`CHANGELOG.md`](./CHANGELOG.md).
+- GitHub view: [CHANGELOG.md](https://github.com/CUBETIQ/cubis-foundry/blob/main/CHANGELOG.md)
+
 ## Install
 
 ```bash
@@ -26,8 +31,9 @@ Compatibility binaries are still shipped for migration:
 # 1) Install CLI
 npm install -g @cubis/foundry
 
-# 2) Set Postman key once (recommended: env mode)
+# 2) Set API keys once (recommended: env mode)
 export POSTMAN_API_KEY="<your-postman-api-key>"
+export STITCH_API_KEY="<your-stitch-api-key>" # Antigravity StitchMCP only
 
 # 3) Install workflow bundle for your platform
 cbx workflows install --platform codex --bundle agent-environment-setup --postman --yes
@@ -54,7 +60,10 @@ cbx workflows install --platform antigravity --terminal-integration --terminal-v
 cbx workflows install --platform codex --postman
 cbx workflows install --platform codex --postman --postman-workspace-id null
 cbx workflows install --platform codex --postman --postman-api-key "<key>"
+cbx workflows install --platform codex --postman --mcp-scope global
+cbx workflows install --platform copilot --postman --mcp-scope project
 cbx workflows install --platform antigravity --postman
+cbx workflows install --platform antigravity --postman --stitch-api-key "<key>"
 cbx workflows install --platform copilot --postman
 ```
 
@@ -63,15 +72,38 @@ Install bootstrap behavior:
 - When install scope is `global` (default), skills/powers install to global paths, while workflows + agents stay in workspace (`project`) paths.
 - Rule sync + engineering artifacts (`AGENTS.md`/`GEMINI.md`/Copilot instructions, `ENGINEERING_RULES.md`, `TECH.md`) are maintained in workspace (`project`) scope.
 - Codex workflow templates are maintained in workspace `.agents/workflows` so workflow-wrapper routing remains discoverable in project rules.
-- Optional `--postman` bootstrap creates `postman_setting.json` and installs/configures the Postman skill/MCP for Codex, Antigravity, and Copilot.
+- Optional `--postman` bootstrap creates `cbx_config.json`, stores managed MCP definitions in `.cbx/mcp/`, and installs/configures Postman MCP for Codex, Antigravity, and Copilot.
+- For Antigravity only, `--postman` also installs a default `StitchMCP` entry (`stitch.googleapis.com/mcp`) using key from `--stitch-api-key` or `STITCH_API_KEY`.
+- Use `--mcp-scope <project|workspace|global|user>` to choose where MCP runtime config is installed (interactive installs prompt for this when not provided).
 - Use `cbx rules init --platform <platform> --overwrite` to force-regenerate both files.
 
-Postman setup behavior:
-- `postman_setting.json` is generated in project root (or `~/.cbx/postman_setting.json` with `--scope global`).
+Postman + Antigravity Stitch setup behavior:
+- `cbx_config.json` is generated in workspace root (project MCP scope) or `~/.cbx/cbx_config.json` (global MCP scope).
+- Managed MCP definition files are generated under `.cbx/mcp/<platform>/postman.json` (workspace scope) or `~/.cbx/mcp/<platform>/postman.json` (global scope).
 - Env-first auth is supported: when `POSTMAN_API_KEY` is set, generated settings keep `apiKey: null` and MCP config uses `Bearer ${POSTMAN_API_KEY}`.
 - Inline auth is supported with `--postman-api-key <key>`.
 - `--postman-workspace-id null` writes JSON `null` for `defaultWorkspaceId`.
-- In project scope, `postman_setting.json` is auto-added to `.gitignore` (no duplicate entries).
+- Antigravity gets an additional managed file at `.cbx/mcp/antigravity/stitch.json` (or `~/.cbx/mcp/antigravity/stitch.json` in global MCP scope).
+- Stitch key source priority for Antigravity: `--stitch-api-key` then `STITCH_API_KEY`; when unset, generated config keeps placeholder `X-Goog-Api-Key: ur stitch key`.
+- In project MCP scope, `cbx_config.json` and `.cbx/mcp/` are auto-added to `.gitignore` (no duplicate entries).
+
+Platform runtime MCP placement:
+- Codex:
+  - Global MCP scope: `~/.codex/config.toml` via `codex mcp add`.
+  - Workspace MCP scope: `.vscode/mcp.json`.
+- Antigravity (Gemini CLI):
+  - Global MCP scope: `~/.gemini/settings.json` (`mcpServers`, includes `postman` + default `StitchMCP`).
+  - Workspace MCP scope: `.gemini/settings.json` (`mcpServers`, includes `postman` + default `StitchMCP`).
+- Copilot:
+  - Workspace MCP scope: `.vscode/mcp.json`.
+  - Global MCP scope: `~/.copilot/mcp-config.json`.
+
+API key docs:
+- Google Stitch MCP setup docs: [stitch.withgoogle.com/docs/mcp/setup](https://stitch.withgoogle.com/docs/mcp/setup)
+- Google Stitch settings (create API key): [stitch.withgoogle.com/settings](https://stitch.withgoogle.com/settings)
+- Google Cloud API key guidance: [Authenticate to Google and Google Cloud MCP servers](https://docs.cloud.google.com/mcp/authenticate-mcp)
+- Postman API key creation: [Generate and use Postman API keys](https://learning.postman.com/docs/developer/postman-api/authentication/)
+- Postman MCP setup: [Set up the Postman MCP Server](https://learning.postman.com/docs/developer/postman-api/postman-mcp-server/set-up-postman-mcp-server)
 
 `rules` manages strict engineering policy and a generated codebase tech map:
 

package/bin/cubis.js

@@ -13,13 +13,16 @@ import {
   writeFile
 } from "node:fs/promises";
 import { createRequire } from "node:module";
+import { execFile as execFileCallback } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 const { version: CLI_VERSION } = require("../package.json");
+const execFile = promisify(execFileCallback);
 
 const MANAGED_BLOCK_START_RE = /<!--\s*cbx:workflows:auto:start[^>]*-->/g;
 const MANAGED_BLOCK_END_RE = /<!--\s*cbx:workflows:auto:end\s*-->/g;
@@ -125,9 +128,16 @@ const DEFAULT_TERMINAL_VERIFIER = "codex";
 const POSTMAN_API_KEY_ENV_VAR = "POSTMAN_API_KEY";
 const POSTMAN_MCP_URL = "https://mcp.postman.com/minimal";
 const POSTMAN_SKILL_ID = "postman";
+const STITCH_MCP_SERVER_ID = "StitchMCP";
+const STITCH_API_KEY_ENV_VAR = "STITCH_API_KEY";
+const STITCH_MCP_URL = "https://stitch.googleapis.com/mcp";
+const STITCH_API_KEY_PLACEHOLDER = "ur stitch key";
+const CBX_CONFIG_FILENAME = "cbx_config.json";
 const POSTMAN_SETTINGS_FILENAME = "postman_setting.json";
 const POSTMAN_API_KEY_MISSING_WARNING =
-  `Postman API key is not configured. Set ${POSTMAN_API_KEY_ENV_VAR} or update ${POSTMAN_SETTINGS_FILENAME}.`;
+  `Postman API key is not configured. Set ${POSTMAN_API_KEY_ENV_VAR} or update ${CBX_CONFIG_FILENAME}.`;
+const STITCH_API_KEY_MISSING_WARNING =
+  `Google Stitch API key is not configured. Set ${STITCH_API_KEY_ENV_VAR} or update ${CBX_CONFIG_FILENAME}.`;
 const TECH_SCAN_MAX_FILES = 5000;
 const TECH_SCAN_IGNORED_DIRS = new Set([
   ".git",
@@ -279,6 +289,14 @@ function normalizeScope(value) {
   throw new Error(`Unknown scope '${value}'. Use --scope project or --scope global.`);
 }
 
+function normalizeMcpScope(value, fallback = "project") {
+  if (!value) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "project" || normalized === "workspace") return "project";
+  if (normalized === "global" || normalized === "user") return "global";
+  throw new Error(`Unknown MCP scope '${value}'. Use project/workspace or global/user.`);
+}
+
 function normalizeTerminalVerifier(value) {
   if (!value) return null;
   const normalized = value.trim().toLowerCase();
@@ -2254,7 +2272,7 @@ async function writeGeneratedArtifact({ destination, content, dryRun = false })
   return { action: exists ? "replaced" : "installed", path: destination };
 }
 
-function resolvePostmanSettingsPath({ scope, cwd = process.cwd() }) {
+function resolveLegacyPostmanSettingsPath({ scope, cwd = process.cwd() }) {
   if (scope === "global") {
     return path.join(os.homedir(), ".cbx", POSTMAN_SETTINGS_FILENAME);
   }
@@ -2262,20 +2280,116 @@ function resolvePostmanSettingsPath({ scope, cwd = process.cwd() }) {
   return path.join(workspaceRoot, POSTMAN_SETTINGS_FILENAME);
 }
 
-function buildPostmanMcpConfig({ apiKey = null, mcpUrl = POSTMAN_MCP_URL }) {
-  const authHeader = apiKey
-    ? `Bearer ${apiKey}`
-    : `Bearer \${${POSTMAN_API_KEY_ENV_VAR}}`;
+function resolveCbxConfigPath({ scope, cwd = process.cwd() }) {
+  if (scope === "global") {
+    return path.join(os.homedir(), ".cbx", CBX_CONFIG_FILENAME);
+  }
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  return path.join(workspaceRoot, CBX_CONFIG_FILENAME);
+}
+
+function resolveMcpRootPath({ scope, cwd = process.cwd() }) {
+  if (scope === "global") {
+    return path.join(os.homedir(), ".cbx", "mcp");
+  }
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  return path.join(workspaceRoot, ".cbx", "mcp");
+}
+
+function resolvePostmanMcpDefinitionPath({ platform, scope, cwd = process.cwd() }) {
+  return path.join(resolveMcpRootPath({ scope, cwd }), platform, `${POSTMAN_SKILL_ID}.json`);
+}
+
+function resolveStitchMcpDefinitionPath({ scope, cwd = process.cwd() }) {
+  return path.join(resolveMcpRootPath({ scope, cwd }), "antigravity", "stitch.json");
+}
+
+function buildPostmanAuthHeader({ apiKey = null, apiKeyEnvVar = POSTMAN_API_KEY_ENV_VAR }) {
+  return apiKey ? `Bearer ${apiKey}` : `Bearer \${${apiKeyEnvVar}}`;
+}
+
+function buildStitchApiHeader({ apiKey = null }) {
+  return `X-Goog-Api-Key: ${apiKey || STITCH_API_KEY_PLACEHOLDER}`;
+}
+
+function buildPostmanMcpDefinition({
+  apiKey = null,
+  apiKeyEnvVar = POSTMAN_API_KEY_ENV_VAR,
+  mcpUrl = POSTMAN_MCP_URL
+}) {
   return {
-    mcpServers: {
-      postman: {
-        url: mcpUrl,
-        headers: {
-          Authorization: authHeader
-        }
-      }
-    },
-    disabled: false
+    schemaVersion: 1,
+    server: POSTMAN_SKILL_ID,
+    transport: "http",
+    url: mcpUrl,
+    headers: {
+      Authorization: buildPostmanAuthHeader({ apiKey, apiKeyEnvVar })
+    }
+  };
+}
+
+function buildStitchMcpDefinition({
+  apiKey = null,
+  mcpUrl = STITCH_MCP_URL
+}) {
+  return {
+    schemaVersion: 1,
+    server: STITCH_MCP_SERVER_ID,
+    transport: "command",
+    command: "npx",
+    args: [
+      "-y",
+      "mcp-remote",
+      mcpUrl,
+      "--header",
+      buildStitchApiHeader({ apiKey })
+    ],
+    env: {}
+  };
+}
+
+function buildVsCodePostmanServer({
+  apiKey = null,
+  apiKeyEnvVar = POSTMAN_API_KEY_ENV_VAR,
+  mcpUrl = POSTMAN_MCP_URL
+}) {
+  return {
+    type: "sse",
+    url: mcpUrl,
+    headers: {
+      Authorization: buildPostmanAuthHeader({ apiKey, apiKeyEnvVar })
+    }
+  };
+}
+
+function buildGeminiPostmanServer({
+  apiKey = null,
+  apiKeyEnvVar = POSTMAN_API_KEY_ENV_VAR,
+  mcpUrl = POSTMAN_MCP_URL
+}) {
+  return {
+    httpUrl: mcpUrl,
+    headers: {
+      Authorization: buildPostmanAuthHeader({ apiKey, apiKeyEnvVar })
+    }
+  };
+}
+
+function buildGeminiStitchServer({
+  apiKey = null,
+  mcpUrl = STITCH_MCP_URL
+}) {
+  return {
+    $typeName: "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
+    command: "npx",
+    args: [
+      "-y",
+      "mcp-remote",
+      mcpUrl,
+      "--header",
+      buildStitchApiHeader({ apiKey })
+    ],
+    env: {}
   };
 }
 
@@ -2285,12 +2399,297 @@ function getPostmanApiKeySource({ apiKey, envApiKey }) {
   return "unset";
 }
 
+function getStitchApiKeySource({ apiKey, envApiKey }) {
+  if (apiKey) return "inline";
+  if (envApiKey) return "env";
+  return "unset";
+}
+
 function normalizePostmanApiKey(value) {
   if (value === undefined || value === null) return null;
   const normalized = String(value).trim();
   return normalized || null;
 }
 
+function parseStoredPostmanConfig(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const source = raw.postman && typeof raw.postman === "object" ? raw.postman : raw;
+
+  const apiKey = normalizePostmanApiKey(source.apiKey);
+  const apiKeyEnvVar = String(source.apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR).trim() || POSTMAN_API_KEY_ENV_VAR;
+  const mcpUrl = String(source.mcpUrl || POSTMAN_MCP_URL).trim() || POSTMAN_MCP_URL;
+  const defaultWorkspaceId = normalizePostmanWorkspaceId(source.defaultWorkspaceId);
+
+  return {
+    apiKey,
+    apiKeyEnvVar,
+    mcpUrl,
+    defaultWorkspaceId
+  };
+}
+
+function parseStoredStitchConfig(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const source = raw.stitch && typeof raw.stitch === "object" ? raw.stitch : null;
+  if (!source) return null;
+
+  const apiKey = normalizePostmanApiKey(source.apiKey);
+  const apiKeyEnvVar = String(source.apiKeyEnvVar || STITCH_API_KEY_ENV_VAR).trim() || STITCH_API_KEY_ENV_VAR;
+  const mcpUrl = String(source.mcpUrl || STITCH_MCP_URL).trim() || STITCH_MCP_URL;
+
+  return {
+    apiKey,
+    apiKeyEnvVar,
+    mcpUrl
+  };
+}
+
+async function readJsonFileIfExists(filePath) {
+  if (!(await pathExists(filePath))) return { exists: false, value: null };
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return { exists: true, value: JSON.parse(raw) };
+  } catch (error) {
+    return { exists: true, value: null, error };
+  }
+}
+
+async function upsertJsonObjectFile({ targetPath, updater, dryRun = false }) {
+  const exists = await pathExists(targetPath);
+  const warnings = [];
+  let parsed = {};
+
+  if (exists) {
+    try {
+      const raw = await readFile(targetPath, "utf8");
+      const decoded = JSON.parse(raw);
+      if (decoded && typeof decoded === "object" && !Array.isArray(decoded)) {
+        parsed = decoded;
+      } else {
+        warnings.push(`Existing JSON at ${targetPath} was not an object. Resetting structure.`);
+      }
+    } catch {
+      warnings.push(`Existing JSON at ${targetPath} could not be parsed. Resetting structure.`);
+    }
+  }
+
+  const nextValue = updater(parsed);
+  const content = `${JSON.stringify(nextValue, null, 2)}\n`;
+  const writeResult = await writeGeneratedArtifact({
+    destination: targetPath,
+    content,
+    dryRun
+  });
+
+  return {
+    action: writeResult.action,
+    filePath: targetPath,
+    warnings
+  };
+}
+
+async function removeGeneratedArtifactIfExists({ targetPath, dryRun = false }) {
+  const exists = await pathExists(targetPath);
+  if (!exists) {
+    return {
+      action: "missing",
+      path: targetPath
+    };
+  }
+
+  if (!dryRun) {
+    await rm(targetPath, { recursive: true, force: true });
+  }
+
+  return {
+    action: dryRun ? "would-remove" : "removed",
+    path: targetPath
+  };
+}
+
+async function applyPostmanMcpForPlatform({
+  platform,
+  mcpScope,
+  apiKey,
+  apiKeyEnvVar,
+  mcpUrl,
+  stitchApiKey,
+  stitchMcpUrl,
+  includeStitchMcp = false,
+  dryRun = false,
+  cwd = process.cwd()
+}) {
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  const warnings = [];
+
+  if (platform === "antigravity") {
+    const settingsPath =
+      mcpScope === "global"
+        ? path.join(os.homedir(), ".gemini", "settings.json")
+        : path.join(workspaceRoot, ".gemini", "settings.json");
+    const result = await upsertJsonObjectFile({
+      targetPath: settingsPath,
+      updater: (existing) => {
+        const next = { ...existing };
+        const mcpServers =
+          next.mcpServers && typeof next.mcpServers === "object" && !Array.isArray(next.mcpServers)
+            ? { ...next.mcpServers }
+            : {};
+        mcpServers[POSTMAN_SKILL_ID] = buildGeminiPostmanServer({
+          apiKey,
+          apiKeyEnvVar,
+          mcpUrl
+        });
+        if (includeStitchMcp) {
+          mcpServers[STITCH_MCP_SERVER_ID] = buildGeminiStitchServer({
+            apiKey: stitchApiKey,
+            mcpUrl: stitchMcpUrl
+          });
+        }
+        next.mcpServers = mcpServers;
+        return next;
+      },
+      dryRun
+    });
+    return {
+      kind: "gemini-settings",
+      scope: mcpScope,
+      path: settingsPath,
+      action: result.action,
+      warnings: [...warnings, ...result.warnings]
+    };
+  }
+
+  if (platform === "copilot") {
+    const configPath =
+      mcpScope === "global"
+        ? path.join(os.homedir(), ".copilot", "mcp-config.json")
+        : path.join(workspaceRoot, ".vscode", "mcp.json");
+    const result = await upsertJsonObjectFile({
+      targetPath: configPath,
+      updater: (existing) => {
+        const next = { ...existing };
+        const servers =
+          next.servers && typeof next.servers === "object" && !Array.isArray(next.servers)
+            ? { ...next.servers }
+            : {};
+        servers[POSTMAN_SKILL_ID] = buildVsCodePostmanServer({
+          apiKey,
+          apiKeyEnvVar,
+          mcpUrl
+        });
+        next.servers = servers;
+        return next;
+      },
+      dryRun
+    });
+    return {
+      kind: mcpScope === "global" ? "copilot-cli-mcp" : "vscode-mcp",
+      scope: mcpScope,
+      path: configPath,
+      action: result.action,
+      warnings: [...warnings, ...result.warnings]
+    };
+  }
+
+  if (platform === "codex") {
+    if (mcpScope === "project") {
+      const vscodePath = path.join(workspaceRoot, ".vscode", "mcp.json");
+      const result = await upsertJsonObjectFile({
+        targetPath: vscodePath,
+        updater: (existing) => {
+          const next = { ...existing };
+          const servers =
+            next.servers && typeof next.servers === "object" && !Array.isArray(next.servers)
+              ? { ...next.servers }
+              : {};
+          servers[POSTMAN_SKILL_ID] = buildVsCodePostmanServer({
+            apiKey,
+            apiKeyEnvVar,
+            mcpUrl
+          });
+          next.servers = servers;
+          return next;
+        },
+        dryRun
+      });
+      return {
+        kind: "vscode-mcp",
+        scope: mcpScope,
+        path: vscodePath,
+        action: result.action,
+        warnings: [...warnings, ...result.warnings]
+      };
+    }
+
+    const codexConfigPath = path.join(os.homedir(), ".codex", "config.toml");
+    if (dryRun) {
+      return {
+        kind: "codex-cli",
+        scope: mcpScope,
+        path: codexConfigPath,
+        action: "would-patch",
+        warnings
+      };
+    }
+
+    try {
+      await execFile("codex", ["mcp", "remove", POSTMAN_SKILL_ID], { cwd });
+    } catch {
+      // Best effort. Add will still run and becomes source of truth.
+    }
+
+    try {
+      await execFile(
+        "codex",
+        [
+          "mcp",
+          "add",
+          POSTMAN_SKILL_ID,
+          "--url",
+          mcpUrl,
+          "--bearer-token-env-var",
+          apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR
+        ],
+        { cwd }
+      );
+    } catch (error) {
+      warnings.push(
+        `Failed to register Postman MCP via Codex CLI. Ensure 'codex' is installed and rerun. (${error.message})`
+      );
+      return {
+        kind: "codex-cli",
+        scope: mcpScope,
+        path: codexConfigPath,
+        action: "failed",
+        warnings
+      };
+    }
+
+    if (apiKey) {
+      warnings.push(
+        "Codex global MCP uses bearer token env vars. Inline apiKey in cbx_config.json is not directly used by Codex."
+      );
+    }
+
+    return {
+      kind: "codex-cli",
+      scope: mcpScope,
+      path: codexConfigPath,
+      action: "patched",
+      warnings
+    };
+  }
+
+  return {
+    kind: "unknown",
+    scope: mcpScope,
+    path: null,
+    action: "skipped",
+    warnings: [`Unsupported platform '${platform}' for Postman MCP installation.`]
+  };
+}
+
 async function ensureGitIgnoreEntry({
   filePath,
   entry,
@@ -2323,13 +2722,15 @@ async function ensureGitIgnoreEntry({
 }
 
 async function resolvePostmanInstallSelection({
+  platform,
   scope,
   options,
   cwd = process.cwd()
 }) {
   const hasApiKeyOption = options.postmanApiKey !== undefined;
   const hasWorkspaceOption = options.postmanWorkspaceId !== undefined;
-  const enabled = Boolean(options.postman) || hasApiKeyOption || hasWorkspaceOption;
+  const hasStitchApiKeyOption = options.stitchApiKey !== undefined;
+  const enabled = Boolean(options.postman) || hasApiKeyOption || hasWorkspaceOption || hasStitchApiKeyOption;
   if (!enabled) return { enabled: false };
 
   const explicitApiKey = hasApiKeyOption ? String(options.postmanApiKey || "").trim() : "";
@@ -2338,7 +2739,14 @@ async function resolvePostmanInstallSelection({
   let defaultWorkspaceId = hasWorkspaceOption
     ? normalizePostmanWorkspaceId(options.postmanWorkspaceId)
     : null;
+  const requestedMcpScope = options.mcpScope
+    ? normalizeMcpScope(options.mcpScope, normalizeMcpScope(scope, "project"))
+    : null;
+  let mcpScope = requestedMcpScope || normalizeMcpScope(scope, "project");
   const warnings = [];
+  const stitchEnabled = platform === "antigravity";
+  let stitchApiKey = hasStitchApiKeyOption ? normalizePostmanApiKey(options.stitchApiKey) : null;
+  const envStitchApiKey = normalizePostmanApiKey(process.env[STITCH_API_KEY_ENV_VAR]);
 
   const canPrompt = !options.yes && process.stdin.isTTY;
   if (canPrompt && !hasApiKeyOption && !apiKey && !envApiKey) {
@@ -2361,34 +2769,91 @@ async function resolvePostmanInstallSelection({
     defaultWorkspaceId = normalizePostmanWorkspaceId(promptedWorkspaceId);
   }
 
+  if (canPrompt && stitchEnabled && !hasStitchApiKeyOption && !stitchApiKey && !envStitchApiKey) {
+    const promptedStitchApiKey = String(
+      await input({
+        message: `Google Stitch API key (optional, leave blank to keep ${STITCH_API_KEY_ENV_VAR} env mode):`,
+        default: ""
+      })
+    ).trim();
+    if (promptedStitchApiKey) {
+      stitchApiKey = promptedStitchApiKey;
+    }
+  }
+
+  if (canPrompt && !requestedMcpScope) {
+    mcpScope = await select({
+      message: "Install MCP config in workspace or global scope?",
+      choices: [
+        { name: scope === "global" ? "Global (recommended)" : "Global", value: "global" },
+        { name: scope === "project" ? "Workspace (recommended)" : "Workspace", value: "project" }
+      ],
+      default: mcpScope
+    });
+  }
+
   const apiKeySource = getPostmanApiKeySource({ apiKey, envApiKey });
   if (apiKeySource === "unset") {
     warnings.push(POSTMAN_API_KEY_MISSING_WARNING);
   }
 
-  const settingsPath = resolvePostmanSettingsPath({ scope, cwd });
-  const settings = {
-    apiKey: apiKey || null,
-    apiKeyEnvVar: POSTMAN_API_KEY_ENV_VAR,
-    apiKeySource,
-    defaultWorkspaceId: defaultWorkspaceId ?? null,
-    mcpUrl: POSTMAN_MCP_URL,
+  const stitchApiKeySource = stitchEnabled
+    ? getStitchApiKeySource({ apiKey: stitchApiKey, envApiKey: envStitchApiKey })
+    : null;
+  if (stitchEnabled && stitchApiKeySource === "unset") {
+    warnings.push(STITCH_API_KEY_MISSING_WARNING);
+  }
+  if (!stitchEnabled && hasStitchApiKeyOption) {
+    warnings.push("--stitch-api-key is only used for --platform antigravity.");
+  }
+
+  const cbxConfigPath = resolveCbxConfigPath({ scope: mcpScope, cwd });
+  const legacySettingsPath = resolveLegacyPostmanSettingsPath({ scope: mcpScope, cwd });
+  const cbxConfig = {
+    schemaVersion: 1,
     generatedBy: "cbx workflows install --postman",
-    generatedAt: new Date().toISOString()
+    generatedAt: new Date().toISOString(),
+    mcp: {
+      scope: mcpScope,
+      server: POSTMAN_SKILL_ID,
+      platform
+    },
+    postman: {
+      apiKey: apiKey || null,
+      apiKeyEnvVar: POSTMAN_API_KEY_ENV_VAR,
+      apiKeySource,
+      defaultWorkspaceId: defaultWorkspaceId ?? null,
+      mcpUrl: POSTMAN_MCP_URL
+    }
   };
+  if (stitchEnabled) {
+    cbxConfig.stitch = {
+      server: STITCH_MCP_SERVER_ID,
+      apiKey: stitchApiKey || null,
+      apiKeyEnvVar: STITCH_API_KEY_ENV_VAR,
+      apiKeySource: stitchApiKeySource,
+      mcpUrl: STITCH_MCP_URL
+    };
+  }
 
   return {
     enabled: true,
     apiKey,
     apiKeySource,
+    stitchEnabled,
+    stitchApiKey,
+    stitchApiKeySource,
     defaultWorkspaceId: defaultWorkspaceId ?? null,
+    mcpScope,
     warnings,
-    settings,
-    settingsPath
+    cbxConfig,
+    cbxConfigPath,
+    legacySettingsPath
   };
 }
 
 async function configurePostmanInstallArtifacts({
+  platform,
   scope,
   profilePaths,
   postmanSelection,
@@ -2398,34 +2863,55 @@ async function configurePostmanInstallArtifacts({
 }) {
   if (!postmanSelection?.enabled) return null;
 
-  let warnings = postmanSelection.warnings.filter((warning) => warning !== POSTMAN_API_KEY_MISSING_WARNING);
-  const settingsContent = `${JSON.stringify(postmanSelection.settings, null, 2)}\n`;
-  const settingsResult = await writeTextFile({
-    targetPath: postmanSelection.settingsPath,
-    content: settingsContent,
+  let warnings = postmanSelection.warnings.filter(
+    (warning) => warning !== POSTMAN_API_KEY_MISSING_WARNING && warning !== STITCH_API_KEY_MISSING_WARNING
+  );
+  const cbxConfigContent = `${JSON.stringify(postmanSelection.cbxConfig, null, 2)}\n`;
+  const cbxConfigResult = await writeTextFile({
+    targetPath: postmanSelection.cbxConfigPath,
+    content: cbxConfigContent,
     overwrite,
     dryRun
   });
 
-  let effectiveApiKey = normalizePostmanApiKey(postmanSelection.settings.apiKey);
+  let effectiveApiKey = normalizePostmanApiKey(postmanSelection.cbxConfig?.postman?.apiKey);
+  let effectiveApiKeyEnvVar = String(
+    postmanSelection.cbxConfig?.postman?.apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR
+  ).trim();
   let effectiveDefaultWorkspaceId = postmanSelection.defaultWorkspaceId ?? null;
-  let effectiveMcpUrl = postmanSelection.settings.mcpUrl || POSTMAN_MCP_URL;
-
-  if (settingsResult.action === "skipped" || settingsResult.action === "would-skip") {
-    try {
-      const existingSettingsRaw = await readFile(postmanSelection.settingsPath, "utf8");
-      const existingSettings = JSON.parse(existingSettingsRaw);
-      effectiveApiKey = normalizePostmanApiKey(existingSettings?.apiKey);
-      effectiveDefaultWorkspaceId = normalizePostmanWorkspaceId(existingSettings?.defaultWorkspaceId);
-      const existingMcpUrl = String(existingSettings?.mcpUrl || "").trim();
-      if (existingMcpUrl) {
-        effectiveMcpUrl = existingMcpUrl;
-      }
-    } catch {
+  let effectiveMcpUrl = postmanSelection.cbxConfig?.postman?.mcpUrl || POSTMAN_MCP_URL;
+  const shouldInstallStitch = Boolean(postmanSelection.stitchEnabled);
+  let effectiveStitchApiKey = shouldInstallStitch
+    ? normalizePostmanApiKey(postmanSelection.cbxConfig?.stitch?.apiKey)
+    : null;
+  let effectiveStitchMcpUrl = shouldInstallStitch
+    ? postmanSelection.cbxConfig?.stitch?.mcpUrl || STITCH_MCP_URL
+    : STITCH_MCP_URL;
+
+  if (cbxConfigResult.action === "skipped" || cbxConfigResult.action === "would-skip") {
+    const existingCbxConfig = await readJsonFileIfExists(postmanSelection.cbxConfigPath);
+    const existingLegacySettings = await readJsonFileIfExists(postmanSelection.legacySettingsPath);
+    const storedPostmanConfig =
+      parseStoredPostmanConfig(existingCbxConfig.value) || parseStoredPostmanConfig(existingLegacySettings.value);
+    const storedStitchConfig =
+      shouldInstallStitch &&
+      (parseStoredStitchConfig(existingCbxConfig.value) || parseStoredStitchConfig(existingLegacySettings.value));
+
+    if (storedPostmanConfig) {
+      effectiveApiKey = storedPostmanConfig.apiKey;
+      effectiveApiKeyEnvVar = storedPostmanConfig.apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR;
+      effectiveDefaultWorkspaceId = storedPostmanConfig.defaultWorkspaceId;
+      effectiveMcpUrl = storedPostmanConfig.mcpUrl || POSTMAN_MCP_URL;
+    } else {
       warnings.push(
-        `Existing ${POSTMAN_SETTINGS_FILENAME} could not be parsed. Using install-time Postman values for MCP config.`
+        `Existing ${CBX_CONFIG_FILENAME} (or legacy ${POSTMAN_SETTINGS_FILENAME}) could not be parsed. Using install-time Postman values for MCP config.`
       );
     }
+
+    if (storedStitchConfig) {
+      effectiveStitchApiKey = storedStitchConfig.apiKey;
+      effectiveStitchMcpUrl = storedStitchConfig.mcpUrl || STITCH_MCP_URL;
+    }
   }
 
   const envApiKey = normalizePostmanApiKey(process.env[POSTMAN_API_KEY_ENV_VAR]);
@@ -2436,52 +2922,112 @@ async function configurePostmanInstallArtifacts({
   if (effectiveApiKeySource === "unset") {
     warnings.push(POSTMAN_API_KEY_MISSING_WARNING);
   }
+  const envStitchApiKey = normalizePostmanApiKey(process.env[STITCH_API_KEY_ENV_VAR]);
+  const effectiveStitchApiKeySource = shouldInstallStitch
+    ? getStitchApiKeySource({
+        apiKey: effectiveStitchApiKey,
+        envApiKey: envStitchApiKey
+      })
+    : null;
+  if (shouldInstallStitch && effectiveStitchApiKeySource === "unset") {
+    warnings.push(STITCH_API_KEY_MISSING_WARNING);
+  }
 
-  let gitIgnoreResult = null;
-  if (scope === "project") {
+  const gitIgnoreResults = [];
+  if (postmanSelection.mcpScope === "project") {
     const workspaceRoot = findWorkspaceRoot(cwd);
     const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
-    gitIgnoreResult = await ensureGitIgnoreEntry({
+    const configIgnore = await ensureGitIgnoreEntry({
       filePath: gitIgnorePath,
-      entry: POSTMAN_SETTINGS_FILENAME,
+      entry: CBX_CONFIG_FILENAME,
       dryRun
     });
+    gitIgnoreResults.push(configIgnore);
+
+    const mcpIgnore = await ensureGitIgnoreEntry({
+      filePath: gitIgnorePath,
+      entry: ".cbx/mcp/",
+      dryRun
+    });
+    gitIgnoreResults.push(mcpIgnore);
   }
 
-  const postmanSkillDir = path.join(profilePaths.skillsDir, POSTMAN_SKILL_ID);
-  const postmanMcpPath = path.join(postmanSkillDir, "mcp.json");
-  let mcpResult = null;
-  const postmanSkillExists = await pathExists(postmanSkillDir);
-  if (!dryRun && !postmanSkillExists) {
-    mcpResult = {
-      action: "missing-postman-skill",
-      path: postmanMcpPath
-    };
-  } else {
-    const mcpConfigContent = `${JSON.stringify(
-      buildPostmanMcpConfig({
-        apiKey: effectiveApiKey,
-        mcpUrl: effectiveMcpUrl
+  const mcpDefinitionPath = resolvePostmanMcpDefinitionPath({
+    platform,
+    scope: postmanSelection.mcpScope,
+    cwd
+  });
+  const mcpDefinitionContent = `${JSON.stringify(
+    buildPostmanMcpDefinition({
+      apiKey: effectiveApiKey,
+      apiKeyEnvVar: effectiveApiKeyEnvVar,
+      mcpUrl: effectiveMcpUrl
+    }),
+    null,
+    2
+  )}\n`;
+  const mcpDefinitionResult = await writeGeneratedArtifact({
+    destination: mcpDefinitionPath,
+    content: mcpDefinitionContent,
+    dryRun
+  });
+  let stitchMcpDefinitionPath = null;
+  let stitchMcpDefinitionResult = null;
+  if (shouldInstallStitch) {
+    stitchMcpDefinitionPath = resolveStitchMcpDefinitionPath({
+      scope: postmanSelection.mcpScope,
+      cwd
+    });
+    const stitchMcpDefinitionContent = `${JSON.stringify(
+      buildStitchMcpDefinition({
+        apiKey: effectiveStitchApiKey,
+        mcpUrl: effectiveStitchMcpUrl
       }),
       null,
       2
     )}\n`;
-    mcpResult = await writeGeneratedArtifact({
-      destination: postmanMcpPath,
-      content: mcpConfigContent,
+    stitchMcpDefinitionResult = await writeGeneratedArtifact({
+      destination: stitchMcpDefinitionPath,
+      content: stitchMcpDefinitionContent,
       dryRun
     });
   }
 
+  const mcpRuntimeResult = await applyPostmanMcpForPlatform({
+    platform,
+    mcpScope: postmanSelection.mcpScope,
+    apiKey: effectiveApiKey,
+    apiKeyEnvVar: effectiveApiKeyEnvVar,
+    mcpUrl: effectiveMcpUrl,
+    stitchApiKey: effectiveStitchApiKey,
+    stitchMcpUrl: effectiveStitchMcpUrl,
+    includeStitchMcp: shouldInstallStitch,
+    dryRun,
+    cwd
+  });
+  warnings.push(...(mcpRuntimeResult.warnings || []));
+
+  const legacySkillMcpCleanup = await removeGeneratedArtifactIfExists({
+    targetPath: path.join(profilePaths.skillsDir, POSTMAN_SKILL_ID, "mcp.json"),
+    dryRun
+  });
+
   return {
     enabled: true,
+    mcpScope: postmanSelection.mcpScope,
     apiKeySource: effectiveApiKeySource,
+    stitchApiKeySource: effectiveStitchApiKeySource,
     defaultWorkspaceId: effectiveDefaultWorkspaceId,
     warnings,
-    settingsPath: postmanSelection.settingsPath,
-    settingsResult,
-    gitIgnoreResult,
-    mcpResult
+    cbxConfigPath: postmanSelection.cbxConfigPath,
+    cbxConfigResult,
+    gitIgnoreResults,
+    mcpDefinitionPath,
+    mcpDefinitionResult,
+    stitchMcpDefinitionPath,
+    stitchMcpDefinitionResult,
+    mcpRuntimeResult,
+    legacySkillMcpCleanup
   };
 }
 
@@ -3051,18 +3597,35 @@ function printPostmanSetupSummary({ postmanSetup }) {
   if (!postmanSetup?.enabled) return;
 
   console.log("\nPostman setup:");
-  console.log(`- Settings file: ${postmanSetup.settingsResult.action} (${postmanSetup.settingsPath})`);
-  console.log(`- API key source: ${postmanSetup.apiKeySource}`);
+  console.log(`- MCP scope: ${postmanSetup.mcpScope}`);
+  console.log(`- Config file: ${postmanSetup.cbxConfigResult.action} (${postmanSetup.cbxConfigPath})`);
+  console.log(`- Postman API key source: ${postmanSetup.apiKeySource}`);
+  if (postmanSetup.stitchApiKeySource) {
+    console.log(`- Stitch API key source: ${postmanSetup.stitchApiKeySource}`);
+  }
   console.log(
     `- Default workspace ID: ${postmanSetup.defaultWorkspaceId === null ? "null" : postmanSetup.defaultWorkspaceId}`
   );
-  if (postmanSetup.gitIgnoreResult) {
+  for (const ignoreResult of postmanSetup.gitIgnoreResults || []) {
+    console.log(`- .gitignore (${ignoreResult.filePath}): ${ignoreResult.action}`);
+  }
+  console.log(
+    `- Managed MCP definition (${postmanSetup.mcpDefinitionPath}): ${postmanSetup.mcpDefinitionResult.action}`
+  );
+  if (postmanSetup.stitchMcpDefinitionPath && postmanSetup.stitchMcpDefinitionResult) {
     console.log(
-      `- .gitignore (${postmanSetup.gitIgnoreResult.filePath}): ${postmanSetup.gitIgnoreResult.action}`
+      `- Managed Stitch MCP definition (${postmanSetup.stitchMcpDefinitionPath}): ${postmanSetup.stitchMcpDefinitionResult.action}`
     );
   }
-  if (postmanSetup.mcpResult) {
-    console.log(`- Postman MCP config (${postmanSetup.mcpResult.path}): ${postmanSetup.mcpResult.action}`);
+  if (postmanSetup.mcpRuntimeResult) {
+    console.log(
+      `- Platform MCP target (${postmanSetup.mcpRuntimeResult.path || "n/a"}): ${postmanSetup.mcpRuntimeResult.action}`
+    );
+  }
+  if (postmanSetup.legacySkillMcpCleanup) {
+    console.log(
+      `- Legacy skill mcp.json cleanup (${postmanSetup.legacySkillMcpCleanup.path}): ${postmanSetup.legacySkillMcpCleanup.action}`
+    );
   }
 
   if (postmanSetup.warnings.length > 0) {
@@ -3383,16 +3946,24 @@ function withInstallOptions(command) {
     .option("--overwrite", "overwrite existing files")
     .option(
       "--postman",
-      "optional: install Postman skill and generate postman_setting.json"
+      "optional: install Postman skill and generate cbx_config.json"
     )
     .option(
       "--postman-api-key <key>",
-      "optional: set Postman API key inline for generated postman_setting.json and installed Postman MCP config"
+      "optional: set Postman API key inline for generated cbx_config.json and installed Postman MCP config"
     )
     .option(
       "--postman-workspace-id <id|null>",
       "optional: set default Postman workspace ID (use 'null' for no default)"
     )
+    .option(
+      "--stitch-api-key <key>",
+      "optional: Antigravity only. Set Google Stitch API key inline for StitchMCP config"
+    )
+    .option(
+      "--mcp-scope <scope>",
+      "optional: MCP config scope for --postman (project|workspace|global|user)"
+    )
     .option(
       "--terminal-integration",
       "Antigravity only: enable terminal verification integration (prompts for verifier when interactive)"
@@ -3557,6 +4128,7 @@ async function runWorkflowInstall(options) {
       options
     });
     const postmanSelection = await resolvePostmanInstallSelection({
+      platform,
       scope,
       options,
       cwd
@@ -3615,6 +4187,7 @@ async function runWorkflowInstall(options) {
       cwd
     });
     const postmanSetupResult = await configurePostmanInstallArtifacts({
+      platform,
       scope,
       profilePaths: installResult.profilePaths,
       postmanSelection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
   "files": [
     "bin",
     "Ai Agent Workflow",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "start": "node bin/cubis.js",