@postman/postman-plugin 0.5.1 → 0.6.0

package/skills/performance-testing/references/gatling-import/injection.md

@@ -0,0 +1,88 @@
+# Load model: injection, throttle, duration, assertions → `postman performance run`
+
+## What Postman supports (verify against the installed `postman performance run --help`; don't assume a version)
+- **Closed model only.** `--vu-count N` virtual users each loop the collection until the run ends. There's no arrival rate and no target RPS.
+- `--load-profile`: `fixed` (N the whole time), `ramp-up` (grows to N), `spike` (a burst to N), `peak` (rises to N, holds, falls). Each has a fixed shape; you can't set stage times from the CLI.
+- `--duration` in whole minutes (≥ 1). `--pass-if` takes **one** condition: `less_than|greater_than|less_than_eq|greater_than_eq(avg|p90|p95|p99|error_rate|rps, value)`. `error_rate` is a percentage.
+- Cloud runs need `--vu-count` ≥ 10. For local runs, any value ≥ 1 works.
+
+## Injection (`inj:*`)
+**Closed steps: exact or near-exact.**
+| Gatling | Flags | Status |
+|---|---|---|
+| `constantConcurrentUsers(n).during(d)` alone | `--vu-count n --load-profile fixed --duration ceil(d)` | mapped (approximated if d isn't whole minutes: say "rounded up") |
+| `rampConcurrentUsers(a).to(b).during(d)`, then `constantConcurrentUsers(b).during(h)` | `--vu-count b --load-profile ramp-up --duration ceil(d+h)` | approximated: the ramp/hold ratio is fixed by the profile |
+| `rampConcurrentUsers(a).to(b)` alone | `--load-profile ramp-up` | approximated |
+| `incrementConcurrentUsers` (steps) | `ramp-up` to the final level | approximated: no stairs |
+
+**Open steps: always approximated.** Gatling open users run the journey **once** and leave. Postman VUs loop. To keep the same load on the server, match the concurrency using Little's law:
+
+> **VUs ≈ arrival rate (users/s) × journey time (s)**
+
+- **Know whether the injector's number is a count or a rate — this is the most common mistake.** `constantUsersPerSec(r)` and `rampUsersPerSec(a).to(b)` are **rates** (users **per second**) — use them directly. `rampUsers(n).during(d)` and `atOnceUsers(n)` are a **total count** of users, not a rate: `rampUsers(50).during(60s)` is 50 users spread over 60 s = an arrival rate of `50/60 ≈ 0.83 users/s`, **not** 50/s. Convert a count to a rate (`n/d`) *before* Little's law. Skipping this step inflates `--vu-count` by the factor `d`.
+- **Journey time** = the sum of pauses (use the mean for ranges, e.g. `pause(1,3)` → 2 s) + the expected response times. Use `0.3 s` per request if unknown, and say so — **but** if a path makes the latency evident (e.g. `/delay/1` ≈ 1 s, a Gatling request literally named "slow …"), use that value instead and note it. Pick one rule per conversion and state it, so two runs don't diverge.
+- **Cloud VU floor.** If the computed `--vu-count` is below 10 and the user will run on **cloud**, keep the computed value but add a one-line note that cloud requires ≥ 10 (so they raise it deliberately, knowing it increases load). For **local** runs any value ≥ 1 is fine. Never silently inflate the count to clear the floor.
+- **`pace(d)` is a floor, not an addend.** `pace` forces each iteration to take *at least* `d`; it does **not** add to the request/pause time, it subsumes it. So when a scenario has `pace(d)`, the journey time is `J = max(d, pauses + response times)`, **not** `pauses + response times + d`. Adding `pace` as a term overstates `J` and inflates `--vu-count`. Show the `max(...)` in MIGRATION.md.
+- **A loop inside the per-user journey changes what `J` is.** If the open-model journey wraps a `during(t) { … }` / `forever { … }` loop (often with `pace`), each arriving user stays busy for the **whole loop duration**, so `J` is that duration, not one pass. Example: `constantUsersPerSec(20)` over a journey of `during(5.minutes){ pace(5s).exec(...) }` → `J = 300 s`, so `VUs ≈ 20 × 300 = 6000`, not `20 × (one 5 s iteration)`. This is usually a very large number — **do not silently pick the one-iteration reading**; compute both, put the arithmetic and the chosen reading in MIGRATION.md → Load model, and tell the user to confirm, because it swings `--vu-count` by orders of magnitude. A finite closed cap (`maxDuration`, cloud VU limits) may force you lower; say so.
+- Round up to `--vu-count` ≥ 1. **Do not bump a sub-10 result up to 10 for cloud here** — the **Cloud VU floor** rule above governs that: keep the computed value and warn the user cloud needs ≥ 10, so load is never silently increased without their decision.
+
+| Gatling | Flags |
+|---|---|
+| `constantUsersPerSec(r).during(d)` | `--vu-count ceil(r × J) --load-profile fixed --duration ceil(d)` |
+| `rampUsersPerSec(a).to(b).during(d)` (then `constantUsersPerSec(b)…`) | `--vu-count ceil(b × J) --load-profile ramp-up`, with duration the sum of all steps |
+| `atOnceUsers(n)` | a burst: `--load-profile spike --vu-count n` if it's the main (only sustained) step. **When it coexists with a ramp/constant step, the sustained step is the dominant shape** — use that profile and its Little's-law VU count; fold the burst in as the initial spike and note it. Only when the burst's `n` exceeds the sustained VU count does it set the peak (use the larger, and say so) |
+| `rampUsers(n).during(d)` | **`n` is a total count, not a rate.** `n` users arrive evenly over `d`, so first convert to a rate `n/d` users/s, then `--vu-count ceil((n/d) × J)`, ramp-up. E.g. `rampUsers(50).during(60s)` → `50/60 ≈ 0.83/s`, **not** 50/s |
+| `stressPeakUsers(n).during(d)` | `--load-profile peak --vu-count ceil(peak rate × J)` |
+| `nothingFor(d)` | none. Add d to the explanation. Gap if it's the only step, otherwise approximated |
+| `.randomized()` | none: gap (arrivals aren't randomised) |
+
+When the chain has several steps, choose **one** profile for the dominant shape and put every step with its arithmetic in MIGRATION.md → Load model. Also write what the user should watch for: "Gatling measured N users arriving per second; Postman keeps V users busy. Compare throughput (rps) with your Gatling report rather than user counts."
+
+Example (show your working like this):
+```
+Source: rampUsersPerSec(1).to(10).during(60s), then constantUsersPerSec(10).during(120s)
+Journey: 2 requests × 0.3 s (assumed) + pause(1,2) mean 1.5 s = 2.1 s
+Peak VUs: 10 users/s × 2.1 s = 21 → --vu-count 21
+Duration: 60 + 120 = 180 s = 3 min → --duration 3
+Profile: ramp-up (one ramp then a hold; the ramp/hold split is fixed by the profile, not 1:2)
+```
+
+Count-based injectors — convert the count to a rate FIRST (this is the step that most often goes wrong):
+```
+Source: atOnceUsers(5), then rampUsers(50).during(60s)
+Rate:    rampUsers(50).during(60s) = 50 users over 60 s = 50/60 ≈ 0.83 users/s   ← NOT 50/s
+Journey: 3 requests × 0.3 s (assumed) + pause 0.5 s × 3 + /delay/1 ≈ 1 s = ~3.7 s
+Sustained VUs: 0.83 users/s × 3.7 s ≈ 3.08 → 4
+Burst:   atOnceUsers(5) = 5 users at once; 5 > 4, so the burst sets the peak → --vu-count 5
+Duration: 60 s = 1 min → --duration 1 ; Profile: ramp-up
+```
+(Reading `rampUsers(50)` as 50 users/s here would give `50 × 3.7 ≈ 185` VUs — ~40× too high.)
+
+## Throttle (`throttle:*`) and max duration
+- `throttle(reachRps(r).in(t), holdFor(h))`: there's no RPS cap. **Gap**, and say that Postman won't hold throughput at r. The user can lower `--vu-count` to get near it.
+- `maxDuration(d)`: `--duration` is already a hard stop. Mapped to `run:--duration` if d ≥ the computed duration. Otherwise use d, and approximate.
+
+## Assertions (`assert:*`)
+The CLI takes **at most one** `--pass-if`. Pick it by this **strict priority — this overrides the order the assertions appear in the source**:
+1. a global error-rate assertion (`failedRequests`/`successfulRequests` → `error_rate`)
+2. a global latency percentile (`p95`, then `p99`, then `p90`)
+3. a global `mean` (`avg`) or `requestsPerSec` (`rps`)
+
+Walk the list top-down and take the **first category that a source assertion matches**, even if a different assertion came first in the source. Example: a simulation with `responseTime().percentile(95).lt(800)` **and** `failedRequests().percent().lt(1)` → the `--pass-if` is `less_than(error_rate, 1)` (category 1 wins), and the p95 assertion is the **gap**, not the other way round.
+
+All non-chosen assertions are **gap**, reason "the CLI takes one pass condition". Suggest adding them as run criteria in the app, where several aggregate checks are allowed.
+
+**If no source assertion matches any category** (e.g. only `forAll`/`details(...)` per-request assertions, or only `responseTime().max()` which has no CLI metric), emit **no `--pass-if` flag at all** — this is correct and expected, not a defect. Record every assertion as a gap and tell the user to add run criteria in the app. A `run.sh` with zero `--pass-if` is valid.
+| Gatling | `--pass-if` | Notes |
+|---|---|---|
+| `global().failedRequests().percent().lt(x)` | `less_than(error_rate, x)` | approximated (see error-rate note below) |
+| `global().failedRequests().count().is(0)` | `less_than_eq(error_rate, 0)` | approximated (percentage instead of count; + error-rate note) |
+| `global().successfulRequests().percent().gt(x)` | `less_than(error_rate, 100 - x)` | approximated (see error-rate note below) |
+| `global().responseTime().percentile(95).lt(ms)` (Scala `percentile3`) | `less_than(p95, ms)` | mapped (also p90, p99. Other percentiles → the nearest, approximated) |
+| `global().responseTime().mean().lt(ms)` | `less_than(avg, ms)` | mapped |
+| `global().responseTime().max()` / `min()` / `stdDev()` | none | gap |
+| `global().requestsPerSec().gt(r)` | `greater_than(rps, r)` | mapped |
+| `forAll…` / `details("group", "req")…` | none (no per-request criteria) | gap |
+| `lte` / `gte` | `less_than_eq` / `greater_than_eq` | — |
+
+**Error-rate note (why failed/successful-request mappings are approximated).** Gatling's `failedRequests` counts a request as failed when a **check** fails, even on an HTTP 200. Postman's `error_rate` counts transport/runtime errors and may **not** count a request that returned a response but failed a translated `pm.test` (behaviour differs by runner). So a batch of 200s that all fail a JSON check would fail Gatling's gate but can **pass** `less_than(error_rate, …)`. Map `failedRequests`/`successfulRequests` → `error_rate` as **approximated**, say so in MIGRATION.md, and note it's a weaker gate than Gatling's (plus any hosted-runner limitation). If the failure the user cares about is a check, a latency percentile or `rps` criterion may be the more faithful gate.

package/skills/performance-testing/references/gatling-import/mapping.md

@@ -0,0 +1,91 @@
+# Mapping: requests, EL, checks, protocol, flow, custom code
+
+## Protocol settings (`proto:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `.baseUrl("https://h")` | collection variable `baseUrl`; requests use `{{baseUrl}}/…` | mapped |
+| `.baseUrls(a, b)` | first one as `baseUrl`; note the round-robin | approximated |
+| `.header(k, v)`, `.headers(map)` | header on every request (or collection pre-request `pm.request.headers.upsert`) | mapped |
+| `.acceptHeader`, `.contentTypeHeader`, `.userAgentHeader`, `.authorizationHeader` … | the matching header on every request | mapped |
+| `.basicAuth(u, p)` | collection auth `basic`, with `{{user}}` / `{{password}}` from the environment | mapped |
+| `.shareConnections()` | none. The runtime manages connections | gap (no-op; performance may differ) |
+| `.enableHttp2()` | none. HTTP/1.1 only | gap |
+| `.inferHtmlResources()` | none. Embedded resources are not fetched | gap |
+| `.disableCaching()`, `.disableFollowRedirect()`, `.maxConnectionsPerHost()` | none, or the request setting `followRedirects: false` | gap / mapped for redirects |
+| `.warmUp(url)` | none | gap |
+
+If a header value is a secret (an inventory `secret` item, or a name like `x-api-key` or `authorization` with a literal), use `{{<camelCaseName>}}` and add an empty environment key.
+
+## Requests (`req:*`)
+- Name: keep the `http("…")` name exactly.
+- Method and path: `.get("/p")` → `GET {{baseUrl}}/p`. An absolute URL stays absolute.
+- `.queryParam(k, v)` → a URL query param. `.formParam(k, v)` → `body.mode: urlencoded`. `.body(StringBody("…")).asJson()` → `body.mode: raw`, `options.raw.language: json`, plus header `Content-Type: application/json`.
+- `.header(k, v)` on a request → that request's header.
+- `ElFileBody("x.json")` / `RawFileBody` → inline the file contents into the raw body (translate EL inside it).
+
+## EL → Postman variables
+| Gatling EL | Postman |
+|---|---|
+| `#{name}` | `{{name}}` |
+| `#{randomUuid()}` | `{{$guid}}` |
+| `#{randomInt()}` / `#{randomInt(a,b)}` | `{{$randomInt}}` (0–1000, approximated), or a pre-request script for a range |
+| `#{randomLong()}` | a pre-request script, stored in a variable |
+| `#{currentTimeMillis()}` | `{{$timestamp}}` is seconds, so use a pre-request script: `pm.variables.set('now', Date.now())` |
+| `#{name.size()}`, `#{name(0)}`, `#{name.random()}` | a pre-request script over the parsed variable |
+| `#{name.jsonStringify()}` | a pre-request script `JSON.stringify(...)` |
+| `#{i}` from `repeat(n, "i")` | see Flow → loops |
+
+Every `{{var}}` must be defined somewhere: the environment, collection variables, a data-file column, or set by an earlier script. The self-verify step checks this.
+
+## Checks (`check:*`) → test script
+Put the checks in the request's `test` event, in source order. Name each `pm.test` after what it asserts.
+| Gatling | Test script |
+|---|---|
+| `status().is(200)` (Kotlin: `shouldBe`) | `pm.test('status is 200', () => pm.response.to.have.status(200));` |
+| `status().in(200, 204)` | `pm.expect([200,204]).to.include(pm.response.code)` |
+| `jsonPath("$.a.b").is("x")` | `pm.expect(pm.response.json().a.b).to.eql('x')`. Gatling compares as a string unless `ofInt()` etc. is used, so compare `String(v)` when the source is a string literal |
+| `jsonPath(...).isEL("#{v}")` | compare with `pm.variables.get('v')` (see **Saved variables scope**: read with `pm.variables.get`, write with `pm.collectionVariables.set`) |
+| `jsonPath(...).exists()` / `.notExists()` | `pm.expect(value).to.not.be.undefined` / `.to.be.undefined` |
+| `jsonPath(...).saveAs("v")` | `pm.collectionVariables.set('v', value)`, and also a `pm.test` that the value exists. **approximated**: Gatling marks the request failed on a missing extraction but, by default, **continues** the scenario — so do **not** add `pm.execution.setNextRequest(null)` here; that would skip the rest of the iteration even though the source doesn't. Stop early only when the source wraps this in `exitHereIfFailed`/`exitBlockOnFail` (see Flow control); if a later request needs to know the extraction failed, track that in a variable. Manifest target: the request's test script (`collection:<req> › test: saveAs v`), **not** `collection-variable:` — the value is script-set, not a declared collection variable |
+| `jmesPath("a.b")` | same as jsonPath, using a JS property path |
+| `regex("p").saveAs("v")` | `const m = pm.response.text().match(/p/); pm.test(..., () => pm.expect(m).to.not.be.null); pm.collectionVariables.set('v', m && m[1] !== undefined ? m[1] : m && m[0])`. Gatling saves group 1 if there is one, otherwise the whole match |
+| `header("h").is(v)` | `pm.expect(pm.response.headers.get('h')).to.eql(v)` |
+| `bodyString().is/contains` | `pm.response.text()` |
+| `substring("s")` | `pm.expect(pm.response.text()).to.include('s')` |
+| `responseTimeInMillis().lt(n)` | `pm.expect(pm.response.responseTime).to.be.below(n)` |
+| `css(...)` / `xpath(...)` | cheerio (`require('cheerio')`) for CSS if the selector is simple. XPath → gap |
+| `checkIf(cond)` | wrap the assertion in an `if` that translates the condition. Approximated if the condition is custom code |
+
+**Implicit status check (`implicit-status:*`).** When a Gatling request declares no `status()` check, Gatling still fails it unless the status is 2xx or 304. Add `pm.test('status is 2xx/304 (Gatling implicit check)', () => pm.expect(pm.response.code === 304 || (pm.response.code >= 200 && pm.response.code < 300)).to.be.true);`. Status: mapped.
+
+**Saved variables scope.** For correlation, **write** with `pm.collectionVariables.set('v', value)` and **read** with `pm.variables.get('v')` (the general resolver sees collection scope, so the two are consistent — don't mix `pm.collectionVariables.get` and `pm.variables.get` for the same value). In a performance run each virtual user has its own variable scope, which matches Gatling's per-user `Session`. A value saved this way is set by a script at run time, so it is **not** a declared collection variable — in the MIGRATION.md coverage table a `saveAs` lands on the request's test script, not a `collection-variable`.
+
+**Name collisions with feeder columns.** Data-file (`iterationData`) values outrank collection variables when `{{x}}` / `pm.variables.get('x')` resolves (see `postman:variables`). So if a `saveAs`/session key has the **same name as a feeder column**, `pm.collectionVariables.set('x', …)` will **not** override it — `{{x}}` still resolves to the feeder's value, unlike Gatling where the later session write wins. When a saved key collides with a feeder column, **rename** the saved key (or the column) and use the renamed key consistently across the extraction, any custom-code translation, and the request substitutions; note the rename in MIGRATION.md.
+
+## Scenario, groups (`scenario:*`, `group:*`)
+- Scenario → the collection itself (name the collection after it). If `setUp` has several scenarios, convert the main one and list the others as a gap: one collection per run.
+- `group("g")` → a folder named `g` containing the requests in the group. Status: approximated. Postman reports per-request metrics, and there's no folder-level (transaction) timing. Say so.
+
+## Flow control (`flow:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `exec` chain (sequential) | request order in the collection | mapped |
+| `repeat(n) { … }` / `repeat(n, "i")` | Use **one** request with a `setNextRequest` loop + a counter collection variable, so the single leaf runs n times. **Never unroll into n copies that share the same name**: a Postman collection can't hold two request leaves with the same path — so the "copies named `name`" shortcut is invalid. The loop also keeps the metric name identical (which is what unrolling was for). Only unroll if the body genuinely differs per iteration, and then give each copy a **distinct** name and note in MIGRATION.md that per-iteration metrics are split across those names. For `repeat(n, "i")`, set the counter as `{{i}}` in the loop script. **When the body is a chain of several requests** (`repeat(3){ A; B }`), loop the **whole body**, not one leaf: keep A and B as distinct requests and have the body's **last** request jump back to the **first** (`pm.execution.setNextRequest('A')`) while the counter < n, initialising/resetting the counter on first entry — so the order is A,B,A,B,A,B. A single-leaf loop only models a single-request body | approximated (explain the loop/metrics effect) |
+| `during(d) { … }` / `forever { … }` wrapping the main journey | The VU loop itself: a VU repeats the collection until the run ends | approximated (Gatling users in open models start and stop. Here VUs loop) |
+| `asLongAs(cond)`, `doWhile` | `setNextRequest` loop with a condition in the test script | approximated |
+| `doIf(cond) { r }` | in the pre-request of `r`: `if (!cond) pm.execution.skipRequest()`. The condition is translated to JS (session attribute → `pm.variables.get`) | **mapped** if the condition reduces to a simple equality/comparison on a session value — *even when written as a lambda* (e.g. `session -> session.getString("tier").equals("gold")` → `pm.variables.get('tier') === 'gold'`). **approximated** only if it calls out to logic you can't express as a plain JS comparison (library calls, computation, external state). A lambda by itself does not force "approximated"; judge the body |
+| `doIfOrElse`, `doSwitch`, `randomSwitch`, `roundRobinSwitch` | `skipRequest` logic per branch. `randomSwitch` percentages via `Math.random()` in a pre-request | approximated |
+| `tryMax(n) { r }` | none. A request that fails isn't retried | gap. Suggest checking the error rate instead |
+| `exitHereIfFailed` | in the test script: `if (pm.response.code >= 400) pm.execution.setNextRequest(null)` — ends the whole iteration | approximated (only stops on status failure, not on any failed check, unless you track that in a variable) |
+| `exitBlockOnFail { … }` | exits **only its block**, then resumes after it — so on failure jump to the **first request after the block** (`pm.execution.setNextRequest('<next>')`), **not** `null`. Ending the iteration would skip requests/cleanup that sit outside the block | approximated (status-failure only unless you track check failures in a variable) |
+| `stopLoadGenerator` / `crashLoadGenerator` | none | gap |
+
+## Custom code (`code:*`)
+`exec(session -> …)` (Java), `exec { session -> … }` (Kotlin), `exec(session => …)` (Scala, JS):
+- Translate it to a **pre-request script** on the next request.
+  - `session.set("k", v)` → `pm.collectionVariables.set('k', v)`
+  - `session.getString("k")` → `pm.collectionVariables.get('k')`
+  - `session.userId()` → `pm.info.iteration`, as an approximation
+  - `UUID.randomUUID()` → `crypto.randomUUID()` if available, otherwise `pm.variables.replaceIn('{{$guid}}')`
+- Always prefix it with `// REVIEW: translated from Gatling custom code (<id>)`. Status: approximated. List it in MIGRATION.md → Approximations, with the original code.
+- JVM library calls you can't translate (JDBC, crypto libraries, file IO) → gap.

package/skills/performance-testing/references/gatling-import/unsupported.md

@@ -0,0 +1,31 @@
+# What can't be carried over, and how to say so
+
+Postman performance runs are **HTTP(S) only** (GraphQL over HTTP and mTLS work). Load settings are the CLI flags in `injection.md`.
+
+## Always a gap
+| Construct | Inventory kind | Wording for MIGRATION.md |
+|---|---|---|
+| `ws(...)`, `sse(...)` | `non_http_step` | WebSocket/SSE steps aren't part of Postman performance runs. They were removed from the load test. Test the socket flow separately (Postman's WebSocket client works for functional checks). |
+| `grpc(...)`, `jms(...)`, `mqtt(...)`, `kafka(...)`, `amqp(...)` | `non_http_step` | This protocol isn't supported under load in Postman. These steps were removed. |
+| `rendezVous(n)` | `timing` | There's no way to synchronise virtual users. Users won't wait for each other. |
+| `pace(d)` | `timing` | There's no iteration pacing: VUs start the next iteration immediately. Add an explicit delay in the last request's test script only if the pacing matters (`setTimeout` isn't reliable under load, so prefer lowering `--vu-count`). |
+| `throttle(...)` | `throttle` | There's no RPS cap. Throughput isn't limited to the Gatling target. |
+| `tryMax(n)` | `flow` | Failed requests aren't retried. |
+| `stopLoadGenerator`, `crashLoadGenerator` | `flow` | There's no scripted run abort. Use `--pass-if` to fail the run afterwards. |
+| `.randomized()` on injection | `injection` | Arrivals aren't randomised. |
+| `.enableHttp2()`, `.inferHtmlResources()`, `.shareConnections()` | `protocol_setting` | See `mapping.md`. |
+| second and later assertions | `assertion` | The CLI takes one `--pass-if`. |
+| `forAll` / `details(...)` assertions | `assertion` | There are no per-request pass criteria. |
+| JDBC/Redis feeders | `feeder` | Export to CSV first. |
+| extra scenarios in `setUp` | `scenario` | One collection per run. Convert them separately and run them in parallel. |
+
+## Pauses
+`pause(d)` and `pause(min, max)` (`timing`) have no first-class think time. Always a **gap**; how it affects the result depends on the injection model:
+- **Open model:** the pause is part of the journey time, so it already feeds the Little's-law `--vu-count` arithmetic in `injection.md`. Dropping the think time alone (keeping the computed VU count) means VUs send faster than Gatling users did. Say which metric (rps) to compare with the Gatling baseline.
+- **Closed model:** there is no journey-time arithmetic to fold into — the VU count is the source concurrency directly. The pause is simply dropped: VUs loop with no think time, so they issue more requests per VU than Gatling did. Record it as a gap and tell the user throughput (rps) will be higher than Gatling's; they can lower `--vu-count` to compensate.
+- If the user explicitly wants think time: a pre-request script with a busy-wait isn't acceptable under load. Record it as a gap, and suggest lowering `--vu-count` in proportion.
+
+## Wording rules
+- One bullet per id: `` `<id>` ``, what changed, why, what to do. Keep it to 1–2 lines.
+- Never write "not supported yet" or promise a roadmap. State today's behaviour.
+- If the gap changes the results (pauses, pace, throttle, queue feeders, open-model injection), say which metric to compare with the Gatling baseline.

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

@@ -9,7 +9,7 @@ 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.
+**api-engineer** when available.
 
 Each tool definition exposed to the model consumes context whenever it is
 included in a request. Prefer the smallest available toolset that covers the

package/skills/variables/SKILL.md

@@ -47,8 +47,8 @@ postman environment var set api_key --secret-id <secret-id> --vault-id <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.
+ability to run a request need not expose the credential to them. Vault
+operations require a signed-in CLI.
 
 ## Verification
 

package/skills/webhook-testing/SKILL.md

@@ -23,7 +23,7 @@ how to use it:
   to fire it again.
 
 The command is singular, and every subcommand needs a signed-in session. Run what you need,
-and read `bootstrap` only if a command fails with a setup error such as `Authentication required`.
+and sign in only if a command fails with a setup error such as `Authentication required`.
 When all you have is the URL, its subdomain is the webhook id.
 
 For capture or inspection alone, create or reuse a webhook and inspect its

package/skills/workspaces/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workspaces
+description: Use when initializing Postman in a repository, binding it to a Postman workspace, interpreting what `postman init` did, or when a CLI command fails because the plan, credits, or usage quota don't allow the operation. Treats the workspace as the place where a service's API work and its evidence live, kept separate from the services it depends on. Use for requests such as "set up Postman in this repo" or "connect this repo to our workspace".
+---
+
+# Workspaces
+
+A Postman workspace is where a service's API work happens and where its context
+builds up: the contracts, collections, environments, and mocks, plus the runs
+and results that show what was checked. It lives in Git beside the code, works
+the same on a laptop or a build agent, and is shared when the work should be
+seen. People use it to audit what was done, by whom, on whose behalf, and with
+what result. Agents use it to read verified work instead of re-deriving it.
+
+1. `postman init` is the starting point. It gives the repository its place of
+   work: Postman files beside the code and, when that is the intent, a
+   workspace bound to them. `postman status` shows whether that is already
+   done, so init runs only when it adds something. Init is safe to repeat and
+   reports what it did: a binding it marks as inferred is a candidate contract
+   to confirm, and a partial result, with local files written but no workspace
+   created, is progress to inspect rather than redo.
+2. One workspace holds the context of one service: one Git repository, or in a
+   monorepo one remote URL and the subpath of one service.
+   `.postman/resources.yaml` records that owner, so every skill, CI job, and
+   teammate resolves the same context. A confirmed binding is worth reusing;
+   replacing it sends the work, and its evidence, to the wrong service.
+3. Other services keep their own workspaces. Their collections, environments,
+   and mocks come in as dependencies through **api-discovery**, so this
+   workspace reuses what another team maintains without taking it over. The
+   context graph links the two, which is how a change on one side reaches work
+   on the other.
+
+## Claiming the work
+
+An agent can start in a guest session, and the work it does there is kept.
+When free credits or a plan limit stop an operation, retrying won't help; the
+person claiming the work is what lets it continue. Wording such as "usage limit
+exceeded", "usage quota has been exceeded", a limit "reached", "breached" or
+"exceeded" for the account, team, or plan, or an operation that "does not allow
+more than" or "requires at least" a stated amount signals one. A temporary rate
+limit or a fixed per-resource validation cap does not. Check which session the
+CLI is using:
+
+- Guest session: tell the user, in its own paragraph, that signing up for a
+  Postman account claims the work done so far and adds the credits needed to
+  continue. Offer to start signup for them; the CLI can produce a link to hand
+  over and waits while they finish in the browser.
+- Signed-in account: tell the user, in its own paragraph, that they need to
+  upgrade their plan at https://postman.postman.co/settings/team/billing.
+
+## Verification
+
+Report the binding in place and what `postman init` did.

package/skills/bootstrap/SKILL.md

@@ -1,140 +0,0 @@
----
-name: bootstrap
-description: Use when resolving Postman CLI setup, authentication, or a repository workspace binding; initializing local API files; handling a CLI error that says an operation isn't allowed because of insufficient entitlements; or importing, pulling, pushing, syncing, or sharing workspace resources. Reuses existing context and chooses sync direction without duplicating a workspace or rebinding a dependency. Use for requests such as "set up Postman for this repo".
----
-
-# Bootstrap Postman for This Repo
-
-A local Postman project puts contracts, runnable requests, environments, and
-mocks beside implementation code so they can be inspected, diffed, and reviewed
-in a PR. A workspace binding connects that work to maintained shared context.
-Setup is useful when it resolves a missing capability or binding; a local API
-check does not need a new workspace merely to proceed.
-
-## Start with postman init
-
-`postman init` is idempotent and safe to run in any project, including one
-already initialized. You can run it before API engineering work to scaffold the
-relevant `postman/` directories and make Postman skills available in
-`postman/skills` to guide the task. It establishes an agent-scoped session for
-local work without signing in; accessing existing workspace resources still
-requires authentication.
-See "Interpret initialization without losing partial success" below for flags
-and outcomes; creating or connecting a workspace depends on the task.
-
-## Resolve only the missing setup
-
-Inspect `postman --version`, `.postman/resources.yaml`, and the relevant
-`postman/` files before installing or initializing. Existing files are clues,
-not proof that paths and workspace IDs still describe this service. Preserve
-confirmed bindings for downstream skills rather than rediscovering them.
-
-**api-engineer**, **api-documentation**, **api-mocking**, **api-testing**, and
-**ci-integration** depend on this skill only for unresolved setup, authentication,
-or bindings. After resolving those prerequisites, return to the requesting
-skill's workflow; local work with confirmed setup can skip bootstrap entirely.
-
-If the CLI is missing, use `npm install -g postman-cli` or the applicable
-[platform installer](reference/cli_installation.md). Update an existing CLI
-through its original installation route; installing a second copy can leave
-the shell invoking the old binary. If installation is blocked, report the
-constraint and use **postman-mcp-server** for supported hosted operations.
-
-Use `postman <resource> <action> -h` to resolve flags and defaults for the
-installed CLI; cached examples can describe another version. Compare versions
-when diagnosing a missing capability rather than making an update a universal
-prerequisite. Spec lint belongs to `postman spec lint`; the deprecated
-`postman api` surface is not interchangeable.
-
-Local file operations need no normal login. `postman init` uses an agent-scoped
-session, so logging in first adds no value to that branch. Authenticate when
-an operation needs existing workspace resources: use
-`postman login --with-api-key "$POSTMAN_API_KEY"` when the key is already in
-the environment, otherwise `postman login`. Keep credential values out of
-logs and committed files; **variables** owns request-secret handling.
-
-## Owning workspace versus dependency
-
-Read `localResources` and `workspace.id` in `.postman/resources.yaml`. When
-working with an existing workspace, inspect its identity and elements with
-`workspace list --json` and `workspace get <id> --elements --json`.
-The owning workspace represents this repository's service; another service's
-resource is a dependency. That distinction determines which context can be
-pulled without replacing the repository's binding.
-
-| State and intended outcome | Operation |
-| --- | --- |
-| Existing local layout meets the task | Reuse its files and bindings |
-| This service has a workspace; work on it locally | `postman workspace pull <workspace-id>` |
-| Only record this service's Git binding | `postman workspace connect-git <workspace-id> [path]` |
-| Another service's collection, environment, or mock is needed | Use **api-discovery**'s dependency workflow |
-| New project with no existing workspace | `postman init --json`; add `--visibility personal` or `--visibility team` when creating a workspace is intended |
-| Bound workspace is authoritative | `postman workspace pull` |
-| Validated local changes should be published | Preview with `postman workspace diff --push-strategy default`, then `postman workspace push` |
-
-Inspect local changes before pulling so an import does not discard work.
-Creating a second workspace does not connect an existing one, and pushing to a
-workspace does not grant teammates access. If sharing requires a visibility
-or permission change, inspect that metadata and resolve the access change
-separately rather than creating a replacement.
-
-`workspace diff` is read-only; use the strategy planned for the push.
-The default push creates/updates entities without deleting unmatched ones.
-`--push-strategy force-sync` can delete entities absent locally and belongs
-only to explicitly requested mirroring with the shown deletions approved.
-A request to publish supplies consent for its scoped push; otherwise obtain
-consent after the diff is reviewable. See **ci-integration** for publishing
-reviewed changes after merge.
-
-## Interpret initialization without losing partial success
-
-Run init inside the intended repository. It scaffolds Postman files and
-`.postman/resources.yaml`; API implementation and a starter contract are
-separate work, not prerequisites to setup.
-
-`--json` avoids interactive prompts. Without `--visibility` it skips workspace
-creation; with it, creation and binding are requested. Read `bindings` and
-`exitCode` from the JSON payload. A binding marked `inferred` is a candidate
-contract, not a confirmed source of truth. Exit 2 means multiple specs need
-selection with `--spec <path>`. Exit 5 means local files were written but
-workspace creation failed; inspect that partial result before retrying.
-
-## Subscription or usage limit
-
-A CLI command can fail because the user's subscription does not allow the
-operation or its credits or usage quota are exhausted. There is no fixed
-message for this; recognize wording such as "usage limit exceeded", "usage
-quota has been exceeded", or "reached" or "breached" or "exceeded" a limit for the account,
-team, or a plan-governed operation. Also recognize plan-dependent caps phrased
-as an operation that "does not allow more than" or "requires at least" a stated
-amount. Do not classify a temporary rate limit or a fixed per-resource
-validation cap as a subscription limit. Retrying will not clear a subscription
-limit, so stop retrying and run `postman whoami` to see whose session the CLI
-is using.
-
-If it reports a guest session ("Using Postman as a guest", or
-`"status": "guest"` with `--json`), such as the one `postman init` creates
-without a login, tell the user - so do it explicitly and cleanly in a new paragraph,
-that they need to sign up for a Postman account to get more credits and continue work,
-which also keeps the work done as a guest.
-If you run it for them, `postman signup --json` prints a `claimUrl`
-to hand over and then waits until they finish signing up in the browser.
-Ask the user if they want you to initiate signup for them.
-
-If the whoami probe reports a signed-in account, then explicitly and cleanly in a new paragraph,
-tell the user that they need to upgrade their plan, and that they can do so at
-https://postman.postman.co/settings/team/billing.
-
-## Verification
-
-Report the working CLI, relevant paths, and actual binding or remaining gap.
-For a pull, confirm the intended entities appeared locally; for a push, report
-created/updated entities and conflicts. Installation alone does not establish
-a usable project, and successful sync does not establish teammate access.
-
-## Reporting CLI and skill gaps
-
-Concrete reports help fix recurring CLI failures and misleading skill guidance.
-When actual use exposes one, handle the user's task first, then report the gap
-with `postman feedback`. Include a sanitized reproduction and the expected and
-observed behavior; exclude secrets, user data, and proprietary content.

package/skills/bootstrap/reference/cli_installation.md

@@ -1,59 +0,0 @@
-# Postman CLI Installation
-
-A global install on `PATH`. npm works anywhere Node is available; the curl
-installer covers macOS, Linux, and WSL; and the PowerShell installer covers
-Windows. Whichever route put the binary there is the one to use again when
-updating it — mixing routes leaves two `postman` binaries and a `PATH`
-question.
-
-## Install
-
-**npm (all platforms):**
-
-```bash
-npm install -g postman-cli
-```
-
-**macOS, Linux, and WSL (curl):**
-
-```bash
-curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
-```
-
-**Windows (PowerShell):**
-
-```powershell
-powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"
-```
-
-## Check for drift
-
-```bash
-postman --version              # installed
-npm view postman-cli version   # latest published
-```
-
-## Update
-
-Run the same command that installed it — the npm, curl or PowerShell line
-above, whichever put the binary there. Using a different one leaves two
-`postman` binaries and a `PATH` question. Never `npm install -g` over a copy
-that came from the curl installer or a system package manager.
-
-The CLI has no self-update verb. `postman skills update` is a different
-thing: it refreshes a repository's committed `postman/skills/`, not the
-binary.
-
-## Uninstall
-
-npm installations:
-
-```bash
-npm uninstall -g postman-cli
-```
-
-Other install methods: delete the `postman` binary from its install
-directory (`%USERPROFILE%\AppData\Local\Microsoft\WindowsApps` on Windows,
-`/usr/local/bin` on macOS/Linux/WSL).
-
-Source: https://learning.postman.com/docs/postman-cli/postman-cli-installation/