@postman/postman-plugin 0.5.1 → 0.6.0-rc.0

package/skills/collection-schema-v3/reference/other_protocols.md

@@ -1,86 +1,232 @@
-# Non-HTTP request schemas (v3)
-
-Read this only when a collection actually contains one of these request
-types — for the common case, the HTTP schema in the parent
-[SKILL.md](../SKILL.md) is the one that applies.
-
-## GraphQL request
-
-- `$kind: "graphql-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `query` — string (the GraphQL query).
-- `variables` — string (a YAML string containing a JSON object).
-- `headers` — array of `{key, value, description?, disabled?}`.
-- `auth` — `{type, credentials}`.
-- `settings` — `{disabledSystemHeaders?}`.
-- `scripts` — array of `{type: "beforeQuery"|"afterResponse", code, language}`.
-
-## gRPC request
-
-- `$kind: "grpc-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `methodPath` — string.
-- `methodDescriptor` — string.
-- `message` — `{content: string (JSON)}`.
-- `metadata` — array of `{key, value, description?}`.
-- `auth` — `{type, credentials}`.
-- `settings` —
-  `{secureConnection?, strictSSL?, maxResponseMessageSize?, includeDefaultFields?, connectionTimeout?}`.
-- `scripts` — array of `{type: "beforeInvoke"|"afterResponse", code, language}`.
-
-## WebSocket request
-
-- `$kind: "websocket-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `headers` — array of `{key, value, description?, disabled?}`.
-- `queryParams` — array of `{key, value, description?, disabled?}`.
-- `settings` — `{handshakeTimeout?, retryCount?, retryDelay?, maxPayload?, strictSSL?}`.
-
-## Socket.IO request
-
-- `$kind: "socket.io-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `headers` — array of `{key, value}`.
-- `queryParams` — array of `{key, value}`.
-- `events` — array of `{name, description?, subscribeOnConnect: boolean}`.
-- `settings` — `{version?, path?, handshakeTimeout?, retryCount?, retryDelay?, strictSSL?}`.
-
-## MQTT request
-
-- `$kind: "mqtt-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `clientId` — string.
-- `version` — `4 | 5`.
-- `topics` — array of
-  `{name, qos: 0|1|2, subscribe: boolean, description?, settings: {noLocal?, retainAsPublished?, retainHandling?, subscriptionIdentifier?}}`.
-- `lastWill` — `{topic, payload, qos, retain, type: "text"|"json", properties: {messageExpiryInterval?, contentType?}}`.
-- `properties` —
-  `{sessionExpiryInterval?, receiveMaximum?, maximumPacketSize?, requestResponseInformation?, userProperties: [{key, value}]}`.
-- `settings` — `{cleanSession?, keepAlive?, autoReconnect?, connectionTimeout?, strictSSL?}`.
-
-## MCP request
-
-- `$kind: "mcp-request"` — required.
-- `transport` — `"sse" | "stdio"`.
-- `order` — optional.
-- SSE shape: `{url, headers?, message, auth?, settings: {strictSSL?, requestTimeout?, sessionTimeout?}}`.
-- STDIO shape: `{command, env: [{key, value}], message, auth?, settings: {requestTimeout?}}`.
-
-## LLM request
-
-- `$kind: "llm-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `config` — `{model, provider}`.
-- `userPrompts` — array of `{id, value, timestamp, active, type: "text"}`.
-- `systemPrompts` — array of `{id, value, timestamp, active, type: "text"}`.
-- `mcpConfig` — optional string (JSON config).
-- `enabledTools` — optional array of strings.
-- `auth` — `{type, credentials}`.
-- `settings` —
-  `{temperature?, maxToken?, streamResponse?, responseFormatJSON?, topP?, presencePenalty?, frequencyPenalty?, maxSteps?, streamTools?}`.
+# Other protocol schemas
+
+Consult the section for the request kind being changed. Non-HTTP protocols have
+different body, script, and settings shapes; structural validity does not establish
+that the configured service or provider is available.
+
+Shared [auth](http.md#auth), [body](http.md#request-body), and
+[script](http.md#scripts) shapes are documented with HTTP where they apply.
+
+- [Request kinds](#request-kinds): GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, LLM
+- [Messages](#messages) and [examples](#examples)
+
+## Request kinds
+
+`$kind` is required on these request kinds, and it is the *only* required field except on
+`mcp-request`, which also requires `transport`. So for every other kind a half-written
+request can pass structural checks without being executable. Only `*.request.yaml`
+files are discovered as requests; the right fields in a differently named file
+do not make it runnable. Each kind has its own settings; HTTP settings do not
+apply to every protocol. Common metadata fields `id`, `name`, `description` and `order`
+are available on all of them and omitted below.
+
+### `graphql-request`
+
+`url`, `query`, `variables` (a **string** of JSON), `headers`, `auth`, `schema`,
+`scripts`, `examples`, `settings`.
+
+There is **no `queryParams`** — put query-string parameters in the `url`.
+
+`settings`: `disabledSystemHeaders`.
+
+`schema` is one shape chosen by `source`:
+
+```yaml
+schema: {source: none}
+```
+```yaml
+schema: {source: auto}
+```
+```yaml
+schema:
+  source: file
+  location: ./schema.graphql
+```
+```yaml
+schema:
+  source: api
+  apiId: <id>
+  versionId: <id>          # releaseId optional
+```
+```yaml
+schema:
+  source: specification
+  specificationId: <id>
+```
+
+### `grpc-request`
+
+`url`, `methodPath` (e.g. `helloworld.Greeter/SayHello`), `methodDescriptor` (an inline
+proto definition), `message` (`{content}`), `metadata` (per-call headers as
+`{key, value}` array entries), `auth`, `schema`, `scripts`, `examples`, `settings`.
+
+`settings`: `secureConnection`, `strictSSL`, `serverNameOverride`,
+`maxResponseMessageSize`, `includeDefaultFields`, `connectionTimeout`.
+
+### `websocket-request`
+
+`url`, `headers`, `queryParams`, `messages`, `examples`, `settings`.
+
+`messages` and `examples` are **strings** — relative paths to directories, not arrays.
+An array fails with `Invalid input: expected string, received array`.
+
+`settings`: `handshakeTimeout`, `retryCount`, `maxPayload`, `retryDelay`, `strictSSL`.
+
+### `socket.io-request`
+
+`url`, `headers`, `queryParams`, `events`, `messages`, `examples`, `settings`.
+
+```yaml
+events:
+  - name: chat:message
+    subscribeOnConnect: true
+    description: Inbound chat traffic
+```
+
+`settings`: `version` (the **strings** `'2'`, `'3'`, `'4'`), `path`,
+`handshakeTimeout`, `retryCount`, `retryDelay`, `strictSSL`. Bare `version: 4` is
+rejected — `Invalid option: expected one of "2"|"3"|"4" (path: /settings/version)`.
+
+### `mqtt-request`
+
+`url`, `clientId`, `version`, `topics`, `lastWill`, `properties`, `auth`, `messages`,
+`examples`, `settings`.
+
+`version` is a **number**, either `4` or `5`, and it sits at the top level rather than
+in `settings`. Do not quote it — that is the opposite of `socket.io-request`, whose
+`settings.version` is the string `'2'`, `'3'` or `'4'`.
+
+```yaml
+topics:
+  - name: sensors/+/temp
+    qos: 1                 # a number: 0, 1 or 2
+    subscribe: true
+lastWill:
+  topic: status/client
+  payload: offline
+  type: text
+  qos: 0
+  retain: true
+```
+
+`properties`: `sessionExpiryInterval`, `receiveMaximum`, `maximumPacketSize`,
+`requestResponseInformation`, `userProperties`.
+
+`settings`: `cleanSession`, `keepAlive`, `autoReconnect`, `connectionTimeout`,
+`strictSSL`.
+
+### `mcp-request`
+
+Requires `$kind` **and** `transport`, which selects the legal keys. Common to both:
+`message`, `auth`.
+
+| `transport` | Its keys | `settings` |
+|---|---|---|
+| `stdio` | `command`, `env` (`{key, value}` array entries) | `version`, `requestTimeout` |
+| `sse` | `url`, `headers` | `version`, `requestTimeout`, `strictSSL`, `sessionTimeout` |
+
+There are no other transports. `message` is a JSON-RPC envelope as a **string**;
+`{{variables}}` interpolate inside it.
+
+```yaml
+$kind: mcp-request
+transport: stdio           # command + env; no url
+command: uvx some-mcp-server
+env:
+  - key: API_KEY
+    value: '{{KEY}}'
+message: |-
+  {"method": "tools/call", "params": {"name": "do_thing", "arguments": {}}}
+order: 1000
+```
+
+```yaml
+$kind: mcp-request
+transport: sse             # url + headers; no command
+url: https://mcp.example.com/sse
+headers:
+  - key: Authorization
+    value: 'Bearer {{KEY}}'
+message: |-
+  {"method": "tools/list"}
+```
+
+### `llm-request`
+
+`url`, `config`, `userPrompts`, `systemPrompts`, `mcpConfig`, `enabledTools`,
+`clientTools`, `auth`, `settings`.
+
+`config` takes `model` and `provider`, both free-form strings. Schema validation
+does not establish that the configured provider or model is available at run time.
+
+Prompt entries are `{id, value, timestamp, active, contentType}`. The content
+format is expressed by `contentType`; `type` is not a prompt-entry field.
+`timestamp` is numeric, and `active` is boolean.
+
+`mcpConfig` is a **string containing a JSON array**, not nested YAML and not
+`mcp.json`'s `mcpServers` object. `clientTools`, for tools the model may call with no
+MCP server behind them, is `[{id, tools: [{id}]}]`.
+
+For example, a prompt and a stdio MCP tool configuration use different scalar
+shapes within the same request:
+
+```yaml
+userPrompts:
+  - id: '1'
+    value: Summarise the last 10 orders
+    timestamp: 1758412800000
+    active: true
+    contentType: text
+mcpConfig: |-
+  [
+    {
+      "name": "orders",
+      "config": {"command": "uvx", "args": ["orders-mcp-server"]},
+      "enabled": true,
+      "disabledTools": []
+    }
+  ]
+```
+
+`settings`: `temperature`, `maxToken`, `maxSteps`, `topP`, `topK`, `seed`,
+`presencePenalty`, `frequencyPenalty`, `repetitionPenalty`, `contextWindow`,
+`streamResponse`, `streamTools`, `responseFormatJSON`. If a tool chain stops early,
+distinguish a step limit from a tool or provider failure before changing `maxSteps`;
+the limit also bounds execution cost and duration.
+
+## Messages
+
+A `messages` directory holds `*.message.yaml` files. Each kind has different required
+fields; a valid WebSocket message is not automatically a valid MQTT message.
+
+```yaml
+$kind: websocket-message      # requires content + contentType
+content: '{"op":"subscribe"}'
+contentType: json             # text | json | xml | html | hex | base64
+```
+
+```yaml
+$kind: socket.io-message      # requires eventName + args
+eventName: chat:message
+acknowledgement: true
+args:
+  - content: '{"text":"hi"}'
+    contentType: json
+```
+
+```yaml
+$kind: mqtt-message           # requires content + contentType + topic
+topic: sensors/1/temp
+content: '21.5'
+contentType: text             # text | json | hex | base64
+qos: 1
+retain: false
+```
+
+## Examples
+
+Examples live in `.resources/<request-name>.resources/examples/*.example.yaml`, with
+`$kind` matching the request's protocol — `graphql-example`,
+`grpc-example`, `websocket-example`, `socket.io-example`, `mqtt-example`. An
+`*-example` kind is rejected in a `*.request.yaml`, and a `*-request` kind is rejected
+in a `*.example.yaml`.

package/skills/datasets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: datasets
-description: Use when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as "run this collection over database rows".
+description: Use when creating or repairing dataset manifests, or when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as "run this collection over database rows".
 ---
 
 # Datasets
@@ -43,15 +43,16 @@ stay with `collection run -d`; a dataset should earn its extra configuration.
 
 Create a local manifest with `postman dataset create <path.dataset.yaml>
 --name <name>`, then attach sources with `dataset source add`. Source commands
-supply IDs and validation that hand-written entries can miss. Existing-dataset
-commands accept a local path or workspace ID; `list` needs a local path for
+supply IDs and validation that hand-written entries can miss. When inspecting
+or repairing manifest fields, consult [Dataset YAML](reference/schema.md).
+Existing-dataset commands accept a local path or workspace ID; `list` needs a local path for
 local discovery, while workspace create/list use `--workspace`.
 
 File sources are copied into `data_dir` unless `--ref-only` is used. That option
 records absolute paths and makes the dataset machine-specific. For a workspace
 dataset, adding `--file` alone registers a local filesystem source; `--upload`
-is what uploads bytes. Use **bootstrap**'s workspace sync when publishing the
-whole project; there is no separate `dataset push`.
+is what uploads bytes. Datasets are pushed along with the workspace; there is
+no separate `dataset push`.
 
 For spreadsheet sources, use the worksheet-aware guidance in
 [Spreadsheet sources](reference/spreadsheets.md). For ordinary source names,

package/skills/datasets/reference/schema.md

@@ -0,0 +1,51 @@
+# Dataset YAML
+
+Consult this reference when inspecting or repairing manifest fields. Source and
+view commands can supply generated IDs when creating new entries.
+
+```
+postman/datasets/users/
+├── users.dataset.yaml
+└── .resources/
+    └── rows.json
+```
+
+```yaml
+type: dataset                 # not $kind
+name: "Users"
+id: 3f2b6c1e-9d4a-4f81-bc37-5e0a71d9c402     # uuid4
+data_dir: .resources
+sources:
+  - from: embedded_datasource
+    datasource:
+      name: Records
+      id: 8a1d0e77-5c62-4b19-9f03-2d6e4a8b7c15
+      format: json            # this example uses a JSON file
+      source_type: static     # static for files, dynamic for databases
+      location:
+        type: local_filesystem
+        value: rows.json      # relative to data_dir
+views:
+  - from: embedded_view
+    view:
+      name: Records_default_view
+      id: c94e5b20-71af-4d36-8e52-0b7c6d1934fa
+      query: SELECT id, name FROM Records ORDER BY id
+```
+
+`sources` and `views` are optional — `type`, `name`, `id` and `data_dir` alone is a
+valid dataset, and is what `postman dataset create <path> --name X` writes.
+
+For example, a MySQL source sets `format: mysql`, `source_type: dynamic`,
+`ingest: false`, a `dsKey` and a `slug`, with `location.type: mysql`, `location.value`
+a DSN and `location.table` the table name.
+
+A view's `query` is SQL over the source `name`, not over the file name.
+
+There is no `dataset lint`. `postman dataset get <path>` checks the structure offline.
+`postman dataset query <path> -q "<sql>"` runs SQL against the source, which also proves
+the data parses and the query resolves — note the `-q` flag is required.
+
+Connector support and credential handling depend on the installed CLI. Use the
+**datasets** skill's connector and credential guidance when changing a source;
+the MySQL example above is not a complete list of supported connectors.

package/skills/flows/SKILL.md

@@ -49,7 +49,6 @@ result that says nothing about the caller's actual workflow.
    and reports. Connector blocks need `--workspace` even for a local file;
    otherwise failure occurs inside the graph. An access denial across several
    workspaces points toward credentials or entitlement, not an empty flow list.
-   Use **bootstrap** for unresolved CLI/authentication setup.
 
 Read [command options](reference/flow_cli_flags.md) for inputs, reporters,
 dataset iteration, and flag collisions; check installed subcommand `-h` before

package/skills/performance-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: performance-testing
-description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API".
+description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds, or when importing or migrating a JMeter `.jmx` plan or a Gatling simulation (Java/Kotlin/Scala/JS/TS) into a Postman collection plus a `postman performance run` configuration. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API", "import my JMeter plan", or "convert my Gatling project to Postman".
 ---
 
 # Performance Testing
@@ -47,6 +47,19 @@ and which JMeter features have no equivalent here — think-time timers,
 concurrent thread groups, and non-HTTP (JDBC/FTP/LDAP/Java) samplers are
 reported, never faked.
 
+## Importing from Gatling
+
+Have a Gatling project (a Java/Kotlin/Scala/JS/TS `Simulation`) instead of a
+collection? Convert it by following `references/gatling-import/README.md`, then
+treat the result as the collection above. There is no importer to run — you read
+the source and build the collection, environment, `run.sh` and gap report, using
+the files next to that README as the algorithm (`mapping.md`, `injection.md`,
+`feeders.md`, `unsupported.md`). The gap report marks what mapped exactly, what
+was approximated, and what has no equivalent — WebSocket/SSE and other non-HTTP
+steps, arrival-rate (open-model) injection, think-time pauses, throttling and
+retries are reported, never faked. Open-model injection is converted to VUs via
+Little's law with the arithmetic shown, not guessed.
+
 ## Verification
 
 Report the workload, runner, achieved traffic, latency and error metrics,

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

@@ -0,0 +1,141 @@
+# Importing a Gatling project into Postman
+
+> Reference for the `performance-testing` skill. Convert the simulation, review the gap report, then the result is an ordinary performance run. Verifying it runs one iteration of real requests against the target, so confirm the target first — the same way any action with effects outside this session gets confirmed.
+
+## Overview
+A Gatling simulation is code: a scenario of `http()` requests, checks, feeders,
+pauses and flow control, plus a `setUp` that injects load and asserts on
+results. Postman splits the same thing in two:
+- the **collection** (requests, test scripts, variables, data file), and
+- the **run config** (`postman performance run` flags: VUs, duration, load profile, pass criteria).
+
+You do the whole translation by reading the source and applying the files next to
+this one — there is no importer to run. Two disciplines keep you honest, both
+described below: an **inventory** (list every construct first, so nothing is
+dropped silently) and a **self-verify** pass (prove every construct landed
+somewhere or is explained, and that the collection actually runs).
+
+A conversion that runs but silently drops a check, or quietly changes the load
+model, is worse than no conversion, because the user will trust the numbers.
+**The gap report is a first-class output, not an apology.**
+
+## Workflow
+
+1. **Discover.** Find the simulation(s): classes that `extends Simulation`,
+   Kotlin `: Simulation()`, or JS/TS `simulation((setUp) => …)`. Note the language
+   and build tool. If there is more than one simulation, ask which to convert.
+   Convert one simulation per output directory.
+2. **Inventory.** Read every source file the simulation touches and list **every
+   construct a conversion must account for** — see *Inventory: what to list*. This
+   is your checklist; each item gets a stable id. Pay attention to requests built
+   in loops or helper methods and to dynamic names — a shallow scan misses them.
+3. **Translate** each item using the files next to this one:
+   - `mapping.md`: requests, EL, checks, protocol settings, groups, flow control, custom code
+   - `feeders.md`: feeders → data file + distribution
+   - `injection.md`: injection profiles, throttle, assertions → run flags
+   - `unsupported.md`: what becomes a gap, and how to word it
+4. **Write outputs** to the output directory (formats below).
+5. **Verify** against the checklist in *Verify: self-review* — including, after you
+   confirm the target, one real smoke iteration via the existing
+   `postman collection run` command. Fix everything that fails and re-check, up to
+   3 rounds.
+6. **Report** to the user: counts (mapped / approximated / gap), the verify
+   result, and the top 3 things they must do by hand. Point them to MIGRATION.md.
+
+## Inventory: what to list
+List every construct below that appears in the simulation, each with a **stable
+id** (used verbatim in the MIGRATION.md coverage table). Kinds and id prefixes:
+
+- `req:<name>` — each `http("name").get/post(...)` request.
+- `check:<req>#<n>` — each check on a request (`status`, `jsonPath`, `jmesPath`, `regex`, `header`, `bodyString`, `substring`, `responseTimeInMillis`, …). A request with **no** `status` check still has Gatling's implicit 2xx-or-304 check — list it as `implicit-status:<req>`.
+- `scenario:<name>`, `group:<name>` — scenarios and groups.
+- `feeder:<file>` and `feed:<n>` — feeder sources and `feed(...)` calls (one logical data source emits both; see `feeders.md`).
+- `timing:<n>` — `pause`, `pace`, `rendezVous`.
+- `flow:<construct>#<n>` — `repeat`, `during`, `forever`, `doIf`, `tryMax`, `exitHereIfFailed`, `doSwitch`, … 
+- `inj#<n>` — each injection step (open or closed model).
+- `throttle#<n>`, `max-duration` — throttle / `maxDuration`.
+- `assert#<n>` — each `setUp(...).assertions(...)` entry.
+- `proto:<setting>` — each `http.baseUrl/header/acceptHeader/shareConnections/enableHttp2/...`.
+- `non_http:<proto>:<name>` — `ws`, `sse`, `grpc`, `mqtt`, … steps (and their checks).
+- `code:<n>` — custom-code `exec(session -> …)` lambdas.
+- `secret:<n>` — any literal that looks like a credential (API key, token, `Authorization` value). **Record only that it exists — never copy the literal anywhere.**
+
+A request built in a loop or helper, or named dynamically, still gets an id; find it by reading, not pattern-matching. If you are unsure a construct exists, list it and resolve it to a gap rather than omit it.
+
+## Output formats
+### `collection.json`: Postman collection v2.1
+- `info.schema` = `https://schema.getpostman.com/json/collection/v2.1.0/collection.json`
+- `info.description` is a plain string whose first line is exactly `imported-from: gatling` followed by two lines `source: <relative source path>` and `class: <simulation class/name>`. Example: `"imported-from: gatling\nsource: src/test/java/poc/BasicSimulation.java\nclass: BasicSimulation"`.
+- One collection per simulation. One folder per Gatling `group`; with **no** groups, requests sit at the collection root (a bare request name, no folder prefix — that is valid). Requests keep their Gatling names exactly (they drive per-request metrics), and **request leaf names must be unique** (a collection cannot hold two requests with the same path — see `repeat` in mapping.md).
+- Base URL → collection variable `baseUrl`. Requests use `{{baseUrl}}/path`.
+- Each request's test script ends with the translated checks. Mark translated custom code with `// REVIEW: translated from Gatling custom code (<inventory id>)`.
+
+### `environment.json`: Postman environment
+`{"name": "<simulation> (from Gatling)", "values": [{"key": "...", "value": "...", "enabled": true}]}`.
+Secrets become keys with an **empty value** and `"type": "secret"`. Never copy a
+secret literal from the source (see Critical rules). This file holds **secrets and
+externalised config only** — `baseUrl` and correlation values are collection variables, not
+environment keys. **Always write the file**, even when there is nothing to put in it: a
+simulation with no secrets and no externalised config gets `"values": []`. (An empty
+environment is correct and expected, not a defect.)
+
+### `data/<name>.csv`
+Copy feeder files that the simulation uses. Convert JSON array feeders to CSV if they are flat. If the simulation has **no feeder**, don't create a `data/` directory at all (and omit `--data-file` from run.sh).
+
+### `run.sh`
+```bash
+#!/usr/bin/env bash
+# Converted from <Simulation>. Replace <collection-uid> after pushing the collection to a workspace.
+postman performance run "<collection-uid>" \
+  --environment "<environment-uid>" \
+  --vu-count 20 --duration 5 --load-profile ramp-up \
+  --data-file data/users.csv \
+  --pass-if "less_than(error_rate, 1)"
+```
+Only flags that exist in `postman performance run --help` (check the user's installed
+version; don't assume a flag from a newer CLI). Duration is in whole minutes, rounded up.
+- `--environment` — include it whenever `environment.json` has any values (the secrets/config requests depend on). Requests using `{{secret}}`/config resolve to nothing without it. Tell the user to import and **populate** `environment.json`, then replace `<environment-uid>` with its UID. Omit the flag only when the environment is empty (`values: []`).
+- `--data-file` only if the simulation has a feeder; **omit the line entirely** when there is none (don't invent a data file).
+- `--pass-if`: **at most one**, chosen by the strict priority in `injection.md` (error-rate, then latency percentile, then mean/rps) — this overrides source order. If **no** source assertion matches any category, **omit `--pass-if` entirely**. Every non-chosen assertion goes to the gap report.
+
+### `MIGRATION.md`: gap report (also your accounting record)
+Sections, in order:
+1. **Summary**: source, counts (mapped / approximated / gap), verify result. The counts must equal the coverage-table tally; derive them from the table, don't hand-write them.
+2. **Load model**: the original injection profile, the chosen flags, and the arithmetic (see `injection.md`). Required even when the mapping is exact.
+3. **Coverage**: a table with one row per inventory id — this is the accounting that replaces a manifest. Columns: `id` · `kind` · `status` (`mapped` / `approximated` / `gap`) · `landed` (where it went, or why it was dropped). **Every inventory id appears here**; a missing row is a silently-dropped construct. Use these idioms in `landed`:
+   - request → `collection:<folder>/<request>` (root request → just the name)
+   - check / saveAs → `collection:<req> › test` (a `saveAs` value is script-set, so it is a test-script line, not a declared collection variable)
+   - protocol setting on every request → name each request it lands on
+   - scenario → `the collection itself`; group → `folder <name>`
+   - injection → the `run:` flags it set
+   - secret → `environment:<key> (placeholder, value not copied)`
+4. **Approximations**: one bullet per approximated id: `` `<id>` ``, what changed, why, what to check.
+5. **Gaps**: one bullet per gap id: `` `<id>` ``, what was dropped, why, and the manual workaround if there is one.
+6. **Secrets**: which environment keys the user must fill in.
+7. **Next steps**: push the collection, fill secrets, run a short test, compare with a Gatling baseline.
+
+Every `approximated` or `gap` id **must appear verbatim** in both the coverage table and its Approximations/Gaps bullet.
+
+## Verify: self-review
+Before claiming done, check each of these against your own output and fix every miss:
+
+1. **Accounting** — every inventory id has a row in the MIGRATION.md coverage table; every `approximated`/`gap` id also has its bullet. Nothing dropped silently.
+2. **Collection** — valid v2.1, `info.description` stamped `imported-from: gatling`, every request has a method and a URL, and no two requests share the same folder/name path.
+3. **Variables** — every `{{var}}` used anywhere in the collection is defined somewhere: a collection variable, an environment key, a data-file column, or set by an earlier request's script. An undefined `{{var}}` is a bug.
+4. **Secrets** — no secret literal appears in any output file (collection, environment, run.sh, MIGRATION.md). Re-read the source's credential-looking values and confirm none were copied.
+5. **run.sh** — run `postman performance run --help` and confirm every flag you used exists in this CLI version, values are valid (duration a whole number ≥ 1, load profile one of the listed names), and there is **at most one** `--pass-if`.
+6. **Smoke** — the one executable check. Tell the user it sends **one iteration** of the converted requests to the target host(s), name the host(s), and wait for a yes for any host that is not local. Then run the existing CLI:
+
+   ```
+   postman collection run collection.json -n 1 -e environment.json
+   ```
+
+   (add `-d data/<file>` when there is a feeder). Confirm every request executed with no transport error. A `pm.test` failure that comes from the conversion needs an explanation in MIGRATION.md; one that comes from the target (e.g. a 4xx the simulation also expected) just gets noted. If the user declines the traffic, or there is no CLI login / network, skip only this step and say in your report that no request was executed — the other five checks still hold.
+
+## Critical rules
+1. **Never copy a secret literal into any output.** That covers the collection, environment, run.sh and MIGRATION.md. Items of kind `secret` become an environment key with an empty value, and MIGRATION.md tells the user to fill it in. Don't put secrets in descriptions or metadata either.
+2. **Never drop an item silently.** Every inventory id gets a coverage-table row. If you aren't sure, choose `approximated` or `gap` and explain. Don't choose `mapped`.
+3. **Never change the load model silently.** Open-model (arrival-rate) injection has no exact equivalent. Always show the conversion arithmetic in MIGRATION.md → Load model.
+4. **Confirm before sending traffic.** The smoke sends one iteration to the target. Get a yes for any non-local host first. Never run `postman performance run` yourself; the user runs `run.sh`.
+5. **Keep request names identical** to the Gatling `http("…")` names, so results can be compared with old Gatling reports.
+6. **Don't claim done until the self-verify checklist passes.** If you can't get it to pass in 3 rounds, stop and report what is still failing.

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

@@ -0,0 +1,31 @@
+# Feeders → data file + distribution
+
+## Sources (`feeder:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `csv("f.csv")`, `tsv`, `ssv`, `separatedValues` | copy to `data/f.csv` (convert TSV/SSV to CSV) → `--data-file data/f.csv` | mapped |
+| `jsonFile("f.json")` (a flat array of objects) | `data/f.csv`, or keep JSON (`--data-file` accepts JSON) | mapped |
+| `jsonUrl(url)` | download once (with the user's OK) or leave as a gap | gap unless downloaded |
+| `jdbcFeeder`, `redisFeeder`, `sitemap` | export to CSV by hand | gap. Give the export query in MIGRATION.md |
+| `listFeeder` / `arrayFeeder` (inline data) | write the rows to `data/<name>.csv` | mapped |
+
+The file must sit in `$OUT/data/` so that `run.sh` and the smoke run can find it. Set `manifest.run.data_file` to the file the smoke run should use.
+
+## Strategy
+The Gatling default (no strategy) is **`queue`**. Each record is used once, and the run **crashes** when the records run out.
+| Gatling | `postman performance run --data-file` behaviour | Status |
+|---|---|---|
+| `.circular()` | with `--data-file`, local rows are distributed per the CLI's documented default (confirm in the installed `--help`; it has been random in recent CLIs). Each VU iteration picks a row | approximated. Say the distribution follows the CLI default, not Gatling's round-robin. A Postman Dataset (`--dataset-distribution round-robin`) is the exact match |
+| `.random()` | random | mapped |
+| `.shuffle()` | random (with replacement) | approximated |
+| `.queue()` / default | random; rows can repeat and the run never runs out | approximated. **Always** call out that uniqueness is lost: if the source relies on each row being used once (unique users, one-time tokens), the test will behave differently |
+| `.shard()` | none | gap |
+| `.batch()`, `.eager()`, `.transform(...)`, `.unzip()` | `eager` and `batch` are no-ops. `transform` → a pre-request script | approximated |
+
+## `feed(...)` calls (`feed:*`)
+`feed(f)` at the start of the scenario → each iteration gets a row, and the columns become variables `{{column}}`. Mapped, with `target: "data:data/<file>"`.
+`feed(f, n)` (several records at once) → gap.
+
+**One data source, two inventory ids.** The inventory emits a `feeder:*` id (the source + its distribution strategy) **and** a `feed:*` id (the binding that hands a row to each iteration), both describing one logical data file. Account for them split by concern: the `feed:*` id is **mapped** (`target: data:data/<file>` — row → `{{column}}` variables), and the `feeder:*` id carries the **strategy** status (e.g. `.circular()` → **approximated**, "distribution follows the CLI default, not round-robin"; default `queue` → **approximated**, "uniqueness lost"). Both may point at the same `data:` target; that is expected, not a duplicate.
+
+**Multiple feeders.** A scenario with more than one `feed(...)` (e.g. `feed(users).feed(products)`) has **no exact mapping**: `postman performance run` takes a single `--data-file` and the smoke run a single `-d`, so only one set of columns can bind. Do **not** emit two `--data-file` bindings and mark both mapped — one set would silently go unbound. Instead either: (a) **combine** the sources into one CSV/dataset by joining their columns, and document the changed row pairing/distribution in MIGRATION.md (**approximated**); or (b) map the primary feeder and record the others as **gaps**, naming which `{{columns}}` won't resolve. State the choice in the coverage table.