@cubis/foundry 0.3.64 → 0.3.66

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

@@ -0,0 +1,192 @@
+---
+name: "agent-handoff"
+description: >
+  Load this skill when you are a CUSTOM AGENT spawned by a workflow and have received a task envelope.
+  Covers: reading the envelope, cold-start protocol, skill_get without skill_search, writing deliverables,
+  returning the result envelope, and what NOT to load into context.
+  DO NOT trigger for orchestrator/workflow-level planning — that is the workflow's job.
+  ALWAYS trigger when: "task envelope received", "spawned from workflow", "agent executing milestone",
+  "result envelope", "handoff".
+---
+# Agent Handoff Skill
+# Zero-bloat protocol for agents spawned from Foundry workflows
+
+## What This Skill Does
+
+You are a custom agent. You were spawned from a workflow with a task envelope.
+This skill tells you exactly how to execute without loading unnecessary context.
+
+---
+
+## Step 1 — Read Your Task Envelope
+
+You received a task envelope. It looks like this:
+```json
+{
+  "milestone_id": "M2",
+  "milestone_name": "Build API layer",
+  "deliverable_path": "src/api/routes.ts",
+  "acceptance_criteria": "File exists, tests pass",
+  "skill_name": "web-backend",
+  "status_file": "TASK_STATUS.md",
+  "env_context": ["NODE_ENV", "API_BASE_URL"]
+}
+```
+
+Fields you MUST use:
+- `milestone_id` — your scope identifier
+- `deliverable_path` — where to write your output
+- `acceptance_criteria` — how to verify completion
+- `skill_name` — the skill to load (pre-resolved by orchestrator)
+- `status_file` — the task status file to read and update
+
+---
+
+## Step 2 — Orient (Cold-Start, Minimal Read)
+
+Read ONLY the project status file named in `status_file` (usually TASK_STATUS.md).
+Use the [TASK_STATUS template](references/TASK_STATUS.md) only to confirm the expected shape.
+
+```
+If your milestone shows "complete" → return result envelope immediately, skip execution.
+If your milestone shows "blocked" → surface the block, do not attempt execution.
+If your milestone shows "pending" or is absent → proceed to Step 3.
+```
+
+**DO NOT read:**
+- TASK_SPEC.md (not needed unless acceptance criteria are ambiguous — read only then)
+- TASK_PLAN.md (your envelope already has your acceptance criteria)
+- Other milestones' files or outputs
+
+---
+
+## Step 3 — Load Skill (No skill_search)
+
+The orchestrator already resolved your skill. Load it directly:
+
+```
+skill_get "<skill_name from envelope>"
+```
+
+Follow the skill's instructions for executing the work.
+
+If `skill_name` is `"none"` or empty: use direct tool execution — no skill needed.
+
+**Never call `skill_search`** — that's the orchestrator's job. Calling it here wastes tokens.
+
+---
+
+## Step 4 — Execute (Code-Execution Pattern)
+
+Use the code-execution pattern for all data-heavy work:
+
+```
+# BAD — each result enters context
+call tool → result enters context
+call tool → result enters context
+
+# GOOD — process outside context
+write code that:
+  1. calls tools → stores results in variables
+  2. processes data in execution environment
+  3. writes output to deliverable_path
+  4. returns only pass/fail + summary to context
+```
+
+Load only env vars listed in `env_context` — do not scan for or load others.
+
+---
+
+## Step 5 — Verify & Update Status
+
+After execution:
+1. Confirm `deliverable_path` exists
+2. Run acceptance check (as defined in `acceptance_criteria`)
+3. Update the project status file from `status_file` using the [TASK_STATUS template](references/TASK_STATUS.md):
+
+```markdown
+## M2 — Build API layer
+- Status: complete
+- Deliverable: src/api/routes.ts ✓
+- Completed: [timestamp]
+```
+
+---
+
+## Step 6 — Return Result Envelope
+
+Return EXACTLY this structure to the calling workflow — nothing more:
+
+```json
+{
+  "milestone_id": "M2",
+  "status": "complete",
+  "deliverable": "src/api/routes.ts",
+  "verified": true,
+  "summary": "Created 4 REST endpoints. All tests pass.",
+  "errors": []
+}
+```
+
+| Field | Rule |
+|---|---|
+| `status` | One of: `complete`, `failed`, `blocked` |
+| `summary` | 1–3 sentences max — what was done, what was produced |
+| `errors` | Empty array on success; structured error objects on failure |
+| `verified` | Only `true` if acceptance criteria was explicitly checked |
+
+**Never return:** raw stdout, full file contents, intermediate reasoning, test output logs.
+If the workflow needs more detail, it will read `deliverable_path` directly.
+
+---
+
+## What You Must Never Do
+
+| Never | Why |
+|---|---|
+| Call `skill_search` | Wastes tokens — orchestrator already resolved skill |
+| Read TASK_SPEC.md / TASK_PLAN.md upfront | Your envelope has what you need |
+| Return raw tool output to workflow | Multiplies context cost |
+| Write to paths outside your `deliverable_path` | Parallel agent collision risk |
+| Load env vars not in your `env_context` | Credential scope leak |
+| Pass your context to sub-agents without filtering | Cascading bloat |
+
+---
+
+## If You Need to Spawn a Sub-Agent
+
+If your milestone requires spawning another agent:
+1. Build a NEW minimal envelope — do NOT forward your own envelope
+2. Include ONLY what the sub-agent needs for its specific task
+3. Receive sub-agent result envelope only — do not receive its full context
+4. Continue with your milestone after verifying sub-agent result
+
+---
+
+## On Failure
+
+If execution fails:
+1. Update the project status file from `status_file` with failure details
+2. Return result envelope with `"status": "failed"` and structured `errors[]`
+3. Do NOT attempt to recover beyond one retry — surface to orchestrator
+4. Do NOT continue to the next milestone
+
+---
+
+## Platform-Specific Adaptation
+
+This skill works across all Foundry platforms, but agent spawning differs:
+
+| Platform | How You Were Spawned | Return Method |
+|---|---|---|
+| **Claude Code** | Via subagent (Agent tool) or `context: fork` | Return result text — orchestrator reads it |
+| **Antigravity** | Via Agent Manager | Write to `deliverable_path`, Agent Manager collects |
+| **Copilot** | Via custom agent (`.github/agents/`) | Return structured result envelope |
+| **Codex** | Via wrapper workflow (`agent-<name>`) | Return structured result envelope |
+
+On **Claude Code**: You may have restricted tool access if spawned with `allowed-tools`.
+Only use the tools available to you. If you need a tool not in your allowlist, surface
+the need in your result envelope — do not attempt workarounds.
+
+On **Antigravity**: You may be running in parallel with other agents. Strictly respect
+your `deliverable_path` — never write outside it.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/agent-handoff/references/TASK_STATUS.md

@@ -0,0 +1,24 @@
+# TASK_STATUS.md Template
+
+Use this as a shape reference for the project-level status file mentioned in the task envelope.
+Do not copy it blindly if the active project already has a status file format.
+
+```markdown
+# Task Status
+
+## M1 — Example milestone
+- Status: pending
+- Deliverable: src/example.ts
+- Notes: Waiting on implementation
+
+## M2 — Example milestone
+- Status: complete
+- Deliverable: src/api/routes.ts
+- Completed: 2026-03-07T10:00:00Z
+- Notes: Acceptance checks passed
+
+## M3 — Example milestone
+- Status: blocked
+- Deliverable: src/db/schema.sql
+- Blocker: Migration contract not finalized
+```

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

@@ -14,11 +14,17 @@ References:
 ## MCP-First Rule
 
 - Prefer Postman MCP tools for all Postman operations.
-- Accept both dynamic naming styles from clients:
-  - dotted: `postman.<tool>`
-  - alias: `postman_<tool>`
+- Use direct Postman server tools for actual Postman cloud work:
+  - direct server: `postman.<tool>`
+  - client-wrapped direct server: `mcp__postman__<tool>`
+- Treat Foundry `postman_*` tools as config helpers only:
+  - `postman_get_status`
+  - `postman_get_mode`
+  - `postman_set_mode`
 - 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.
+- Do not use `postman.runMonitor` as an automatic fallback after `postman.runCollection` timeout or failure.
+- Only use monitor execution when the user explicitly asks for monitor-based cloud execution, scheduled monitoring, or monitor validation.
+- Recommend Postman CLI as the default secondary path when direct MCP execution fails.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
@@ -35,16 +41,21 @@ References:
 ## Preflight
 
 1. Read Postman status first:
-   - Call `postman_get_status`.
+   - Call `postman_get_status` for mode/default-workspace/config state.
 2. Ensure mode is `full`:
    - If not, call `postman_set_mode` with `mode: full`.
 3. Discover upstream tools:
-   - Confirm required tools exist before execution (for example workspaces/collections/runs).
+   - Confirm required direct Postman server 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.
+- For Postman requests, call the direct Postman server (`postman.<tool>` or `mcp__postman__<tool>`) instead of Foundry `postman_*` config tools.
 - If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
 
+Quota-safe rule:
+- If `postman.runCollection` times out or fails, stop and classify the error before choosing any fallback.
+- Never auto-convert a collection run failure into `postman.runMonitor`.
+- Recommend Postman CLI first for repeatable local reruns.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -75,6 +86,30 @@ When a Postman tool requires a workspace argument, always pass the resolved work
 
 ## Failure Handling
 
+### Error Classification
+
+Classify failures before suggesting any fallback:
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - monitor quota exhaustion
+  - do not retry monitor runs
+  - recommend local Postman CLI execution
+  - tell the user to check the Postman monitoring usage dashboard
+- `429` or rate-limit response:
+  - Postman API rate limiting
+  - recommend backoff and a lower request burst
+  - do not reinterpret it as monitor quota
+- collection run timeout without quota/rate-limit signal:
+  - direct MCP runtime or tool timeout
+  - do not auto-convert to a monitor run
+  - recommend Postman CLI or a smaller-scope rerun
+
+### Quota Notes
+
+- Monitor usage is separate from Postman API rate 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 remains available.
+
 If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.

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

@@ -28,3 +28,42 @@ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
 ## Missing API key at startup
 
 Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
+
+## Quota-safe execution
+
+Preferred path:
+
+1. Use direct Postman MCP collection execution first (`postman.runCollection` or equivalent).
+2. If that fails, stop and classify the error.
+3. Recommend Postman CLI as the safe default secondary path.
+4. Use monitor execution only when the user explicitly asks for monitor-based cloud execution.
+
+Do not auto-fallback from `runCollection` to `runMonitor`.
+
+## Error classification
+
+### `limitBreachedError` or "breached monitoring usage limit"
+
+- This is monitor quota exhaustion, not generic API failure.
+- Do not retry monitor runs.
+- Do not reinterpret it as an MCP auth issue.
+- Tell the user to check Postman monitoring usage and billing-period reset in the Postman dashboard.
+- Recommend Postman CLI as the next execution path.
+
+### `429` or rate-limited API response
+
+- This is Postman API rate limiting.
+- Reduce request burst, add backoff, and retry later.
+- Do not treat it as monitor quota exhaustion.
+
+### `runCollection` timeout without quota/rate-limit signal
+
+- Treat this as direct MCP/runtime timeout.
+- Do not auto-convert to monitor execution.
+- Recommend Postman CLI or a smaller-scope rerun.
+
+## Monitor usage facts
+
+- Monitor usage is separate from Postman API RPM limits.
+- Monitor usage is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply usage remains available.

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

@@ -18,23 +18,44 @@ Use this when tasks are primarily about Postman workspaces, collections, environ
 ## 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.
+- Use direct Postman MCP server tools for real Postman actions (`postman.<tool>` or client-wrapped equivalent such as `mcp__postman__<tool>`).
+- Reserve Foundry `postman_*` tools for status/mode/config only.
+- Prefer direct Postman MCP tools over manual JSON/CLI fallback unless fallback is explicitly requested by the user.
+- Support monitor tasks only when the user explicitly asks for monitor-based cloud execution or monitor validation.
+- Never auto-fallback from `postman.runCollection` failure into `postman.runMonitor`.
+- Recommend Postman CLI as the default secondary path after direct MCP execution fails.
 
 ## 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`).
+1. Load Postman skill and check integration status (`postman_get_status` for config/status only).
 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.
+3. Execute required direct Postman MCP operations (list/create/update/run) with explicit IDs.
+4. If execution fails, classify the error before suggesting any fallback.
+5. 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.
 
+## Failure classification
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - classify as monitor quota exhaustion
+  - do not retry monitor execution
+  - recommend Postman CLI
+  - direct the user to Postman monitoring usage dashboard
+- `429` or rate-limited API response:
+  - classify as Postman API rate limiting
+  - recommend backoff and lower request burst
+- collection-run timeout without quota/rate-limit signal:
+  - classify as direct MCP/runtime timeout
+  - do not auto-convert to monitor execution
+  - recommend Postman CLI or smaller-scope rerun
+
 ## Output Contract
 ```yaml
 POSTMAN_WORKFLOW_RESULT:

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

@@ -15,11 +15,17 @@ References:
 ## MCP-First Rule
 
 - Prefer Postman MCP tools for all Postman operations.
-- Accept both dynamic naming styles from clients:
-  - dotted: `postman.<tool>`
-  - alias: `postman_<tool>`
+- Use direct Postman server tools for actual Postman cloud work:
+  - direct server: `postman.<tool>`
+  - client-wrapped direct server: `mcp__postman__<tool>`
+- Treat Foundry `postman_*` tools as config helpers only:
+  - `postman_get_status`
+  - `postman_get_mode`
+  - `postman_set_mode`
 - 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.
+- Do not use `postman.runMonitor` as an automatic fallback after `postman.runCollection` timeout or failure.
+- Only use monitor execution when the user explicitly asks for monitor-based cloud execution, scheduled monitoring, or monitor validation.
+- Recommend Postman CLI as the default secondary path when direct MCP execution fails.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
@@ -36,16 +42,21 @@ References:
 ## Preflight
 
 1. Read Postman status first:
-   - Call `postman_get_status`.
+   - Call `postman_get_status` for mode/default-workspace/config state.
 2. Ensure mode is `full`:
    - If not, call `postman_set_mode` with `mode: full`.
 3. Discover upstream tools:
-   - Confirm required tools exist before execution (for example workspaces/collections/runs).
+   - Confirm required direct Postman server 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.
+- For Postman requests, call the direct Postman server (`postman.<tool>` or `mcp__postman__<tool>`) instead of Foundry `postman_*` config tools.
 - If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
 
+Quota-safe rule:
+- If `postman.runCollection` times out or fails, stop and classify the error before choosing any fallback.
+- Never auto-convert a collection run failure into `postman.runMonitor`.
+- Recommend Postman CLI first for repeatable local reruns.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -76,6 +87,30 @@ When a Postman tool requires a workspace argument, always pass the resolved work
 
 ## Failure Handling
 
+### Error Classification
+
+Classify failures before suggesting any fallback:
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - monitor quota exhaustion
+  - do not retry monitor runs
+  - recommend local Postman CLI execution
+  - tell the user to check the Postman monitoring usage dashboard
+- `429` or rate-limit response:
+  - Postman API rate limiting
+  - recommend backoff and a lower request burst
+  - do not reinterpret it as monitor quota
+- collection run timeout without quota/rate-limit signal:
+  - direct MCP runtime or tool timeout
+  - do not auto-convert to a monitor run
+  - recommend Postman CLI or a smaller-scope rerun
+
+### Quota Notes
+
+- Monitor usage is separate from Postman API rate 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 remains available.
+
 If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.

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

@@ -28,3 +28,42 @@ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
 ## Missing API key at startup
 
 Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
+
+## Quota-safe execution
+
+Preferred path:
+
+1. Use direct Postman MCP collection execution first (`postman.runCollection` or equivalent).
+2. If that fails, stop and classify the error.
+3. Recommend Postman CLI as the safe default secondary path.
+4. Use monitor execution only when the user explicitly asks for monitor-based cloud execution.
+
+Do not auto-fallback from `runCollection` to `runMonitor`.
+
+## Error classification
+
+### `limitBreachedError` or "breached monitoring usage limit"
+
+- This is monitor quota exhaustion, not generic API failure.
+- Do not retry monitor runs.
+- Do not reinterpret it as an MCP auth issue.
+- Tell the user to check Postman monitoring usage and billing-period reset in the Postman dashboard.
+- Recommend Postman CLI as the next execution path.
+
+### `429` or rate-limited API response
+
+- This is Postman API rate limiting.
+- Reduce request burst, add backoff, and retry later.
+- Do not treat it as monitor quota exhaustion.
+
+### `runCollection` timeout without quota/rate-limit signal
+
+- Treat this as direct MCP/runtime timeout.
+- Do not auto-convert to monitor execution.
+- Recommend Postman CLI or a smaller-scope rerun.
+
+## Monitor usage facts
+
+- Monitor usage is separate from Postman API RPM limits.
+- Monitor usage is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply usage remains available.

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

@@ -15,11 +15,17 @@ References:
 ## MCP-First Rule
 
 - Prefer Postman MCP tools for all Postman operations.
-- Accept both dynamic naming styles from clients:
-  - dotted: `postman.<tool>`
-  - alias: `postman_<tool>`
+- Use direct Postman server tools for actual Postman cloud work:
+  - direct server: `postman.<tool>`
+  - client-wrapped direct server: `mcp__postman__<tool>`
+- Treat Foundry `postman_*` tools as config helpers only:
+  - `postman_get_status`
+  - `postman_get_mode`
+  - `postman_set_mode`
 - 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.
+- Do not use `postman.runMonitor` as an automatic fallback after `postman.runCollection` timeout or failure.
+- Only use monitor execution when the user explicitly asks for monitor-based cloud execution, scheduled monitoring, or monitor validation.
+- Recommend Postman CLI as the default secondary path when direct MCP execution fails.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
@@ -36,16 +42,21 @@ References:
 ## Preflight
 
 1. Read Postman status first:
-   - Call `postman_get_status`.
+   - Call `postman_get_status` for mode/default-workspace/config state.
 2. Ensure mode is `full`:
    - If not, call `postman_set_mode` with `mode: full`.
 3. Discover upstream tools:
-   - Confirm required tools exist before execution (for example workspaces/collections/runs).
+   - Confirm required direct Postman server 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.
+- For Postman requests, call the direct Postman server (`postman.<tool>` or `mcp__postman__<tool>`) instead of Foundry `postman_*` config tools.
 - If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
 
+Quota-safe rule:
+- If `postman.runCollection` times out or fails, stop and classify the error before choosing any fallback.
+- Never auto-convert a collection run failure into `postman.runMonitor`.
+- Recommend Postman CLI first for repeatable local reruns.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -76,6 +87,30 @@ When a Postman tool requires a workspace argument, always pass the resolved work
 
 ## Failure Handling
 
+### Error Classification
+
+Classify failures before suggesting any fallback:
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - monitor quota exhaustion
+  - do not retry monitor runs
+  - recommend local Postman CLI execution
+  - tell the user to check the Postman monitoring usage dashboard
+- `429` or rate-limit response:
+  - Postman API rate limiting
+  - recommend backoff and a lower request burst
+  - do not reinterpret it as monitor quota
+- collection run timeout without quota/rate-limit signal:
+  - direct MCP runtime or tool timeout
+  - do not auto-convert to a monitor run
+  - recommend Postman CLI or a smaller-scope rerun
+
+### Quota Notes
+
+- Monitor usage is separate from Postman API rate 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 remains available.
+
 If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.

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

@@ -28,3 +28,42 @@ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
 ## Missing API key at startup
 
 Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
+
+## Quota-safe execution
+
+Preferred path:
+
+1. Use direct Postman MCP collection execution first (`postman.runCollection` or equivalent).
+2. If that fails, stop and classify the error.
+3. Recommend Postman CLI as the safe default secondary path.
+4. Use monitor execution only when the user explicitly asks for monitor-based cloud execution.
+
+Do not auto-fallback from `runCollection` to `runMonitor`.
+
+## Error classification
+
+### `limitBreachedError` or "breached monitoring usage limit"
+
+- This is monitor quota exhaustion, not generic API failure.
+- Do not retry monitor runs.
+- Do not reinterpret it as an MCP auth issue.
+- Tell the user to check Postman monitoring usage and billing-period reset in the Postman dashboard.
+- Recommend Postman CLI as the next execution path.
+
+### `429` or rate-limited API response
+
+- This is Postman API rate limiting.
+- Reduce request burst, add backoff, and retry later.
+- Do not treat it as monitor quota exhaustion.
+
+### `runCollection` timeout without quota/rate-limit signal
+
+- Treat this as direct MCP/runtime timeout.
+- Do not auto-convert to monitor execution.
+- Recommend Postman CLI or a smaller-scope rerun.
+
+## Monitor usage facts
+
+- Monitor usage is separate from Postman API RPM limits.
+- Monitor usage is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply usage remains available.