@postman/postman-plugin 0.3.0 → 0.4.1-rc.0

package/skills/performance-testing/references/jmeter-import/mapping-table.md

@@ -0,0 +1,95 @@
+# JMeter → Postman mapping table
+
+Fidelity: **exact** (behaviour preserved) · **approx** (closest supported equivalent, reported) · **manual** (needs a judgment call, often with the user) · **unsupported** (dropped, reported).
+
+## Structure
+
+| JMeter element | XML tag | Postman | Fidelity |
+|---|---|---|---|
+| Test Plan | `TestPlan` | Collection (`info` + `item`) | exact |
+| Thread Group | `ThreadGroup` | load config (VUs/duration/profile) + folder when >1 | approx |
+| setUp/tearDown Thread Group | `SetupThreadGroup`/`PostThreadGroup` | folder; suggest `--setup-collection`/`--teardown-collection` | approx |
+| Concurrency Thread Group | `...ConcurrencyThreadGroup` | VUs=`TargetLevel`, duration=`RampUp`+`Hold`, `ramp-up` | approx |
+| Stepping Thread Group | `kg.apc...SteppingThreadGroup` | VUs=`num_threads`, duration=`flighttime`, `ramp-up` | approx |
+| Ultimate Thread Group | `kg.apc...UltimateThreadGroup` | VUs=max row concurrency, duration=sum of row times | approx |
+| Arrivals Thread Group | `...ArrivalsThreadGroup` | treated like concurrency | approx |
+| Transaction Controller | `TransactionController` | folder | exact |
+| Simple/Generic Controller | `GenericController`/`SimpleController` | folder | exact |
+| Loop Controller | `LoopController` | flattened; loop count → duration | approx |
+| If Controller | `IfController` | each enclosed request gets a pre-request skip guard (`pm.execution.skipRequest`); `${var}` → `pm.variables.get(...)` | approx |
+| While Controller | `WhileController` | flattened, requests run unconditionally; restore looping with `pm.execution.setNextRequest` | approx |
+| Recording Controller | `RecordingController` | transparent (children recursed) | exact |
+| Module / Include Controller | `ModuleController`/`IncludeController` | flattened children if inline; external refs reported | manual |
+
+## Requests
+
+| JMeter | XML | Postman | Fidelity |
+|---|---|---|---|
+| HTTP Request | `HTTPSamplerProxy` | request item | exact |
+| method / path / domain / port / protocol | `HTTPSampler.*` | `request.method` + `url` (blank protocol → `http`) | exact |
+| Query/body params | `Arguments`/`HTTPArgument` | query (GET) / urlencoded (POST/PUT/PATCH) / formdata (multipart) | exact |
+| Raw body | `postBodyRaw=true` | `body.mode=raw` | exact |
+| Header Manager | `HeaderManager` | `request.header` (merged by scope, later wins) | exact |
+| HTTP Request Defaults | `ConfigTestElement`/`HttpDefaultsGui` | fallback for blank domain/port/protocol/path | exact |
+| Auth Manager Basic/Digest | `AuthManager` | `request.auth` basic/digest (first entry; multiples reported) | exact |
+| Auth Manager Kerberos/NTLM | `AuthManager` mechanism | — | unsupported |
+| Cookie / Cache / DNS Manager | `CookieManager`/... | auto per-VU cookies; presets not transferred | unsupported |
+| Non-HTTP samplers | `JDBC/FTP/LDAP/Java/TCP/Debug/Dummy...Sampler` | — | unsupported |
+
+## Extractors (post-response → test script `pm.collectionVariables.set`)
+
+| JMeter | XML | Fidelity |
+|---|---|---|
+| Regular Expression Extractor | `RegexExtractor` | exact (via `new RegExp`, group from `$n$` template) |
+| Boundary Extractor | `BoundaryExtractor` | exact (left/right → non-greedy regex) |
+| JSON Extractor (native) | `JSONPostProcessor` | exact for dot/index paths; complex → manual |
+| JSON Path Extractor (plugin) | `...JSONPathExtractor` | exact for simple paths |
+| XPath / XPath2 Extractor | `XPathExtractor`/`XPath2Extractor` | manual (no sandbox XPath) |
+| CSS/HTML Extractor | `HtmlExtractor` | manual (no sandbox CSS) |
+
+## Assertions (→ `pm.test`)
+
+| JMeter | XML | Maps to | Fidelity |
+|---|---|---|---|
+| Response Assertion | `ResponseAssertion` | status / contains / equals / matches, honouring `test_type` bitmask + NOT | exact |
+| — test_field response_code | | `pm.response.code` | exact |
+| — test_field response_data | | `pm.response.text()` | exact |
+| — test_field headers/message | | `pm.response.headers`/`.status` | exact |
+| Duration Assertion | `DurationAssertion` | `pm.test` responseTime + `--pass-if less_than(p95, ms)` hint | exact |
+| Size Assertion | `SizeAssertion` | `pm.test` on `responseSize` | approx |
+| JSON Assertion | `JSONPathAssertion` | `pm.test` on simple path | approx |
+
+`ResponseAssertion.test_type` bits: `MATCH=1, CONTAINS=2, NOT=4, EQUALS=8, SUBSTRING=16, OR=32`.
+
+## Variables & data
+
+| JMeter | XML | Postman | Fidelity |
+|---|---|---|---|
+| User Defined Variables | `Arguments` under TestPlan/scope | collection `variable[]` | exact |
+| `${var}` references | inline | `{{var}}` | exact |
+| `${__UUID}` / `${__time}` | function | `{{$guid}}` / `{{$timestamp}}` | exact |
+| `${__Random(...)}` and other `__fn` | function | `{{$randomInt}}` or flagged reference | approx/manual |
+| CSV Data Set Config | `CSVDataSet` | `--data-file` + column list | approx (one file/run; naive CSV) |
+| Counter / Random Variable | `CounterConfig`/`RandomVariableConfig` | pre-request script or `{{$randomInt}}` | manual |
+
+## Scripting
+
+| JMeter | XML | Postman | Fidelity |
+|---|---|---|---|
+| JSR223 PreProcessor | `JSR223PreProcessor` | prerequest script (JS, IIFE-wrapped) | manual |
+| JSR223 PostProcessor | `JSR223PostProcessor` | test script | manual |
+| BeanShell Pre/PostProcessor | `BeanShell*Processor` | pre/test script | manual |
+| JSR223 / BeanShell Sampler | `JSR223Sampler`/`BeanShellSampler` | script-only stub (no HTTP) | manual |
+
+## Timing / pacing — not supported, always reported
+
+Postman performance runs have no think time and no flag for one. Every timer is
+dropped and listed in the report; none is reproduced.
+
+| JMeter | XML |
+|---|---|
+| Constant / Uniform / Gaussian / Poisson Timer | `ConstantTimer`/`UniformRandomTimer`/... |
+| Constant Throughput Timer | `ConstantThroughputTimer` |
+| Throughput Shaping Timer | plugin |
+| Synchronizing Timer | `SyncTimer` |
+| Test Action (pause/stop) | `TestAction` |

package/skills/performance-testing/references/jmeter-import/postman-perf-capabilities.md

@@ -0,0 +1,56 @@
+# What Postman performance testing supports (the import target)
+
+Grounded in the `postman-cli`, `performance-test-api`, and `postman-performance-test` source — not the marketing docs. This is the ceiling an import maps onto. When JMeter asks for something not here, it is reported, never faked.
+
+## `postman performance run` CLI flags that matter for import
+
+| Concern | Flag | Notes |
+|---------|------|-------|
+| Virtual users | `--vu-count <n>` | default 20; cloud runs enforce a **minimum of 10** |
+| Duration | `-d, --duration <minutes>` | **minutes**, not seconds; default 1; cloud ceiling ~120 min (plan-gated) |
+| Load profile | `-p, --load-profile <p>` | one of `fixed`, `ramp-up`, `spike`, `peak`; default `ramp-up` |
+| Data file | `--data-file <path>` | JSON array or CSV; **local runs only**; distribution is forced to `random` |
+| Dataset | `--dataset-id` + `--dataset-view-id` + `--dataset-distribution` | cloud path; distribution `round-robin`/`fixed`/`random` |
+| Pass/fail | `--pass-if "<fn>(<metric>, <value>)"` | **single, not repeatable** |
+| Environment | `-e, --environment <id>` | |
+| Setup/teardown | `--setup-collection` / `--teardown-collection` | run **once** before/after — not concurrent load |
+
+There is **no** `--load-segments`, no `--stages`, no `--iterations`, no think-time flag. A latent YAML "stages" schema exists in the CLI repo but is not wired to the command — do not target it.
+
+## Load profiles
+
+Four named shapes only, each derived from `(vu-count, duration)`:
+
+- `fixed` — constant VUs.
+- `ramp-up` — ramps from 25% to full over the first quarter.
+- `spike` — low baseline, one spike to full mid-run, back down.
+- `peak` — baseline, ramp up, hold, ramp down.
+
+JMeter custom ramp curves, stepping schedules, and arrival-rate shapes **cannot be reproduced**. Pick the closest of the four and report the approximation. Rule: any ramp/stepping/concurrency/ultimate/arrivals group → `ramp-up`; a flat group with zero ramp → `fixed`.
+
+## `--pass-if` metrics and operators
+
+- Functions (operators): `less_than`, `greater_than`, `less_than_eq`, `greater_than_eq`.
+- Metrics (CLI): `avg`, `p90`, `p95`, `p99` (ms); `error_rate`, `failure_rate` (%); `rps`.
+- **Server-side (cloud) accepts a narrower set**: `responseTime.average/p90/p95/p99`, `throughput`, `errorRate`. `failure_rate` is local-only — if you emit it, note it won't gate a cloud run.
+- Only one condition per run. A JMeter Duration Assertion is the only clean source (→ `less_than(p95, <ms>)`); otherwise suggest `less_than(error_rate, 5)` and tell the user it's a default.
+
+## Scripts under load
+
+- Pre-request / test scripts run per VU per iteration via `postman-runtime`.
+- `postman.setNextRequest(...)` **is supported** — flow control within one VU's iteration works.
+- Vault access **in scripts** is disabled; per-request timeouts are forced to infinite; each VU gets its own cookie jar.
+- Known engine caveat: mutating `pm.request` inside a script can bleed across VUs. `pm.iterationData` / `pm.variables` are correctly isolated. Avoid importing JMeter logic into `pm.request` mutation.
+
+## Data
+
+- One `--data-file` (JSON array of objects, or CSV) per run. Multiple JMeter CSV Data Sets must be merged or a primary chosen.
+- Rows map to VUs/iterations; rows < VUs repeat. The CLI CSV parser is a naive comma split — **no quoted-field/escape support**, so JMeter CSVs with embedded commas/quotes need cleaning.
+
+## Hard limits to encode in every import
+
+1. One collection, repeated across VUs. **No concurrent thread groups.**
+2. Time-based, not iteration-based. **Loop counts → duration.**
+3. One `--pass-if`.
+4. **No think time** — timers are not reproduced; each one is reported.
+5. **HTTP(S) only.**

package/skills/performance-testing/references/jmeter-import/script-translation.md

@@ -0,0 +1,97 @@
+# Translating JSR223 / BeanShell scripts to Postman JavaScript
+
+Every JSR223/BeanShell script is translated by hand and treated as a manual task until it's checked. Wrap each translation in an IIFE (`(function () { ... })();`) so a leftover `return` stays legal.
+
+## Execution-context map
+
+JMeter runs these inside a sampler's processor. Postman runs them as a request's `prerequest` or `test` event. Equivalents:
+
+| JMeter (Groovy/BeanShell) | Postman JS | Context |
+|---|---|---|
+| `vars.get("x")` / `vars["x"]` | `pm.variables.get("x")` | both |
+| `vars.put("x", v)` | `pm.variables.set("x", v)` | both |
+| `props.get/put(...)` | `pm.variables.get/set(...)` (approx) | both |
+| `log.info/warn/error(...)` | `console.log/warn/error(...)` | both |
+| `prev.getResponseDataAsString()` | `pm.response.text()` | post only |
+| `prev.getResponseCode()` | `String(pm.response.code)` | post only |
+| `prev.getResponseMessage()` | `pm.response.status` | post only |
+| `prev.getTime()` | `pm.response.responseTime` | post only |
+| `ctx.getPreviousResult()` | `pm.response` | post only |
+| `sampler.getUrl()` | `pm.request.url.toString()` | pre only |
+| `sampler.addArgument(k,v)` | `pm.request.url.query.add({key:k,value:v})` or body edit | pre only |
+| `System.currentTimeMillis()` | `Date.now()` | both |
+| `UUID.randomUUID().toString()` | `require('uuid').v4()` | both |
+| `Integer.parseInt(x)` | `parseInt(x)` | both |
+
+## What doesn't map line by line
+
+- **BeanShell implicit result vars** (`ResponseCode`, `ResponseMessage`, `IsSuccess`, `bsh.args`, `Parameters`). No pm.* equivalent in a processor. For a sampler that sets `IsSuccess=false`, express it as a `pm.test(...)` that fails. For `return X`, delete the return (the IIFE makes it legal, but it's a no-op).
+- **Groovy closures / collection methods** (`.each {}`, `.collect {}`, `->`). Rewrite as `for...of` / `.map()` / arrow functions.
+- **`import` / `new ClassName()` / Java types** (`StringBuilder`, `SimpleDateFormat`, `JsonSlurper`). Replace with JS: string concat, `Date`, `JSON.parse`. `JsonSlurper().parseText(prev...)` → `pm.response.json()`.
+- **`try/catch`, multi-statement logic** — valid JS already; just verify semantics.
+- **GString interpolation** `"${x} and ${y}"` → template literal `` `${x} and ${y}` `` **only if** `x`/`y` are JS locals; if they are JMeter vars use `pm.variables.get`.
+
+## Procedure
+
+1. Read the original `<script>` text in the `.jmx` (note the element's name, so the report can point at it).
+2. Rewrite line by line using the table. Preserve variable names so `{{var}}` references elsewhere still resolve.
+3. Mark anything you're unsure of with a `// REVIEW` comment, and remove it once the logic is confirmed.
+4. Run the syntax check from `README.md` step 4.
+
+## Example
+
+JMeter (Groovy post-processor):
+```groovy
+import groovy.json.JsonSlurper
+def json = new JsonSlurper().parseText(prev.getResponseDataAsString())
+def token = json.data.token
+vars.put("authToken", token)
+log.info("got " + token)
+```
+Postman (test script):
+```javascript
+const json = pm.response.json();
+const token = json.data.token;
+pm.collectionVariables.set("authToken", token);
+console.log("got " + token);
+```
+
+## Canonical JS templates
+
+Emit exactly these so every import produces the same code. `<default>` empty-string if JMeter has none. Source is `pm.response.text()` normally, or `pm.response.headers.toString()` when the extractor's `useHeaders` is true.
+
+**Regex extractor** (`$n$` template → group `n`):
+```javascript
+try { var _m = String(pm.response.text()).match(new RegExp("<REGEX>")); pm.collectionVariables.set("<ref>", _m ? _m[<n>] : "<default>"); } catch (e) { pm.collectionVariables.set("<ref>", "<default>"); }
+```
+
+**Boundary extractor** (left/right → non-greedy capture):
+```javascript
+try { var _b = String(pm.response.text()).match(new RegExp("<lboundary>([\\s\\S]*?)<rboundary>")); pm.collectionVariables.set("<ref>", _b ? _b[1] : "<default>"); } catch (e) { pm.collectionVariables.set("<ref>", "<default>"); }
+```
+
+**JSON extractor** (`JSONPostProcessor` / plugin). Only **simple** paths (`$.a.b`, `$.a[0].c`) import; `$`/`$.` → `pm.response.json()`:
+```javascript
+try { pm.collectionVariables.set("<ref>", pm.response.json().a.b[0]); } catch (e) { pm.collectionVariables.set("<ref>", "<default>"); }
+```
+Wildcards / filters / recursive descent (`*`, `..`, `?`, `@`) → do NOT import; emit `// [manual] JSONPath "<expr>" too complex` and add a manual task.
+
+**Implicit HTTP success** (first test on every request unless a `response_code`/`response_message` assertion or `assume_success` exists):
+```javascript
+pm.test('JMeter default success (HTTP 200-399)', function () {
+    pm.expect(pm.response.code).to.be.within(200, 399);
+});
+```
+
+**Response Assertion** — decode `test_type` bits (`MATCH=1, CONTAINS=2, NOT=4, EQUALS=8, SUBSTRING=16, OR=32`). Field getter: `response_code`→`pm.response.code`, `response_message`→`pm.response.status`, `response_headers`→`pm.response.headers.toString()`, else `pm.response.text()`. For each test string `s`:
+- **EQUALS (8)** on `response_code`: `pm.expect(pm.response.code).to.eql(<s>)` (number). Other fields: `.to.eql("<s>")`.
+- **SUBSTRING (16)** → literal: `pm.expect(<getter>).to.include("<s>")`.
+- **CONTAINS (2) or MATCH (1)** → regex: `pm.expect(String(<getter>)).to.match(new RegExp("<s>"))`.
+- **NOT (4)** → insert `.not` before `.to`.
+Wrap each in `pm.test("<name>", function () { <expr>; });`.
+
+**Duration Assertion** → a test plus a perf `--pass-if` hint:
+```javascript
+pm.test("Response time < <ms>ms", function () { pm.expect(pm.response.responseTime).to.be.below(<ms>); });
+```
+and set the run's `--pass-if "less_than(p95, <ms>)"`.

package/skills/postman-mcp-server/SKILL.md

@@ -1,71 +1,65 @@
 ---
 name: postman-mcp-server
-description: Postman concepts and MCP tool guidance. Loaded when working with Postman MCP tools to make better decisions about tool selection and workarounds.
-user-invocable: false
+description: Use when working through Postman MCP tools to inspect or change workspace resources, choose a targeted operation, or handle MCP limitations. Supports hosted workflows when the CLI is unavailable and distinguishes tool completion from a usable result. Use for requests such as "use Postman MCP to inspect this collection".
 ---
 
-# Postman Knowledge
+# Postman MCP Server
 
-Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.
+MCP exposes workspace resources directly to an agent. Existing collections,
+specs, examples, and environments provide maintained API knowledge; fetching
+the relevant entity preserves that context when a local CLI workflow is not
+available. For repository edits and Git review, prefer the local workflows in
+**api-engineer** and **bootstrap** when available.
 
-See `references/setup.md` for how to to setup postman mcp server and auth.
+Each tool definition exposed to the model consumes context whenever it is
+included in a request. Prefer the smallest available toolset that covers the
+task; expanding to every tool can crowd out the API evidence needed to reason.
+When exposed, call `getEnabledTools` to inspect the active toolset before
+diagnosing a missing operation. Otherwise use the host's discovered tools and
+report that limitation. Do not infer availability from reference tool names or
+assume a client can switch a route pinned to a specific MCP endpoint.
 
-## Core Concepts
+1. Select tools from the connected server's actual surface. Tool availability
+   varies by mode; a name listed in a reference is not proof it is exposed.
+   Use [setup](references/setup.md) for connection/auth failures and
+   [limitations](references/mcp-limitations.md) when an operation is missing
+   or behaves differently from the CLI.
+2. Search to locate an entity, then fetch enough detail to work on it.
+   `searchPostmanElements` finds candidates; collection, spec, and workspace
+   detail tools establish IDs, ownership, and content. A search preview is
+   insufficient evidence for replacing a collection or declaring an API absent.
+3. Match the mutation to the intended scope. Request-level updates preserve
+   unrelated collection content; whole-collection replacement requires the
+   current complete object. A workspace is a container and access boundary,
+   not a reason to create duplicate resources whenever a new task begins.
+4. Preserve the source of truth when synchronizing. Spec-to-collection
+   generation reuses the interface, while collection-to-spec sync carries
+   changes in the other direction. Choose from the intended contract rather
+   than overwriting whichever artifact is easiest to reach. An asynchronous
+   acceptance response needs a completed task result before claiming sync.
+5. Treat publication separately from editing. A collection example can feed
+   docs and a classic mock, but neither becomes publicly accessible merely
+   because it exists. Apply the user's intended audience and authorization
+   before publishing docs or mocks, or changing shared resources.
 
-- **Collection:** A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples, tests, and documentation.
-- **Environment:** Key-value pairs (variables) scoped to a context (dev, staging, prod). Used to swap base URLs, auth tokens, and config without changing requests.
-- **Workspace:** Container for collections, environments, and specs. Can be personal, team, or public.
-- **Spec (Spec Hub):** An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections and stay synced.
-- **Request:** A single API call definition (method, URL, headers, body, tests).
-- **Response:** A saved example response for a request. Used by mock servers and documentation.
-- **Folder:** A grouping within a collection, typically by resource (e.g., "Users", "Orders").
-- **Tags:** Labels on collections for categorization and search.
-- **Monitor:** A scheduled collection runner that checks API health.
-- **Mock Server:** A fake API that serves example responses from a collection.
+Read the reference for the branch being used:
 
-## Decision Guide
+| Task | Reference and decision it supports |
+| --- | --- |
+| Locate an API | [Search](references/search.md): narrow candidates to the intended resource |
+| Generate or synchronize artifacts | [Sync](references/sync.md): choose source and track completion |
+| Serve saved examples | [Mock](references/mock.md): classic collection mocks; for CLI Code Mocks use **api-mocking** |
+| Execute saved assertions | [Test](references/test.md): distinguish run completion from failures |
+| Improve or publish docs | [Docs](references/docs.md): fill contract gaps and verify reader access |
+| Requested security review | [Security](references/security.md): assess concrete API risks |
+| Product how-to questions | [Learning Center](references/learn.md): product documentation search when exposed |
 
-| Goal | Approach |
-|------|----------|
-| Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection |
-| Consume a Postman API | Read collection + generate client code |
-| Find an API | Use `searchPostmanElements`, then drill into details |
-| Test an API | Run collection with `runCollection` |
-| Create a fake API for frontend | Create mock server from collection with examples |
-| Document an API | Analyze collection completeness, fill gaps, optionally publish |
-| Audit API security | Run security checks against spec or collection |
-| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) |
+## Verification
 
-## MCP Tool Selection
+State the active toolset as observed through `getEnabledTools`, or identify the
+host discovery evidence used when that tool is unavailable. Report any operation
+the connected surface could not perform instead of claiming it succeeded.
 
-**Workspace operations:** `getWorkspaces`, `getWorkspace`, `createWorkspace`
-**Collection CRUD:** `getCollections`, `getCollection`, `createCollection`, `putCollection`, `patchCollection`, `deleteCollection`
-**Request/Response:** `getCollectionRequest`, `createCollectionRequest`, `updateCollectionRequest`, `getCollectionResponse`, `createCollectionResponse`, `updateCollectionResponse`
-**Folder management:** `getCollectionFolder`, `createCollectionFolder`, `updateCollectionFolder`
-**Spec Hub:** `getAllSpecs`, `getSpec`, `createSpec`, `getSpecDefinition`, `updateSpecFile`, `getSpecFiles`
-**Sync:** `generateCollection`, `syncCollectionWithSpec`, `syncSpecWithCollection`
-**Environments:** `getEnvironments`, `getEnvironment`, `createEnvironment`, `putEnvironment`
-**Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock`
-**Tests:** `runCollection`
-**Docs:** `publishDocumentation`, `unpublishDocumentation`
-**Search:** `searchPostmanElements` , `getTaggedEntities`
-**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance)
-**User:** `getAuthenticatedUser`
-
-See `references/mcp-limitations.md` for known limitations and workarounds.
-
-## Workflows
-
-Each reference below is a full MCP-tool workflow for one goal — the tool
-call sequence, what to present at each step, and error handling. Reach for
-one once the Decision Guide above has picked a goal; they assume MCP tools
-only, no `postman` CLI.
-
-- `references/setup.md` — first-run auth (OAuth or API key) and workspace verification.
-- `references/search.md` — discover APIs across workspaces with `searchPostmanElements`.
-- `references/sync.md` — create/update collections from specs, or sync a spec from collection changes.
-- `references/mock.md` — create a mock server from a collection or spec.
-- `references/test.md` — run collection tests and diagnose failures.
-- `references/docs.md` — generate, improve, and publish API documentation.
-- `references/security.md` — audit a spec or collection against the OWASP API Top 10.
-- `references/learn.md` — search the Postman Learning Center for how-to guidance.
+Report the resource and observed result: assertions for a run, completed sync
+for a generated artifact, or the reachable URL and visibility for publication.
+Tool success alone does not establish any of those outcomes.

package/skills/postman-mcp-server/references/docs.md

@@ -1,6 +1,5 @@
 ---
 description: Generate, improve, and publish API documentation from Postman collections.
-allowed-tools: Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__updateCollectionRequest, mcp__postman__publishDocumentation, mcp__postman__unpublishDocumentation, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks
 ---
 
 # API Documentation

package/skills/postman-mcp-server/references/learn.md

@@ -1,6 +1,5 @@
 ---
 description: Search the Postman Learning Center for how-to guidance, feature explanations, and suggested workflows. Use for "how do I..." questions about the Postman product.
-allowed-tools: Read, mcp__postman__searchLearningCenter, mcp__postman__getEnabledTools
 ---
 
 # Learn Postman
@@ -11,14 +10,16 @@ Use this to learn *about Postman itself* — not to search the user's own collec
 
 ## Prerequisites
 
-This workflow uses `searchLearningCenter`, which the Postman MCP Server exposes only in **Full mode**.
+Use `searchLearningCenter` when it is exposed by the connected server. Follow
+**postman-mcp-server**'s toolset inspection guidance before diagnosing a missing
+tool; a remembered mode-to-tool mapping is not evidence of current availability.
+The route's MCP endpoint determines its configured surface. `POSTMAN_MCP_MODE`
+is not read by this plugin's routes and cannot switch that surface.
 
-The mode is fixed by the endpoint in each route's MCP config, not by the environment. A route pinned to `https://mcp.postman.com/mcp` has the tool; a route pinned to `https://mcp.postman.com/minimal` does not. Read it off the route's own MCP config rather than inferring it from the agent's name — which endpoint an agent gets is a per-route product decision, and new routes are added. **`POSTMAN_MCP_MODE` is not read on any route** — never tell the user to set or unset it to change the tool set.
-
-- If MCP tools aren't available at all, follow `references/setup.md` to connect the Postman MCP Server.
-- If `searchLearningCenter` is missing, call `getEnabledTools` to confirm the active tool set, then split on which endpoint the route is pinned to. On a `/minimal` route it is absent by design and the user cannot change it from the client: say the Learning Center tool isn't part of that route's tool set and point them at https://learning.postman.com to search directly. On a `/mcp` route its absence is not a mode problem — the server isn't connected as configured: follow `references/setup.md` to reconnect it.
-
-Do not answer a "how do I..." question from memory when the tool is unavailable. Cite only URLs the tool returned, or send the user to the Learning Center.
+If no MCP tools are available, follow `references/setup.md`. If only the learning
+tool is absent, use an available web search/browser to read the official Learning
+Center and cite the pages actually consulted. Without either capability, report
+the limitation and link the Learning Center rather than inventing product steps.
 
 ## Workflow
 
@@ -68,6 +69,6 @@ To create a mock server in Postman:
 ## Error Handling
 
 - **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
-- **`searchLearningCenter` unavailable:** Confirm with `getEnabledTools`. Expected on any route pinned to the `minimal` endpoint — say the tool isn't in that route's tool set and point the user at https://learning.postman.com. On a `/mcp` route: follow `references/setup.md` to reconnect it.
+- **`searchLearningCenter` unavailable:** Use the toolset inspection and official-documentation fallback under Prerequisites.
 - **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **No results:** "Nothing matched in the Learning Center. Try rephrasing with the Postman feature name, or ask about a more specific step."

package/skills/postman-mcp-server/references/mock.md

@@ -1,6 +1,5 @@
 ---
 description: Create Postman mock servers for frontend development. Generates missing examples, provides integration config.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__createCollectionResponse, mcp__postman__createSpec, mcp__postman__generateCollection, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__getSpecCollections, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getMocks, mcp__postman__getMock, mcp__postman__createMock, mcp__postman__publishMock, mcp__postman__unpublishMock
 ---
 
 # Create Mock Servers

package/skills/postman-mcp-server/references/search.md

@@ -1,6 +1,5 @@
 ---
 description: Discover APIs across your Postman workspaces. Ask natural language questions about available endpoints and capabilities.
-allowed-tools: Read, Glob, Grep, mcp__postman__searchPostmanElements, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getTaggedEntities, mcp__postman__getCollection, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__getSpecDefinition
 ---
 
 # Discover APIs

package/skills/postman-mcp-server/references/security.md

@@ -1,6 +1,5 @@
 ---
 description: Security audit your APIs against OWASP API Top 10. Finds vulnerabilities and provides remediation guidance.
-allowed-tools: Read, Edit, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getAllSpecs, mcp__postman__getSpecDefinition, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__getEnvironment, mcp__postman__putEnvironment, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
 ---
 
 # API Security Audit

package/skills/postman-mcp-server/references/setup.md

@@ -1,6 +1,5 @@
 ---
 description: Set up Postman MCP Server. Authenticate via OAuth or API key, verify connection, select workspace.
-allowed-tools: mcp__postman__authenticate, mcp__postman__complete_authentication, mcp__postman__getAuthenticatedUser, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getAllSpecs
 ---
 
 # First-Run Configuration

package/skills/postman-mcp-server/references/sync.md

@@ -1,6 +1,5 @@
 ---
 description: Sync Postman collections with your API code. Create collections from specs, push updates, keep everything in sync.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__createSpec, mcp__postman__updateSpecFile, mcp__postman__generateCollection, mcp__postman__getAsyncSpecTaskStatus, mcp__postman__getGeneratedCollectionSpecs, mcp__postman__syncCollectionWithSpec, mcp__postman__syncSpecWithCollection, mcp__postman__getCollectionUpdatesTasks, mcp__postman__createEnvironment, mcp__postman__createCollectionRequest, mcp__postman__updateCollectionRequest, mcp__postman__createCollectionFolder, mcp__postman__createCollectionResponse
 ---
 
 # Sync Collections

package/skills/postman-mcp-server/references/test.md

@@ -1,6 +1,5 @@
 ---
 description: Run Postman collection tests, analyze results, diagnose failures, and suggest fixes.
-allowed-tools: Bash, Read, Write, Glob, Grep, mcp__postman__getWorkspaces, mcp__postman__getCollections, mcp__postman__getCollection, mcp__postman__runCollection, mcp__postman__getEnvironments, mcp__postman__getCollectionRequest, mcp__postman__getCollectionResponse, mcp__postman__updateCollectionRequest, mcp__postman__updateCollectionResponse
 ---
 
 # Run Collection Tests

package/skills/variables/SKILL.md

@@ -1,106 +1,63 @@
 ---
 name: variables
-description: How to parameterize a collection with variables and where each value belongs — a plain value goes in an environment or collection variable, a secret (token, password, API key) goes in the team's shared vault via `postman secret create` so its value never passes through the coding harness or lands in a committed file. Covers the variable scopes and their resolution order, reading and writing variables at runtime from pre-request and post-response scripts (`pm.environment`, `pm.collectionVariables`, `pm.variables`), and composing variables out of other variables. Use when the user asks where to put a base URL, token, or password, how to reference a secret without exposing it, how `{{variables}}` resolve, or how to set a value in a script. Covers `postman secret`.
+description: Use when parameterizing requests across environments, choosing variable scopes, chaining values in scripts, or referencing credentials without committing or exposing them. Keeps one reusable collection while separating target configuration from secret values. Use for requests such as "where should I put this API key".
 ---
 
 # Variables
 
-A variable lets a request name a value — `{{base_url}}`, `{{authToken}}` —
-instead of hardcoding it, so one collection runs against staging and
-production and a secret never has to be typed into a request. The only real
-decision is **where the value lives**, and it turns on one question: is it a
-secret?
+Variables let one maintained collection run against different targets without
+forking its requests. Scope determines which value wins; secret references
+allow the same files to be shared without sharing credential values.
+
+1. Put API defaults in collection variables and target-specific values, such
+   as `base_url`, in an environment. Parameterize values that actually vary;
+   a stable literal need not become another configuration choice. Reference
+   values as `{{key}}` in URLs, headers, parameters, or bodies.
+2. Resolve surprises through precedence: local script values override
+   iteration data, then environment, collection, and global values. A correct
+   environment file can still lose to a row or script override. Values can
+   reference other variables and resolve at send time, so inspect the chain
+   rather than just the final request field.
+3. Use runtime values for chaining responses into later requests. Choose
+   `pm.environment` or `pm.collectionVariables` when the scope is intentional;
+   `pm.variables.get` reads across scopes, and `pm.variables.set` holds a local
+   value for the current run. For transient sensitive values, avoid persisting
+   them to an environment or logging them.
+4. Store durable credentials in the shared vault and commit references.
+   `type: secret` alone masks the UI but still leaves a literal YAML value
+   readable. **collection-schema-v3**'s environment reference describes the
+   file schema; command-specific `-h` supplies supported vault operations.
+
+For non-sensitive target configuration:
 
-## Core foundations
-1. One collection, many targets. Parameterize everything that changes between
-   environments so the same requests run everywhere — a diff in values, not in
-   requests.
-2. Where a value lives is a security decision, not a convenience one. A plain
-   value is a variable; a secret belongs in the vault, nowhere else.
-3. A secret's value should never reach this harness, the terminal, or a
-   committed file. `type: secret` only hides it in the UI — the value still
-   sits in clear text in the YAML. The vault is the only place it stays out of
-   the repo. (ref: postman secret command) 
-4. Resolution is narrowest-wins: `local (script) > data (iteration row) >
-   environment > collection > global`. This is what lets a collection ship a
-   default and an environment override just the few that differ.
-5. Variables compose. A value can reference another (`usersUrl =
-   {{base_url}}/users`), and a script can set one at runtime to chain requests
-   (capture a token, use it on the next call). Resolution happens at send
-   time, not at definition time.
-
-## Non-secret variables
-
-A base URL, a non-sensitive id, a feature flag, a default page size — store it
-as a variable and commit it. Reference it as `{{key}}` in a URL, header, query
-param, or body. Scope picks the file:
-
-- **Collection variable** — travels with the collection; use it for a default
-  that belongs to the API itself and rarely changes.
-- **Environment variable** — swapped per target; use it for anything that
-  differs between staging and production. One file per environment, selected
-  at run time.
-
-
-You can either directly edit into collection / environment file or use the cli commands to achieve the same.
 ```bash
 postman environment new "Staging"
 postman environment var set base_url https://staging.example.com \
   --environment "postman/environments/Staging.environment.yaml"
-postman environment lint postman/environments --fail-severity warning
 ```
 
-Set one at runtime from a script when you need to chain requests:
-
-```javascript
-// post-response: capture for later requests
-pm.environment.set("authToken", pm.response.json().access_token);
-// pre-request: read it back (any scope, resolution order applies)
-const base = pm.variables.get("base_url");
-```
-
-Use `pm.environment`/`pm.collectionVariables` to target a scope, `pm.variables`
-to read across all of them, and `pm.variables.set` for a local value that
-lives only for the current run.
-
-## Secret keys
-
-Passport is how people, services, and agents call APIs without ever holding
-the secret. `postman secret` is the vault side of the same idea: it stores and
-links secrets without putting their values in agent context or repository
-files. Run `postman secret -h` for the supported vault operations and flags.
-
-A bearer token, password, API key, client secret, or signing key goes in the
-team's **shared vault**:
-
-```bash
-# interactive masked prompt (default when stdin is a terminal)
-postman secret create STRIPE_API_KEY --workspace <workspaceId>
-```
-By default only the creator of secret can view the secret. Others in workspace can resolve the secret in their runs but can not see the secret value.
-
-You then link the secret to an environment variable to use it in a request —
-the CLI writes the link for you from `secret create`'s output:
+For a secret, have the user supply the value through the CLI's masked prompt,
+not through agent context or a literal command argument:
 
 ```bash
+postman secret create STRIPE_API_KEY --workspace <workspace-id>
 postman environment var set api_key --secret-id <secret-id> --vault-id <vault-id> \
   --environment "postman/environments/Staging.environment.yaml"
 ```
 
-The variable now points at the vault instead of holding a value; the file
-carries only the reference, never the secret:
-
-```yaml
-values:
-  - key: api_key
-    enabled: true
-    type: secret
-    description: API key
-    secret: true
-    source:
-      provider: postman
-      postman:
-        type: cloud
-        secretId: <secret-id>
-        vaultId: <vault-id>
-```
+The environment then carries the vault/secret IDs rather than the value.
+Secret resolution and permission to view the secret are distinct; a teammate's
+ability to run a request need not expose the credential to them. Use
+**bootstrap** when the vault operation needs unresolved authentication.
+
+## Verification
+
+Run `postman environment lint <path> --fail-severity warning` to fail on
+warnings as well as errors in the saved environment. Lint checks the artifact;
+it does not prove that the session can resolve a vault secret. Verify resolution
+with an appropriate authenticated request and a contract-derived assertion,
+keeping credentials out of output. An unresolved-reference or authorization
+failure needs investigation, not a claim that the secret worked.
+Report the selected environment and scope
+or reference that supplies the value; a masked display alone does not prove
+that the committed file contains no literal secret.