@cubis/foundry 0.3.57 → 0.3.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.57",
+  "version": "0.3.60",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {
@@ -82,8 +82,10 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.8.6",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "commander": "^14.0.1",
-    "jsonc-parser": "^3.3.1"
+    "jsonc-parser": "^3.3.1",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/src/cli/core.ts

@@ -929,9 +929,35 @@ function buildEngineeringRulesTemplate() {
     "## 8) Response Contract (Decision Log Required)",
     "",
     "- For planning/review/execution summaries, use a `Decision Log` structure.",
-    "- Each decision entry should include: `Context`, `Decision`, `Rationale`, `Tradeoffs`, `Validation`.",
-    "- Include a `Files Used` section with full absolute paths (not shorthand names).",
+    "- Each decision entry must include: `Context`, `Decision`, `Rationale`, `Tradeoffs`, `Validation`.",
+    "- Include `Files Used` with labeled keys and full absolute paths (not shorthand names).",
+    "- Include `Skills Used` with skill IDs and full skill file paths when skills are loaded.",
+    "- Minimum required entries in `Files Used` for project work:",
+    "  - `active_rules_file`: active platform rules file path (for example `AGENTS.md`, `.agent/rules/GEMINI.md`, or `.github/copilot-instructions.md`)",
+    "  - `engineering_rules_file`: `/abs/path/ENGINEERING_RULES.md`",
+    "  - `tech_map_file`: `/abs/path/TECH.md`",
+    "- If no skill is loaded, write `Skills Used: none` explicitly.",
     "- Never hide key file paths behind aliases or abbreviated labels.",
+    "- A Decision Log without required `Files Used` and `Skills Used` is incomplete and must be corrected before final response.",
+    "",
+    "Required shape:",
+    "",
+    "Decision Log",
+    "1. Context: ...",
+    "Decision: ...",
+    "Rationale: ...",
+    "Tradeoffs: ...",
+    "Validation: ...",
+    "",
+    "Files Used",
+    "- active_rules_file: /abs/path/<platform-rule-file>",
+    "- engineering_rules_file: /abs/path/ENGINEERING_RULES.md",
+    "- tech_map_file: /abs/path/TECH.md",
+    "- implementation_file: /abs/path/other/file.ts (as needed)",
+    "",
+    "Skills Used",
+    "- skill-id: /abs/path/<platform-skills-root>/<skill-id>/SKILL.md",
+    "- or: none",
     "",
     "## 9) Keep TECH.md Fresh",
     "",
@@ -967,7 +993,10 @@ function buildEngineeringRulesManagedBlock({
     "3. Apply SOLID pragmatically to reduce change risk, not add ceremony.",
     "4. Use clear naming with focused responsibilities and explicit boundaries.",
     "5. Require validation evidence (lint/types/tests) before merge.",
-    "6. Use Decision Log response style and include full absolute file paths in `Files Used`.",
+    "6. Use Decision Log response style.",
+    "7. Every Decision Log must include both `Files Used` and `Skills Used` sections.",
+    "8. `Files Used` must include labeled keys (`active_rules_file`, `engineering_rules_file`, `tech_map_file`) with full absolute paths.",
+    "9. If no skill loaded, `Skills Used: none` is mandatory.",
     "",
     "<!-- cbx:engineering:auto:end -->",
   ].join("\n");
@@ -1174,6 +1203,99 @@ function parseTomlSections(content) {
   return sections;
 }
 
+function escapeTomlBasicString(value) {
+  return String(value ?? "")
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"');
+}
+
+async function patchCodexPostmanHttpHeaders({
+  configPath,
+  mcpUrl,
+  bearerToken,
+  dryRun = false,
+}) {
+  const warnings = [];
+  const normalizedToken = normalizePostmanApiKey(bearerToken);
+  if (!normalizedToken) {
+    return {
+      action: "skipped",
+      warnings: [
+        "Postman API key is unavailable in current environment. Kept bearer_token_env_var wiring in Codex config.",
+      ],
+    };
+  }
+
+  const configExists = await pathExists(configPath);
+  const original = configExists ? await readFile(configPath, "utf8") : "";
+  const lines = original.split(/\r?\n/);
+  const nextLines = [];
+
+  const headerLine =
+    `http_headers = { Authorization = "Bearer ${escapeTomlBasicString(normalizedToken)}" }`;
+  const serverHeader = "[mcp_servers.postman]";
+  let inPostmanSection = false;
+  let postmanSectionFound = false;
+  let insertedHeaders = false;
+
+  const flushPostmanHeaderIfNeeded = () => {
+    if (inPostmanSection && !insertedHeaders) {
+      nextLines.push(headerLine);
+      insertedHeaders = true;
+    }
+  };
+
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (sectionMatch) {
+      flushPostmanHeaderIfNeeded();
+      const sectionName = sectionMatch[1].trim();
+      inPostmanSection = sectionName === "mcp_servers.postman";
+      if (inPostmanSection) {
+        postmanSectionFound = true;
+        insertedHeaders = false;
+      }
+      nextLines.push(line);
+      continue;
+    }
+
+    if (inPostmanSection) {
+      if (
+        /^\s*(bearer_token_env_var|http_headers|env_http_headers)\s*=/.test(
+          line,
+        )
+      ) {
+        continue;
+      }
+    }
+    nextLines.push(line);
+  }
+
+  flushPostmanHeaderIfNeeded();
+
+  if (!postmanSectionFound) {
+    if (nextLines.length > 0 && nextLines[nextLines.length - 1].trim() !== "") {
+      nextLines.push("");
+    }
+    nextLines.push(serverHeader);
+    nextLines.push(`url = "${escapeTomlBasicString(mcpUrl || POSTMAN_MCP_URL)}"`);
+    nextLines.push(headerLine);
+  }
+
+  const next = `${nextLines.join("\n").replace(/\n+$/g, "")}\n`;
+  if (next === original) {
+    return { action: "unchanged", warnings };
+  }
+  if (!dryRun) {
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, next, "utf8");
+  }
+  return {
+    action: dryRun ? "would-patch" : "patched",
+    warnings,
+  };
+}
+
 function parsePubspecDependencyNames(content) {
   const packages = new Set();
   let currentSection = null;
@@ -5005,6 +5127,23 @@ async function applyPostmanMcpForPlatform({
           ],
           { cwd },
         );
+        const postmanToken = normalizePostmanApiKey(
+          process.env[apiKeyEnvVar || POSTMAN_API_KEY_ENV_VAR],
+        );
+        const postmanPatch = await patchCodexPostmanHttpHeaders({
+          configPath: codexConfigPath,
+          mcpUrl,
+          bearerToken: postmanToken,
+          dryRun: false,
+        });
+        if (postmanPatch.action === "patched") {
+          warnings.push(
+            "Codex Postman MCP config patched to static Authorization header for startup reliability.",
+          );
+        }
+        if (postmanPatch.warnings?.length) {
+          warnings.push(...postmanPatch.warnings);
+        }
       } catch (error) {
         warnings.push(
           `Failed to register Postman MCP via Codex CLI. Ensure 'codex' is installed and rerun. (${error.message})`,

package/workflows/skills/postman/SKILL.md

@@ -18,19 +18,20 @@ References:
 - Accept both dynamic naming styles from clients:
   - dotted: `postman.<tool>`
   - alias: `postman_<tool>`
+- Never default to raw Postman REST JSON payloads, Newman, or Postman CLI when MCP tools are available.
 - Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
 
-1. Install with Postman enabled and explicit full mode:
-   - `cbx workflows install --platform <codex|antigravity|copilot> --scope global --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
+1. Install with Postman enabled and explicit full mode (use the same scope as your current install):
+   - `cbx workflows install --platform <codex|antigravity|copilot> --scope <project|global> --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
 2. Persist env aliases once (no per-session re-export):
    - `cbx workflows config keys persist-env --service postman --scope global`
 3. Verify mode/config:
-   - `cbx workflows config --scope global --show`
-   - `cbx mcp tools sync --service postman --scope global`
-   - `cbx mcp tools list --service postman --scope global`
+   - `cbx workflows config --scope <project|global> --show`
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
 
 ## Preflight
 
@@ -41,6 +42,10 @@ References:
 3. Discover upstream tools:
    - Confirm required tools exist before execution (for example workspaces/collections/runs).
 
+Execution rule:
+- For Postman requests, call MCP tools directly (`postman.*` or `postman_*`) instead of drafting manual JSON or curl payloads.
+- If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -52,7 +57,7 @@ Resolve workspace in this order:
 4. If multiple workspaces and no default:
    - Ask user to choose one.
    - Recommend persisting it with:
-     - `cbx workflows config --scope global --workspace-id <workspace-id>`
+     - `cbx workflows config --scope <project|global> --workspace-id <workspace-id>`
 
 When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
 
@@ -75,10 +80,10 @@ If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.
 2. Resync catalog:
-   - `cbx mcp tools sync --service postman --scope global`
-   - `cbx mcp tools list --service postman --scope global`
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
 3. Recreate runtime if needed:
-   - `cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
+   - `cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
 
 ## Security Notes
 

package/workflows/skills/postman/references/full-mode-setup.md

@@ -7,7 +7,7 @@ Use CLI mode flags instead of manual `jq` edits.
 ```bash
 cbx workflows install \
   --platform codex \
-  --scope global \
+  --scope <project|global> \
   --bundle agent-environment-setup \
   --postman \
   --postman-mode full \
@@ -21,7 +21,7 @@ cbx workflows install \
 ## Change Mode Later
 
 ```bash
-cbx workflows config --scope global --platform codex --postman-mode full
+cbx workflows config --scope <project|global> --platform codex --postman-mode full
 ```
 
 This updates:
@@ -34,3 +34,7 @@ This updates:
 ```bash
 cbx workflows config keys persist-env --service postman --scope global
 ```
+
+Note:
+- `persist-env` writes CBX-managed aliases to `~/.cbx/credentials.env`.
+- Keep MCP target scope (`project` or `global`) aligned with the scope where you installed Postman integration.

package/workflows/skills/postman/references/troubleshooting.md

@@ -3,19 +3,24 @@
 ## Only `postman_get_*` / `postman_set_mode` tools appear
 
 1. Confirm active env alias exists in shell (or persisted env file).
-2. Sync catalog:
+2. Sync catalog in the same install scope:
 
 ```bash
-cbx mcp tools sync --service postman --scope global
-cbx mcp tools list --service postman --scope global
+cbx mcp tools sync --service postman --scope <project|global>
+cbx mcp tools list --service postman --scope <project|global>
 ```
 
 3. Restart runtime if using Docker:
 
 ```bash
-cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310
+cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310
 ```
 
+4. If dynamic Postman tools are still missing, do not fall back to manual JSON/CLI by default:
+   - report MCP tool discovery failure
+   - ask for remediation approval
+   - only use fallback if the user explicitly requests it
+
 ## Client does not show dotted names
 
 Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.

package/workflows/workflows/agent-environment-setup/manifest.json

@@ -22,7 +22,8 @@
         "mobile.md",
         "devops.md",
         "qa.md",
-        "vercel.md"
+        "vercel.md",
+        "postman.md"
       ],
       "agents": [
         "backend-specialist.md",
@@ -193,7 +194,8 @@
         "mobile.toml",
         "devops.toml",
         "qa.toml",
-        "vercel.toml"
+        "vercel.toml",
+        "postman.toml"
       ]
     },
     "codex": {
@@ -215,7 +217,8 @@
         "mobile.md",
         "devops.md",
         "qa.md",
-        "vercel.md"
+        "vercel.md",
+        "postman.md"
       ],
       "agents": [
         "backend-specialist.md",
@@ -388,7 +391,8 @@
         "mobile.md",
         "devops.md",
         "qa.md",
-        "vercel.md"
+        "vercel.md",
+        "postman.md"
       ],
       "agents": [
         "backend-specialist.md",
@@ -559,7 +563,8 @@
         "workflow-mobile.prompt.md",
         "workflow-devops.prompt.md",
         "workflow-qa.prompt.md",
-        "workflow-vercel.prompt.md"
+        "workflow-vercel.prompt.md",
+        "workflow-postman.prompt.md"
       ]
     }
   }

package/workflows/workflows/agent-environment-setup/platforms/antigravity/commands/postman.toml

@@ -0,0 +1,11 @@
+description = "Execute Postman MCP operations for workspaces, collections, environments, and runs."
+prompt = '''
+Follow the /postman workflow from .agent/workflows/postman.md.
+
+Execution contract:
+1. Confirm the request fits the workflow's "When to use" section.
+2. Execute according to "Workflow steps" and apply "Context notes".
+3. Complete "Verification" checks and report concrete evidence.
+
+If command arguments are provided, treat them as additional user context.
+'''

package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/postman.md

@@ -0,0 +1,40 @@
+---
+command: "/postman"
+description: "Execute Postman MCP operations for workspaces, collections, environments, and runs."
+triggers: ["postman", "collection", "workspace", "environment", "runcollection", "monitor", "mock", "api test"]
+---
+# Postman Workflow
+
+## When to use
+Use this when tasks are primarily about Postman workspaces, collections, environments, monitors, mocks, or collection runs.
+
+## Routing
+- Postman operations and execution: `@backend-specialist`
+- Security/compliance checks on test data: `@security-auditor`
+- Validation quality and assertions: `@test-engineer`
+
+## Context notes
+- This workflow file, active platform rules, and selected agents/skills guide execution.
+- Resolve and pass workspace IDs explicitly when tools require them.
+- Prefer MCP tools (`postman.*` or `postman_*`) over manual JSON/CLI fallback unless fallback is explicitly requested by the user.
+
+## Skill Routing
+- Primary skills: `postman`
+- Supporting skills (optional): `api-designer`, `test-master`
+
+## Workflow steps
+1. Load Postman skill and check integration status (`postman_get_status`).
+2. Resolve workspace ID (user-provided, configured default, or explicit selection).
+3. Execute required MCP operations (list/create/update/run) with explicit IDs.
+4. Summarize outcomes, failures, and next actions with exact object identifiers.
+
+## Verification
+- Confirm requested Postman action completed successfully.
+- Validate response status and key result fields (IDs, counts, failures).
+- Note any skipped steps and required follow-up.
+
+## Output Contract
+- Workspace/context used
+- Actions executed and resulting IDs
+- Pass/fail summary for runs
+- Follow-up or remediation steps

package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md

@@ -105,6 +105,7 @@ When user intent includes Postman workflows (for example: workspace, collection,
 2. If `postman` skill exists, load `skill_get "postman"` before workflow/agent routing.
 3. Prefer Postman MCP tools (`postman.*`) over Newman/CLI fallback unless the user explicitly asks for fallback.
 4. If `--postman` was installed but `postman` skill cannot be found, report installation drift and suggest reinstall with `cbx workflows install ... --postman`.
+5. Do not default to raw Postman REST JSON payloads or curl for execution when Postman MCP tools are available.
 
 **Hard rules:**
 

package/workflows/workflows/agent-environment-setup/platforms/codex/workflows/postman.md

@@ -0,0 +1,40 @@
+---
+command: "/postman"
+description: "Execute Postman MCP operations for workspaces, collections, environments, and runs."
+triggers: ["postman", "collection", "workspace", "environment", "runcollection", "monitor", "mock", "api test"]
+---
+# Postman Workflow
+
+## When to use
+Use this when tasks are primarily about Postman workspaces, collections, environments, monitors, mocks, or collection runs.
+
+## Routing
+- Postman operations and execution: `@backend-specialist`
+- Security/compliance checks on test data: `@security-auditor`
+- Validation quality and assertions: `@test-engineer`
+
+## Context notes
+- This workflow file, active platform rules, and selected agents/skills guide execution.
+- Resolve and pass workspace IDs explicitly when tools require them.
+- Prefer MCP tools (`postman.*` or `postman_*`) over manual JSON/CLI fallback unless fallback is explicitly requested by the user.
+
+## Skill Routing
+- Primary skills: `postman`
+- Supporting skills (optional): `api-designer`, `test-master`
+
+## Workflow steps
+1. Load Postman skill and check integration status (`postman_get_status`).
+2. Resolve workspace ID (user-provided, configured default, or explicit selection).
+3. Execute required MCP operations (list/create/update/run) with explicit IDs.
+4. Summarize outcomes, failures, and next actions with exact object identifiers.
+
+## Verification
+- Confirm requested Postman action completed successfully.
+- Validate response status and key result fields (IDs, counts, failures).
+- Note any skipped steps and required follow-up.
+
+## Output Contract
+- Workspace/context used
+- Actions executed and resulting IDs
+- Pass/fail summary for runs
+- Follow-up or remediation steps

package/workflows/workflows/agent-environment-setup/platforms/copilot/prompts/workflow-postman.prompt.md

@@ -0,0 +1,11 @@
+# Workflow Prompt: /postman
+
+Execute Postman MCP operations for workspaces, collections, environments, and runs.
+
+Use this prompt with the matching workflow file:
+- Workflow: ../copilot/workflows/postman.md
+
+Execution contract:
+1. Apply workflow sections in order: When to use, Workflow steps, Context notes, Verification.
+2. Route to the workflow's primary specialist and only add supporting specialists when needed.
+3. Return actions taken, verification evidence, and any gaps.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/documentation-templates/docs/api.md

@@ -0,0 +1,16 @@
+# API Reference Template
+
+Use this file as the canonical entry point for API endpoint documentation.
+
+## Endpoint Index
+
+- `GET /resource`
+- `POST /resource`
+- `PATCH /resource/{id}`
+- `DELETE /resource/{id}`
+
+## Conventions
+
+- Include auth requirements per endpoint.
+- Include request/response examples.
+- Include error codes and retry guidance.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/documentation-templates/docs/architecture.md

@@ -0,0 +1,23 @@
+# Architecture Overview Template
+
+Use this file to describe system boundaries and data flow.
+
+## Components
+
+- API layer
+- Domain/service layer
+- Persistence layer
+- External integrations
+
+## Runtime Flow
+
+1. Request enters API layer
+2. Domain logic validates and processes
+3. Persistence reads/writes state
+4. Response returns with observability metadata
+
+## Non-Functional Notes
+
+- Reliability/SLOs
+- Security model
+- Scaling strategy

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/SKILL.md

@@ -18,19 +18,20 @@ References:
 - Accept both dynamic naming styles from clients:
   - dotted: `postman.<tool>`
   - alias: `postman_<tool>`
+- Never default to raw Postman REST JSON payloads, Newman, or Postman CLI when MCP tools are available.
 - Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
 
-1. Install with Postman enabled and explicit full mode:
-   - `cbx workflows install --platform <codex|antigravity|copilot> --scope global --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
+1. Install with Postman enabled and explicit full mode (use the same scope as your current install):
+   - `cbx workflows install --platform <codex|antigravity|copilot> --scope <project|global> --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
 2. Persist env aliases once (no per-session re-export):
    - `cbx workflows config keys persist-env --service postman --scope global`
 3. Verify mode/config:
-   - `cbx workflows config --scope global --show`
-   - `cbx mcp tools sync --service postman --scope global`
-   - `cbx mcp tools list --service postman --scope global`
+   - `cbx workflows config --scope <project|global> --show`
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
 
 ## Preflight
 
@@ -41,6 +42,10 @@ References:
 3. Discover upstream tools:
    - Confirm required tools exist before execution (for example workspaces/collections/runs).
 
+Execution rule:
+- For Postman requests, call MCP tools directly (`postman.*` or `postman_*`) instead of drafting manual JSON or curl payloads.
+- If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -52,7 +57,7 @@ Resolve workspace in this order:
 4. If multiple workspaces and no default:
    - Ask user to choose one.
    - Recommend persisting it with:
-     - `cbx workflows config --scope global --workspace-id <workspace-id>`
+     - `cbx workflows config --scope <project|global> --workspace-id <workspace-id>`
 
 When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
 
@@ -75,10 +80,10 @@ If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.
 2. Resync catalog:
-   - `cbx mcp tools sync --service postman --scope global`
-   - `cbx mcp tools list --service postman --scope global`
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
 3. Recreate runtime if needed:
-   - `cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
+   - `cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
 
 ## Security Notes
 

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/full-mode-setup.md

@@ -7,7 +7,7 @@ Use CLI mode flags instead of manual `jq` edits.
 ```bash
 cbx workflows install \
   --platform codex \
-  --scope global \
+  --scope <project|global> \
   --bundle agent-environment-setup \
   --postman \
   --postman-mode full \
@@ -21,7 +21,7 @@ cbx workflows install \
 ## Change Mode Later
 
 ```bash
-cbx workflows config --scope global --platform codex --postman-mode full
+cbx workflows config --scope <project|global> --platform codex --postman-mode full
 ```
 
 This updates:
@@ -34,3 +34,7 @@ This updates:
 ```bash
 cbx workflows config keys persist-env --service postman --scope global
 ```
+
+Note:
+- `persist-env` writes CBX-managed aliases to `~/.cbx/credentials.env`.
+- Keep MCP target scope (`project` or `global`) aligned with the scope where you installed Postman integration.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/troubleshooting.md

@@ -3,19 +3,24 @@
 ## Only `postman_get_*` / `postman_set_mode` tools appear
 
 1. Confirm active env alias exists in shell (or persisted env file).
-2. Sync catalog:
+2. Sync catalog in the same install scope:
 
 ```bash
-cbx mcp tools sync --service postman --scope global
-cbx mcp tools list --service postman --scope global
+cbx mcp tools sync --service postman --scope <project|global>
+cbx mcp tools list --service postman --scope <project|global>
 ```
 
 3. Restart runtime if using Docker:
 
 ```bash
-cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310
+cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310
 ```
 
+4. If dynamic Postman tools are still missing, do not fall back to manual JSON/CLI by default:
+   - report MCP tool discovery failure
+   - ask for remediation approval
+   - only use fallback if the user explicitly requests it
+
 ## Client does not show dotted names
 
 Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.