@cubis/foundry 0.3.64 → 0.3.65

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project are documented in this file.
 
+## [Unreleased]
+
+### Changed
+
+- Clarified Postman MCP guidance across skills, workflows, README, and platform rule templates:
+  - direct `postman` MCP server is now the explicit execution path for collections, workspaces, environments, monitors, and runs
+  - Foundry `postman_*` tools are documented as config/status helpers only.
+- Added quota-safe Postman execution guidance:
+  - no automatic `runCollection` -> `runMonitor` fallback
+  - Postman CLI is the recommended secondary path after direct MCP execution fails
+  - monitor quota, API rate limits, and runtime timeouts are documented as separate failure classes.
+
 ## [0.3.62] - 2026-03-05
 
 ### Fixed

package/README.md

@@ -5,14 +5,16 @@ Workflow-first installer for multi-platform AI agent environments.
 Last updated: 2026-03-04.
 
 `cbx` installs workflows, skills, wrappers, and rule files for:
+
 - Codex
 - Antigravity (Gemini)
 - GitHub Copilot
+- Claude Code
 
-Official install targets: `codex`, `antigravity`, `copilot`.
-Mirror/parity artifacts are maintained for `cursor` and `windsurf`, but those are not direct install targets.
+Official install targets: `codex`, `antigravity`, `copilot`, `claude`.
 
 Skill install default is profile-based:
+
 - default profile: `core`
 - add `--skill-profile web-backend` for broader web/backend stack
 - add `--all-skills` for full workflow + MCP catalog install
@@ -37,11 +39,18 @@ Skill install default is profile-based:
 
 - Workflow files (`/plan`, `/create`, etc.)
 - Skill folders
-- Codex callable wrapper skills ($workflow-*, $agent-*)
+- Codex callable wrapper skills ($workflow-_, $agent-_)
 - Platform rule files (`AGENTS.md`, `GEMINI.md`, etc.)
 - Engineering artifacts in workspace (`ENGINEERING_RULES.md`, `TECH.md`)
 - Managed MCP config for Postman and Stitch
 
+Generated rule files are intentionally route-first and lazy about skill loading:
+
+- inspect locally first
+- route through native workflows or agents first
+- execute directly for simple tasks
+- load skills only when the user names one or the domain is still unclear
+
 ## Install
 
 ```bash
@@ -65,6 +74,7 @@ cbx init
 ```
 
 Wizard flow:
+
 - Welcome screen (Cubis Foundry banner + version)
 - Bundle selection
 - Multi-platform selection (`codex`, `antigravity`, `copilot`)
@@ -104,6 +114,7 @@ cbx init \
 Use `cbx init` when you want step-by-step guided setup.
 
 Detailed wizard behavior and platform matrix:
+
 - `docs/cli-init-wizard.md`
 
 ## Quickstarts
@@ -115,6 +126,7 @@ cbx workflows install --platform codex --scope global --bundle agent-environment
 ```
 
 Important:
+
 - Do not use `--yes` if you want interactive Postman workspace selection.
 - Interactive install can fetch your Postman workspaces and save the selected workspace as the active profile `workspaceId`.
 
@@ -137,6 +149,7 @@ cbx workflows install --platform copilot --scope global --bundle agent-environme
 Default install scope is `global`.
 
 Behavior:
+
 - Skills are installed in global platform skill directories.
 - Workflows and agents are installed in project paths for active workspace behavior.
 - Rule files remain workspace-oriented for current repo context.
@@ -145,18 +158,21 @@ Behavior:
 ### Where files go
 
 Codex:
+
 - Global skills: `~/.agents/skills`
 - Project workflows: `<workspace>/.agents/workflows`
 - Project rules: `<workspace>/AGENTS.md`
 - Global rules: `~/.codex/AGENTS.md`
 
 Antigravity:
+
 - Global skills: `~/.gemini/antigravity/skills`
 - Project workflows: `<workspace>/.agent/workflows`
 - Project rules: `<workspace>/.agent/rules/GEMINI.md`
 - Global rules: `~/.gemini/GEMINI.md`
 
 Copilot:
+
 - Global skills: `~/.copilot/skills`
 - Project workflows: `<workspace>/.github/copilot/workflows`
 - Project rules: `<workspace>/AGENTS.md` and `<workspace>/.github/copilot-instructions.md`
@@ -167,6 +183,7 @@ Copilot:
 `cbx_config.json` is the single supported credentials/config source.
 
 Paths:
+
 - Global: `~/.cbx/cbx_config.json`
 - Project: `<workspace>/cbx_config.json`
 
@@ -240,6 +257,7 @@ cbx workflows config keys persist-env --service all --scope global
 ```
 
 Alias commands are also available:
+
 - None. Use canonical `cbx workflows config keys ...` commands only.
 
 ## Postman and Stitch Setup Flows
@@ -253,14 +271,26 @@ cbx workflows install --platform codex --scope global --bundle agent-environment
 If active Postman env var (for example `POSTMAN_API_KEY_DEFAULT`) is available and `--yes` is not used, installer can show workspace chooser and save selected `workspaceId` in active Postman profile.
 
 `--postman` now installs side-by-side MCP topology by default:
+
 - direct Postman MCP server (`postman`)
 - direct Stitch MCP server where applicable (`StitchMCP` for Antigravity)
 - local Foundry MCP command server (`cubis-foundry` via `cbx mcp serve --transport stdio --scope global`)
 
-`--postman` also installs the `postman` skill. Managed platform rules then treat Postman intent as skill-first:
-- run `skill_search "postman"`
-- load `skill_get "postman"` before workflow/agent routing
-- prefer Postman MCP tools over Newman/CLI fallback unless explicitly requested
+`--postman` also installs the `postman` skill. Managed platform rules then treat Postman intent as route-first with optional skill priming:
+
+- validate or search for the `postman` skill only when Postman intent is explicit or the route still needs domain context
+- load `skill_get "postman"` before execution only when that context is actually needed
+- use direct `postman` server tools for actual Postman collection/workspace/environment/run actions
+- keep Foundry `postman_*` tools limited to mode/status/default-workspace config
+- never auto-fallback from `runCollection` to `runMonitor`
+- recommend Postman CLI as the default secondary path after direct MCP execution fails
+- use monitor execution only when the user explicitly asks for monitor-based cloud execution
+
+Quota-safe execution facts:
+
+- Postman API rate limits are separate from monitor usage limits
+- monitor usage is plan/billing usage and is consumed by request count, region count, and auth requests
+- monitor runtime caps are separate from monitor quota and do not imply quota is still available
 
 To opt out of Foundry MCP registration during install:
 
@@ -312,24 +342,28 @@ Default managed command template:
 ## MCP Placement Matrix
 
 Managed MCP definition files (`.cbx/mcp/...`):
+
 - Global scope: `~/.cbx/mcp/<platform>/postman.json`
 - Project scope: `<workspace>/.cbx/mcp/<platform>/postman.json`
 
 Runtime target patching:
 
 Codex:
+
 - Global MCP runtime target: `~/.codex/config.toml` (via `codex mcp add/remove`)
 - Project MCP runtime target: `<workspace>/.vscode/mcp.json`
 - Foundry side-by-side server id: `cubis-foundry` (command: `cbx mcp serve --transport stdio --scope <global|project>`)
   - Install now pins scope explicitly (`global` or `project`) in this command.
 
 Antigravity:
+
 - Global runtime target: `~/.gemini/settings.json` (`mcpServers`)
 - Project runtime target: `<workspace>/.gemini/settings.json` (`mcpServers`)
 - Foundry side-by-side server id: `cubis-foundry` (command template)
   - Install now pins scope explicitly (`global` or `project`) in this command.
 
 Copilot:
+
 - Global runtime target: `~/.copilot/mcp-config.json` (`servers`)
 - Project runtime target: `<workspace>/.vscode/mcp.json` (`servers`)
 - Foundry side-by-side server id: `cubis-foundry` (stdio command server)
@@ -361,6 +395,7 @@ cbx workflows install --platform codex --bundle agent-environment-setup --postma
 ```
 
 When `--mcp-runtime docker` is selected and Docker is available, install now prepares the image automatically:
+
 - Pulls the image by default (`docker pull`)
 - Or builds locally when `--mcp-build-local` is set
 
@@ -373,6 +408,7 @@ cbx mcp tools list --service stitch --scope global
 ```
 
 Notes:
+
 - `cbx mcp tools sync` requires `POSTMAN_API_KEY_DEFAULT`.
 - For `--service stitch` or `--service all`, it also requires `STITCH_API_KEY_DEFAULT`.
 
@@ -392,6 +428,7 @@ npm run check:mcp-rules:all
 ```
 
 Generated MCP artifacts:
+
 - `mcp/generated/mcp-manifest.json` (catalog snapshot used by managed rule blocks)
 - `mcp/generated/README.md` (artifact notes)
 
@@ -502,6 +539,7 @@ cbx workflows config --scope project --mcp-runtime docker --mcp-fallback local
 ```
 
 `--show` now includes computed `status`:
+
 - stored source (from active profile config)
 - effective source (resolved at runtime with env)
 - active profile name
@@ -518,12 +556,14 @@ cbx rules tech-md --overwrite --compact
 ### Removed aliases
 
 The following aliases were removed:
+
 - `cbx skills ...`
 - `cbx install`
 - `cbx platforms`
 - `cbx workflows init`
 
 Use these canonical replacements:
+
 - `cbx init` (guided interactive installer)
 - `cbx workflows ...`
 - `cbx workflows install`
@@ -548,6 +588,7 @@ cbx workflows remove-all --scope all --platform all --yes
 ```
 
 What it removes (by scope/platform selection):
+
 - Generated workflows/agents/skills wrappers.
 - Managed rule blocks and generated engineering docs (`AGENTS.md`, `ENGINEERING_RULES.md`, `TECH.md`) where applicable.
 - Managed MCP definition files and runtime target entries.
@@ -574,9 +615,11 @@ TECH.md
 ### `MCP startup failed: Environment variable POSTMAN_API_KEY_* ... is not set`
 
 Cause:
+
 - Active profile uses env alias but variable is not exported in current shell/process.
 
 Fix:
+
 ```bash
 export POSTMAN_API_KEY_DEFAULT="<key>"
 cbx workflows config --scope global --show
@@ -587,11 +630,13 @@ Then confirm `status.postman.effectiveSource` is `env`.
 ### `apiKeySource` looks unset even after export
 
 Use:
+
 ```bash
 cbx workflows config --scope global --show
 ```
 
 Check these fields:
+
 - `status.postman.storedSource`
 - `status.postman.effectiveSource`
 - `status.postman.effectiveEnvVar`
@@ -601,15 +646,18 @@ If stored source is env but effective source is unset, your env var alias is mis
 ### Existing config skipped during install
 
 If installer says config was skipped:
+
 - Re-run with `--overwrite`, or
 - Use `cbx workflows config` / `cbx workflows config keys ...` to mutate existing config.
 
 ### Docker runtime starts but skill discovery is zero
 
 Cause:
+
 - Runtime container has no skill mount at `/workflows/skills`.
 
 Fix:
+
 ```bash
 # Ensure host skill vault exists
 ls ~/.agents/skills

package/dist/cli/core.js

@@ -109,7 +109,7 @@ const WORKFLOW_PROFILES = {
             agentDirs: [".github/agents"],
             skillDirs: [".github/skills"],
             promptDirs: [".github/prompts"],
-            ruleFilesByPriority: [".github/copilot-instructions.md", "AGENTS.md"],
+            ruleFilesByPriority: [".github/copilot-instructions.md"],
         },
         global: {
             workflowDirs: ["~/.copilot/workflows"],
@@ -129,6 +129,31 @@ const WORKFLOW_PROFILES = {
         legacyDetectorPaths: [],
         ruleHintName: "AGENTS.md or .github/copilot-instructions.md",
     },
+    claude: {
+        id: "claude",
+        label: "Claude Code",
+        installsCustomAgents: true,
+        project: {
+            workflowDirs: [".claude/workflows"],
+            agentDirs: [".claude/agents"],
+            skillDirs: [".claude/skills"],
+            ruleFilesByPriority: ["CLAUDE.md"],
+        },
+        global: {
+            workflowDirs: ["~/.claude/workflows"],
+            agentDirs: ["~/.claude/agents"],
+            skillDirs: ["~/.claude/skills"],
+            ruleFilesByPriority: ["~/.claude/CLAUDE.md"],
+        },
+        detectorPaths: [
+            "CLAUDE.md",
+            ".claude",
+            ".claude/rules",
+            ".claude/settings.json",
+        ],
+        legacyDetectorPaths: [],
+        ruleHintName: "CLAUDE.md",
+    },
 };
 const PLATFORM_IDS = Object.keys(WORKFLOW_PROFILES);
 const CODEX_WORKFLOW_SKILL_PREFIX = "workflow-";
@@ -931,7 +956,10 @@ async function upsertEngineeringRulesFile({ targetPath, template, overwrite = fa
     const analysis = analyzeTaggedBlock(original, ENGINEERING_RULES_FILE_BLOCK_START_RE, ENGINEERING_RULES_FILE_BLOCK_END_RE);
     if (analysis.status === "absent") {
         if (!isLikelyGeneratedEngineeringRules(original)) {
-            return { action: dryRun ? "would-skip" : "skipped", filePath: targetPath };
+            return {
+                action: dryRun ? "would-skip" : "skipped",
+                filePath: targetPath,
+            };
         }
         return writeTextFile({
             targetPath,
@@ -1376,7 +1404,8 @@ function inferArchitectureByApp(relativeFiles, relativeDirs) {
     const appRoots = new Set(["."]);
     for (const relPath of relativeFiles) {
         const segments = relPath.split("/");
-        if (segments.length >= 3 && (segments[0] === "apps" || segments[0] === "packages")) {
+        if (segments.length >= 3 &&
+            (segments[0] === "apps" || segments[0] === "packages")) {
             appRoots.add(`${segments[0]}/${segments[1]}`);
             continue;
         }
@@ -2698,7 +2727,7 @@ function unique(values) {
     return [...new Set(values)];
 }
 function extractFrontmatter(markdown) {
-    const match = markdown.match(/^---\n([\s\S]*?)\n---\n?/);
+    const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
     if (!match) {
         return { frontmatter: "", body: markdown };
     }
@@ -2708,7 +2737,7 @@ function extractFrontmatter(markdown) {
     };
 }
 function hasFrontmatter(markdown) {
-    return /^---\n[\s\S]*?\n---\n?/.test(markdown);
+    return /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.test(markdown);
 }
 function collectTopLevelFrontmatterKeys(frontmatter) {
     const keys = [];
@@ -3212,6 +3241,14 @@ function buildManagedWorkflowBlock(platformId, workflows) {
         lines.push("- Do not use `$workflow-*` / `$agent-*` as the primary route surface here; those are Codex compatibility aliases.");
         lines.push("");
     }
+    else if (platformId === "claude") {
+        lines.push("Prefer native Claude Code route surfaces first:");
+        lines.push("- Rules: `.claude/rules/*.md`");
+        lines.push("- Workflow files: `.claude/workflows/*.md`");
+        lines.push("- Memory: `CLAUDE.md`");
+        lines.push("- Do not use `$workflow-*` / `$agent-*` as the primary route surface here; those are Codex compatibility aliases.");
+        lines.push("");
+    }
     lines.push("Use the following workflows proactively when task intent matches:");
     lines.push("");
     if (workflows.length === 0) {
@@ -3243,6 +3280,11 @@ function buildManagedWorkflowBlock(platformId, workflows) {
         lines.push("2. Else match user intent to one primary workflow and use the matching command file when available.");
         lines.push("3. Treat `$workflow-*` / `$agent-*` as Codex compatibility aliases, not as the primary route surface here.");
     }
+    else if (platformId === "claude") {
+        lines.push("1. Match explicit workflow or scoped rule first.");
+        lines.push("2. Else match user intent to one primary workflow.");
+        lines.push("3. Treat `$workflow-*` / `$agent-*` as Codex compatibility aliases, not as the primary route surface here.");
+    }
     else {
         lines.push("1. Match explicit slash command first.");
         lines.push("2. Else match user intent to workflow description and triggers.");
@@ -4488,7 +4530,8 @@ async function resolvePostmanInstallSelection({ platform, scope, options, cwd =
     let mcpScope = requestedMcpScope || normalizeMcpScope(scope, "project");
     const warnings = [];
     const stitchEnabled = stitchRequested ||
-        (platform === "antigravity" && options.stitchDefaultForAntigravity !== false);
+        (platform === "antigravity" &&
+            options.stitchDefaultForAntigravity !== false);
     const envStitchApiKey = normalizePostmanApiKey(process.env[STITCH_API_KEY_ENV_VAR]);
     const requestedRuntime = normalizeMcpRuntime(options.mcpRuntime, DEFAULT_MCP_RUNTIME);
     const requestedFallback = normalizeMcpFallback(options.mcpFallback, DEFAULT_MCP_FALLBACK);
@@ -4920,7 +4963,8 @@ async function applyPostmanConfigArtifacts({ platform, mcpScope, configValue, dr
     const warnings = [];
     const postmanState = ensureCredentialServiceState(configValue, "postman");
     const stitchState = parseStoredStitchConfig(configValue);
-    const postmanApiKeyEnvVar = normalizePostmanApiKey(postmanState.apiKeyEnvVar) || POSTMAN_API_KEY_ENV_VAR;
+    const postmanApiKeyEnvVar = normalizePostmanApiKey(postmanState.apiKeyEnvVar) ||
+        POSTMAN_API_KEY_ENV_VAR;
     const postmanMcpUrl = postmanState.mcpUrl || POSTMAN_MCP_URL;
     const stitchEnabled = Boolean(stitchState);
     const stitchApiKeyEnvVar = normalizePostmanApiKey(stitchState?.apiKeyEnvVar) || STITCH_API_KEY_ENV_VAR;
@@ -5384,7 +5428,8 @@ async function installBundleArtifacts({ bundleId, manifest, platform, scope, ove
                 overwrite,
                 dryRun,
             });
-            if (indexResult.action === "skipped" || indexResult.action === "would-skip")
+            if (indexResult.action === "skipped" ||
+                indexResult.action === "would-skip")
                 skipped.push(skillsIndexDest);
             else
                 installed.push(skillsIndexDest);
@@ -6824,7 +6869,11 @@ async function removeMcpRuntimeEntriesJson({ filePath, keyName, serverIds, dryRu
 }
 async function removePlatformMcpRuntimeTargets({ platform, scope, dryRun = false, cwd = process.cwd(), }) {
     const workspaceRoot = findWorkspaceRoot(cwd);
-    const serverIds = [POSTMAN_SKILL_ID, FOUNDRY_MCP_SERVER_ID, STITCH_MCP_SERVER_ID];
+    const serverIds = [
+        POSTMAN_SKILL_ID,
+        FOUNDRY_MCP_SERVER_ID,
+        STITCH_MCP_SERVER_ID,
+    ];
     if (platform === "antigravity") {
         const settingsPath = scope === "global"
             ? path.join(os.homedir(), ".gemini", "settings.json")
@@ -6972,7 +7021,9 @@ async function runWorkflowRemoveAll(options) {
                         extraSkillIds: [],
                     });
                     const wrapperSkillIds = platform === "codex" ? buildCodexWrapperSkillIds(platformSpec) : [];
-                    const bundleSkillIds = [...new Set([...skillIds, ...wrapperSkillIds])];
+                    const bundleSkillIds = [
+                        ...new Set([...skillIds, ...wrapperSkillIds]),
+                    ];
                     for (const workflowsDir of alternateWorkflowsDirs) {
                         for (const workflowFile of workflowFiles) {
                             await removePathRecord({
@@ -8116,12 +8167,10 @@ async function runWorkflowConfig(options) {
             let platform = null;
             const explicitPlatform = normalizePlatform(opts.platform);
             const configuredPlatform = normalizePlatform(next?.mcp?.platform);
-            if (explicitPlatform &&
-                WORKFLOW_PROFILES[explicitPlatform]) {
+            if (explicitPlatform && WORKFLOW_PROFILES[explicitPlatform]) {
                 platform = explicitPlatform;
             }
-            else if (configuredPlatform &&
-                WORKFLOW_PROFILES[configuredPlatform]) {
+            else if (configuredPlatform && WORKFLOW_PROFILES[configuredPlatform]) {
                 platform = configuredPlatform;
             }
             else {
@@ -9260,7 +9309,9 @@ function normalizeInitMcpSelections(value) {
     const items = Array.isArray(value) ? value : parseCsvOption(value);
     const normalized = [];
     for (const item of items) {
-        const key = String(item || "").trim().toLowerCase();
+        const key = String(item || "")
+            .trim()
+            .toLowerCase();
         if (!allowed.has(key))
             continue;
         if (!normalized.includes(key))
@@ -9391,12 +9442,10 @@ async function runInitWizard(options) {
             selections.stitchApiKey = await promptOptionalSecret("Stitch API key (optional, leave blank to keep existing env/profile state):");
         }
         if (selections.postmanApiKey) {
-            process.env[profileEnvVarAlias("postman", DEFAULT_CREDENTIAL_PROFILE_NAME)] =
-                selections.postmanApiKey;
+            process.env[profileEnvVarAlias("postman", DEFAULT_CREDENTIAL_PROFILE_NAME)] = selections.postmanApiKey;
         }
         if (selections.stitchApiKey) {
-            process.env[profileEnvVarAlias("stitch", DEFAULT_CREDENTIAL_PROFILE_NAME)] =
-                selections.stitchApiKey;
+            process.env[profileEnvVarAlias("stitch", DEFAULT_CREDENTIAL_PROFILE_NAME)] = selections.stitchApiKey;
         }
         const plan = buildInitExecutionPlan({
             selections,
@@ -9549,7 +9598,9 @@ export function buildCliProgram() {
 }
 export async function runCli(argv = process.argv) {
     const program = buildCliProgram();
-    const removedTopLevelAlias = String(argv[2] || "").trim().toLowerCase();
+    const removedTopLevelAlias = String(argv[2] || "")
+        .trim()
+        .toLowerCase();
     if (["skills", "install", "platforms"].includes(removedTopLevelAlias)) {
         console.error(`\nError: '${removedTopLevelAlias}' has been removed. Use 'cbx workflows' commands instead.`);
         console.error("Migration:");
@@ -9563,7 +9614,9 @@ export async function runCli(argv = process.argv) {
         process.exit(1);
     }
     if (removedTopLevelAlias === "workflows" &&
-        String(argv[3] || "").trim().toLowerCase() === "init") {
+        String(argv[3] || "")
+            .trim()
+            .toLowerCase() === "init") {
         console.error("\nError: 'cbx workflows init' has been removed.");
         console.error("Use: cbx workflows install");
         process.exit(1);