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

package/README.md

@@ -73,7 +73,7 @@ codex plugin add postman@postman
 
 These commands track `main`; review the session-start hook in Codex after a
 manual install. The npx installer also approves the hook after each install or
-update, and moves an existing `codex-release` registration to `main`.
+update.
 
 ### Cursor
 
@@ -232,6 +232,12 @@ exercise failure paths.
 
 ## How Postman builds context
 
+`postman init` is idempotent and safe to run in any project. Run it before API
+engineering work to create the relevant local directories and make Postman
+skills available to guide the task, even if the project is already initialized.
+See [bootstrap](https://github.com/postmanlabs/postman-plugin/blob/main/skills/bootstrap/SKILL.md#start-with-postman-init) for setup
+options and workspace binding.
+
 Work done in a Postman folder produces artifacts: collection runs, lint
 results, request history, mock deployments. When that folder is connected to a
 Postman workspace after `postman init`, those artifacts are published to it as

package/mcp.pi.json

@@ -6,8 +6,8 @@
       "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
       "headers": {
         "X-Source": "postman-pi-plugin",
-        "X-Plugin-Version": "0.4.1-rc.0",
-        "User-Agent": "postman-pi-plugin/0.4.1-rc.0"
+        "X-Plugin-Version": "0.5.0-rc.0",
+        "User-Agent": "postman-pi-plugin/0.5.0-rc.0"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.4.1-rc.0",
+  "version": "0.5.0-rc.0",
   "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, Factory Droid, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/api-engineer/SKILL.md

@@ -30,8 +30,7 @@ guesswork each time work resumes.
    even when the provider is already chosen: those details help you assess fit and
    implement reliably without relying on remembered API behavior or loading a
    full vendor specification.
-   Existing workspace resources can supply maintained contracts and mocks; the
-   Context Graph can identify consumers and dependencies outside the checkout,
+   Context Graph can identify consumers and dependencies outside the current repo,
    helping you focus investigation before traversing more repositories.
 5. When you run or test code that calls other services, or are asked how it
    behaves when one of them fails, use **api-simulation**, which runs that code
@@ -44,20 +43,25 @@ guesswork each time work resumes.
    be diffed, reviewed, and reused in Git and CI. Use **bootstrap** when setup or
    workspace bindings are unresolved: reuse an existing local layout, pull the
    current service's existing workspace, or initialize a new project when neither
-   exists. `postman init` scaffolds files using an agent-scoped session without a
-   normal Postman login.
-7. Another service's collection, environment, or mock can be added as a dependency
+   exists.
+7. `postman init` gives API engineering work a ready state. It scaffolds local structure: `postman/`
+   directories for API artifacts. It installs skills in `postman/skills` folder with guidance on  designing, implementing, and validating APIs.
+   The command is idempotent and safe to rerun in an initialized project.
+   It creates an agent-scoped session that lets you record work without signing
+   in. You can claim that work later if you create an account.
+8. Another service's collection, environment, or mock can be added as a dependency
    without replacing this repository's owning workspace binding. Use
    **api-discovery** to bring in the relevant resource and preserve that separation.
-8. Publishing validated local changes to the bound workspace makes them available
-   for future work and teammates with access. Because `postman workspace push`
-   changes shared state, obtain user consent before pushing; an existing request
-   to publish those changes supplies that consent. For publication tied to reviewed
-   PR merges, see **ci-integration**.
-9. When requests need credentials, Postman secret variables let them resolve the
+9. Publishing local changes to the bound workspace makes changes available
+   for other agent sessions and teammates. Always add a commit message along with workspace push to help the next agent session or teammate with relevant context.
+10. A Postman workspace is a place to capture context. Use this information as prior
+    knowledge of work done before. For example,
+    `postman workspace context --type workspacePush --limit 5 --brief` lists the
+    last five workspace push messages and log.
+11. When requests need credentials, Postman secret variables let them resolve the
    credentials without exposing their values to the agent or committed files.
    See **variables**.
-10. When implementing or debugging webhooks, use **webhook-testing** to
+12. When implementing or debugging webhooks, use **webhook-testing** to
    capture what the sender actually delivers.
    Can also be used when the need is to forward incoming events
    to a local handler and replay captured requests after fixes;

package/skills/api-simulation/SKILL.md

@@ -16,9 +16,12 @@ credentials and leave side effects. A simulation runs that code over real
 HTTP, the same way in CI, and its log shows what each dependency was asked.
 
 Do only what the task needs. If a `.sim.yaml` in `postman/simulations/`
-already covers it, run that one. One request through the changed path proves
-a change; build failure variants only when asked how the code fails or when
-it must survive a failure.
+already covers it, run that one, and read the `<name>.context.md` beside it
+first: it holds the commands, the preconditions and the failures earlier runs
+hit, so reading it costs less than rebuilding any of that from the `.sim.yaml`
+and the handlers. One request through the changed path proves a change; build
+failure variants only when asked how the code fails or when it must survive a
+failure.
 
 `postman simulation` needs CLI 1.70.0 or later (`postman --version`; an older
 CLI answers `postman simulation -h` with its general help).
@@ -34,6 +37,11 @@ CLI answers `postman simulation -h` with its general help).
   the contract will do; one that invents responses can send the caller down a
   path the real service never would. In a mock you build, answer `501` for calls this path
   doesn't make: a `404` reads to the caller like a real "not found".
+- **Bring in each mock you don't own as a dependency first, then build the
+  simulation over them.** `postman dependency add mock <name-or-id>` declares
+  it in `.postman/resources.yaml` and materialises it under
+  `postman/.dependencies/`, and the member's `path:` points there; `-w
+  <workspace>` resolves a name from the workspace that owns it.
 - **Prefix each mock's `pm.state` keys with its name.** As of CLI 1.73.0,
   members of a local run read each other's keys, so two mocks storing
   `orders` overwrite each other.
@@ -41,18 +49,17 @@ CLI answers `postman simulation -h` with its general help).
 ## Running it
 
 The run is a server that never exits, so a foreground command never returns.
-Start it in the background with an explicit port, its log in a file:
+Start it in the background, its log in a file:
 
 ```bash
 postman simulation run postman/simulations/checkout-dev.sim.yaml --port 4900 --output ndjson > sim.ndjson 2> sim.err &
 ```
 
-Without `--port`, a busy 3000 silently becomes a random port and every base
-URL points at nothing. It's up when `sim.ndjson` has a `listening` event; a
-start-up error is in `sim.err`. It listens on 127.0.0.1 only, so a caller in
-a container or VM can't reach it. Stop it with
-`pkill -INT -f "simulation run <file>"`; `kill $!` leaves it running,
-because the `postman` launcher ignores the signal. Nothing reloads: restart
+`--port` is optional. It's up when `sim.ndjson` has a `listening` event; a
+start-up error is in `sim.err`. That event carries the bound port and each
+member's address, so take the base URLs from it rather than from the port you
+asked for. Stop it with
+`pkill -INT -f "simulation run .*<file>.sim.yaml"`. Nothing reloads: restart
 it after a mock edit.
 
 Point the caller at it without changing what the code does once deployed.
@@ -60,10 +67,30 @@ Under path routing, swap only the host and keep the path:
 `https://catalog.internal.example.com/v2` becomes
 `http://127.0.0.1:4900/catalog/v2`; a dropped `/v2` is the usual cause of a
 `404`. A hard-coded base URL should read an environment variable with
-today's value as the default. If the code mustn't change at all,
-`simulation run --proxy` reaches the members through `HTTPS_PROXY` instead;
-it applies no conditions, and passes any other host through to the real
-service.
+today's value as the default. If the code mustn't change at all, run it
+behind the proxy instead, below.
+
+## Through a proxy, when no base URL can change
+
+`simulation run <file.sim.yaml> --proxy` puts the members behind a local
+forward proxy that answers for the dependencies' own hostnames, so the code
+keeps the base URLs it ships with. Any other host passes through to the real
+service. Reach for it when hostnames are hard-coded, built from config the
+change shouldn't touch, or owned by an SDK — and because nothing it answers
+for has to resolve, an internal hostname with no DNS record works.
+
+Read `postman simulation run --help` before driving it. The flags, what the
+caller's own process needs in order to reach the proxy, and what to do about a
+client that ignores it are all there and change with the CLI, so take them
+from the command rather than from here.
+
+Two things decide whether a proxied run proves anything. A member with no
+`origin:` in the `.sim.yaml` is never matched, so its traffic reaches the real
+service and a run can come up having intercepted nothing — `simulation create`
+copies that field from the mock's manifest, so editing the manifest alone
+won't fix it ([reference/sim_yaml_schema.md](reference/sim_yaml_schema.md)).
+And conditions don't apply here: member `scenarios` are ignored, so failures
+need the one-port run.
 
 ## Reading the log
 
@@ -102,10 +129,27 @@ failure never reaches the mock and isn't logged, so judge it by what the
 caller did, and check the other members' logs for side effects, such as
 stock reserved and never released.
 
+## Its context document
+
+Every simulation is created with a `<name>.context.md` beside it, holding what
+running this one has taught: the commands that start it and prove it's up, the
+preconditions and what breaks when one fails, what it takes for granted about
+the dependencies themselves, the data seeded to test with, the failures earlier
+runs already hit, and what a passing run still doesn't prove. The `.sim.yaml` says what the simulation is, not how it behaves, so
+this is the file that saves a session the search. A new one is mostly
+`@todo`s, which are the questions a first real run answers.
+
+Every line passes one test — the repo doesn't already state it — so it stays
+about a screenful, and a claim carries the date and the run that established
+it, because the log it came from isn't committed. Its sections and conventions
+are in [reference/context_file.md](reference/context_file.md); read that
+before writing it back.
+
 ## Keeping it
 
-Commit your own mocks, the `.sim.yaml` and what `postman dependency add`
-changed, so the next session or CI reruns it in one command. Don't commit
+Commit your own mocks, the `.sim.yaml`, its context document and what
+`postman dependency add` changed, so the next session or CI reruns it in one
+command. Don't commit
 `postman/.dependencies/`: a copy goes stale when its owner updates theirs,
 and `postman dependency install` restores it. Don't commit `sim.ndjson`: the
 CLI redacts common auth headers and fields, but other headers and bodies are
@@ -136,3 +180,9 @@ or hung, the run proved nothing; say so and why. Say what a pass proves,
 your code against these stand-ins rather than the real services, what still
 needs the real service before release, and where each mock came from,
 including when you skipped the owner's.
+
+Then write the run back into `<name>.context.md`, so the next session starts
+where this one ended: the `@todo`s it answered, whatever it found wrong, a
+precondition you had to discover, what broke and why, and which members served
+or stayed silent — the last is a line every run adds, so a member silent across
+several runs reads as a pattern rather than a one-off.

package/skills/api-simulation/reference/context_file.md

@@ -0,0 +1,159 @@
+# `<name>.context.md`
+
+The handoff document beside a simulation: `postman/simulations/checkout.sim.yaml`
+gets `checkout.context.md`, and a foldered simulation keeps both in its folder.
+`simulation create` and the Postman app write it from what they already know,
+`simulation update` renames it with the simulation, and `simulation delete`
+removes it. An existing one is never overwritten, because it holds what earlier
+sessions learned.
+
+It is prose for whoever works here next, human or agent. Nothing parses it, so
+there is no schema to satisfy — but the generated headings and the
+`<!-- begin:observations -->` markers are what a reader and the next write
+expect to find, so keep them.
+
+Keep it to the generated sections plus `## What didn't work`, in Markdown,
+under about a screenful, so the line that matters is the one a reader lands on
+rather than one they have to search for.
+
+## What the generated file contains
+
+A fresh file states the simulation's name, the date, its members and the hosts
+they stand in for, and the run command for this simulation's own path.
+Everything needing someone who has actually run it is left as an `@todo` HTML
+comment, so a half-filled file reads as half-filled instead of as fact.
+
+| Section | Holds |
+| --- | --- |
+| Header | Generation date and what the mocks came from. |
+| `## Purpose` | What the simulation stands in for and what work it unblocks. Generated as the member list and a pointer to the handlers; needs hindsight, so it is the last thing to rewrite. |
+| `## Execution` | The commands, in order: start the simulation, start the service pointed at it, prove it is up, count what got called, stop. The generated block leaves the service's own command, the proof request, the port and the log path as `@todo`. |
+| `## Assumptions` | Every precondition someone had to discover, what the simulation takes for granted about the dependencies' own behaviour, the seeded data worth reusing, and what the simulation cannot reproduce. Each is a dated claim, the consequence of it not holding, and how it was established. |
+| `## Observations` | One dated line per run, newest first, between the `begin`/`end` markers: which members took traffic and which took none. A summary, not a request log, and a failure goes in `## What didn't work` instead. |
+| `## What didn't work` | Failures this simulation has already hit, a dated line each: what broke, the signature you'd recognize it by, where it surfaced, and the cause. Not generated — add the heading at the end, after `## Observations`, the first time a run gives you one. |
+
+`## Observations` and `## What didn't work` both accrete, so a run is visible
+in the file after the next one; `## Purpose`, `## Execution` and
+`## Assumptions` are rewritten in place, since they describe the simulation as
+it stands rather than a run. Each accreting section is bounded: `## What didn't
+work` keeps the ten most recent, a line staying until a run shows it fixed, and
+`## Observations` the five most recent runs. Past that the oldest go.
+
+A run that keeps its line is how a pattern becomes visible — a member silent
+for three runs running is worth more than the same fact seen once.
+
+Don't restate what the generated file already says: its `## Assumptions` ships
+with the ones that hold for every simulation.
+
+## What earns a line
+
+Write what running it taught you, and only that. Each line passes one test:
+the repo doesn't already state it. That leaves five kinds of thing, and they
+are the file's whole value:
+
+- **A precondition you had to discover** — the setting, the service, the
+  cleanup a run needs before it works at all. In `## Assumptions`.
+- **A failure and its cause**, with where it surfaced, so the next session
+  recognizes it instead of debugging it again. In `## What didn't work`.
+- **What the run takes for granted about a dependency itself** — that an
+  operation is idempotent, that a timeout means nothing committed, what order
+  events arrive in. A mock answers these whether or not anyone checked, so its
+  answer is a belief your code now relies on. In `## Assumptions`.
+- **What the simulation can't reproduce, and what nobody has settled**, so a
+  passing run is read for what it actually proves. In `## Assumptions`.
+- **What the last run served**: which members took traffic, which stayed
+  silent, and why. In `## Observations`.
+
+For anything the repo does state — routes and request shapes, valid actions,
+auth mechanics, each mock's hosts, config flags — name the file that holds it,
+the way the generated `## Purpose` points at the handlers, and let the reader
+go there. One source stays true; a copy here drifts, and this file gets
+committed, so a named file is also how a credential stays out of it.
+
+Write statements that stay true between runs. Counts, timings and coverage
+belong to the run that produced them, so leave them in the log and keep the
+pattern here: "every member served except `workspace`" rather than a tally.
+
+## How a line carries its evidence
+
+The log a claim came from isn't committed, so the line is all the next session
+gets. Date every claim in `## Assumptions` and `## What didn't work`, and say
+where it came from when a run didn't show it: `(observed 2026-10-22)` for what
+a run established, `(reasoned 2026-10-22, src/payments/client.ts)` for what was
+read rather than run.
+
+A failure also carries the signature the next session will recognize it by —
+the error text, the status, the member that sent it — since that is what
+someone matches a new failure against. Quote the error itself, never a
+response body. For the rest, name the committed file that holds it: the
+handler that threw, the mock example captured from the real service, the test
+that reproduces it. Not the run's log, which is wherever that run redirected
+output and which the next run overwrites.
+
+A good `## Assumptions` is a claim, its consequence and its date; a good
+`## Observations` is a few lines; a good `## What didn't work` is one line per
+failure:
+
+```markdown
+## Assumptions
+
+- **`payments` treats a retried charge as idempotent on `Idempotency-Key`.**
+  If it doesn't, the retry path charges twice. Nobody has settled it and the
+  mock answers as though it does. (reasoned 2026-10-22, the mock's handler)
+- **Redis holds no `EVENT_BATCH` key when a run starts.** A leftover one
+  crashes the aggregation flush before any request is sent. (observed
+  2026-10-22)
+
+<!-- begin:observations -->
+2026-10-22: every member served except `workspace`, which the service never
+calls in development, and `god`, which models no endpoints.
+2026-10-18: same, and `payments` served only `POST /charges`.
+<!-- end:observations -->
+
+## What didn't work
+
+- 2026-10-22: the aggregation flush crashed on start —
+  `TypeError: batch.map is not a function` in `src/events/flush.ts`, from a
+  stale Redis `EVENT_BATCH` key an earlier run left behind. Not a simulation
+  error, so the log shows nothing.
+- 2026-09-30: `payments` answered `501` for `POST /refunds` — the mock models
+  no refund path, so a run that reaches it proves nothing about refunds.
+```
+
+## Working with it
+
+Read it before starting. An observed claim holds until your run contradicts
+it; a reasoned one is a hypothesis, so check it, cheaply, when your run depends
+on it. Check the assumptions and anything recorded about what a run doesn't
+prove before concluding that something works. A claim this run contradicts is
+a finding to report, not to quietly route around.
+
+What it already answers, it answers: `## Execution` holds commands that ran,
+and `## Assumptions` holds preconditions someone already established, so both
+are usable as they stand rather than as a starting point to rebuild from. The
+code you are about to change still needs reading; the setup around it is what
+this file is for. A session that reads the document and then repeats the
+search it was meant to replace has paid for it twice.
+
+Then leave it truer than you found it:
+
+- Replace the `@todo`s your run can answer, and delete each one you replace.
+- Correct what you found wrong. Say what it is now, not what it used to be.
+- Add the precondition you had to discover, or the thing the simulation turned
+  out not to reproduce, as another dated claim-and-consequence pair.
+- Add what broke and why to `## What didn't work`, and delete the lines there
+  your run showed fixed.
+- Add this run's summary to the top of the `## Observations` block, read from
+  the simulation's log, and drop the oldest line past five.
+
+A run that only confirms the file still adds its `## Observations` line.
+
+## Rules
+
+- Leave another session's assumptions and limits standing unless your run
+  contradicted one: not exercised is not the same as not true.
+- Keep this file for how the simulation behaves, and let the `.sim.yaml`
+  speak for what it is.
+- Rewrite `## Purpose` when the simulation's scope genuinely changed.
+- Prefer deleting a line to adding one. Everything here is something the next
+  session must either trust or re-check.

package/skills/api-simulation/reference/sim_yaml_schema.md

@@ -8,8 +8,11 @@ Read this when writing or debugging a `.sim.yaml` by hand.
 simulation: checkout-dev               # required: the name
 routing: path                          # path (default) or header
 mocks:                                 # required: one entry per member
-  - routeKey: catalog                  # lowercase letters, digits, - and _
-    path: ../mocks/catalog/config.yaml # a mock's config.yaml, or a .js handler
+  - name: catalog                      # optional display name
+    routeKey: catalog                  # lowercase letters, digits, - and _
+    origin:                            # optional: hostnames, for --proxy
+      - catalog.internal.example.com
+    path: postman/mocks/catalog        # a mock's folder, config.yaml or handler
     scenarios:                         # optional: conditions, below
       - overrides:
           conditions:
@@ -17,7 +20,17 @@ mocks:                                 # required: one entry per member
 ```
 
 Run the `.sim.yaml` rather than a simulation id: a run by id drops every
-member's conditions (CLI 1.70.0–1.73.0).
+member's conditions (CLI 1.70.0–1.73.0), and `--proxy` takes no id at all,
+since the file is what declares the hostnames.
+
+`simulation create` writes each `path:` relative to the repository root, the
+directory holding `postman/`, and puts the simulation in a folder of its own
+(`postman/simulations/checkout-dev/checkout-dev.sim.yaml`) so its
+`<name>.context.md` sits beside it; the app records that document in a
+`context:` ref. Reading is broader than writing — a path relative to
+`postman/simulations/`, to the file, absolute or `~/`, naming the folder or
+the manifest inside it, all resolve — and an unresolvable one names every
+directory it looked in.
 
 ## Conditions
 
@@ -38,6 +51,23 @@ member's conditions (CLI 1.70.0–1.73.0).
 - A `latency` request is served and logged, with a `duration` that leaves
   out the delay.
 
+## `origin`
+
+The hostnames a member answers for under `--proxy`, and the only thing that
+decides which member a proxied request reaches.
+
+`simulation create` copies `origin` from the mock's manifest
+(`origin: api.stripe.com`, a string or a list).
+
+A scheme and port are stripped (`https://API.Stripe.com:443` →
+`api.stripe.com`). An unmatchable value — a path left on a copied URL, a
+wildcard — is warned about and skipped, leaving the member working; two
+members claiming one hostname fails the run. A member whose mock declares
+none has no `origin` key, since `origin: []` would reach the actual service instead of the mock.
+
+Under `--proxy` the members run on throwaway ports, so a manifest's `port` is
+ignored.
+
 ## The log (`--output ndjson`)
 
 One JSON event per line on stdout; notices go to stderr, so keep them apart.

package/skills/application-testing/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: application-testing
+description: Sets up, runs, debugs, and interprets results from `postman application test` — the Postman layer that runs your Playwright tests, captures their network traffic, matches it against a collection contract, runs pm.test assertions, and publishes results to Application Inventory. Covers the Postman side of the integration only — not Playwright test authoring or Playwright failures unrelated to capture. Use when the user asks to "set up application testing," "test my application with Postman," "connect my Playwright tests to Postman," "capture network traffic from Playwright," "Playwright tests are running but nothing shows up in Postman," "why isn't application testing capturing anything," "exclude certain requests from capture," "generate a collection from my app's traffic," "set up application testing in CI," "what API coverage do my e2e tests have," "which APIs are my Playwright tests not hitting."
+---
+
+# Application Test
+
+## Overview
+
+**Requires a Playwright project in the repository.** Without Playwright e2e tests there is nothing to capture — Playwright is the only supported runner.
+
+`postman application test` does not send its own requests. It:
+1. Spawns your Playwright test command (e.g. `npx playwright test`)
+2. The capture plugin intercepts network traffic and writes it as artifacts
+3. The CLI reads those artifacts, matches each request against your collections, and runs any `pm.test` assertions saved in the matched items
+4. Publishes results to Application Inventory in your Postman workspace
+
+The question it answers: **did my app's actual HTTP calls conform to the collection contract?** Not "does this endpoint respond correctly" — for that, use `postman collection run`.
+
+**Application Inventory** is where results are published — a Postman dashboard that records each run's Playwright test results alongside captured/matched/assertion counts, giving you a combined view of test health and API contract conformance across runs.
+
+---
+
+## Prerequisites
+
+**All `postman app` commands must be run from the repository root** — that is where `postman.config.cjs`, `.postman/resources.yaml`, and `postman/collections/` are expected to live.
+
+Assess each prerequisite against the current state of the repository before taking any action. Most will already be satisfied in an established project; only act on what is actually missing.
+
+### Playwright project
+
+This skill applies only when the repository has Playwright e2e tests. Verify that a `playwright.config.*` file exists and `@playwright/test` is listed as a project dependency. If neither is present, stop — there is nothing to capture and this skill does not cover Playwright setup.
+
+### Authentication
+
+Publishing results to Postman requires credentials. Authenticate only when workspace publishing is needed:
+
+- If `POSTMAN_API_KEY` is in the environment, run `postman login --with-api-key "$POSTMAN_API_KEY"`. This is the expected path in CI and agentic contexts.
+- If the key is not available, surface the gap to the user — do not initiate `postman login` in an agentic context, as it requires a human to complete a browser flow.
+
+If this run does not need to publish results (local debugging, dry run), authentication can be skipped by passing `--report-events false`.
+
+### Workspace link
+
+Publishing to Application Inventory requires a workspace binding. Check `.postman/resources.yaml` for a `workspace.id`. Reason about whether publishing is actually needed for this task before treating a missing workspace as a blocker:
+
+- If publishing is needed and the workspace is missing, load the `bootstrap` skill to set it up. In a non-interactive context this must be done locally first, then `.postman/resources.yaml` committed.
+- If publishing is not needed, pass `--report-events false` and proceed.
+
+### Capture plugin
+
+Network traffic capture requires the `postman-playwright` package to be installed and the Playwright config wrapped with `withPostman()`. Before attempting any setup, check whether it is already configured — `postman app setup-capture --dry-run` shows the current state without touching files.
+
+Decide what action (if any) is needed based on what the dry run reports:
+
+- Already configured → no action needed.
+- Not configured → run `postman app setup-capture --yes`. If automatic patching fails (non-standard config export patterns), fall back to manual installation: install `postman-playwright` as a dev dependency and wrap the config export with `withPostman()`.
+
+**Legacy pattern:** If the project uses `attachNetworkCapture()` in spec files instead of `withPostman()`, that is still supported — do not re-run setup. The CLI detects it automatically. Only migrate to `withPostman()` if the user asks to upgrade.
+
+### Server reachability
+
+`postman app test` spawns Playwright, which drives the live application — servers must be running before the command starts.
+
+Check `playwright.config.*` for a `webServer` entry. If present unconditionally, Playwright manages server startup automatically. If absent or conditional (e.g. gated on an env var), verify the servers are reachable before running. If they are not, check `webServer.command`, `package.json` scripts, and any README for the startup command, and surface it to the user.
+
+---
+
+## Running
+
+Before constructing any command, run `postman app test --help` to confirm the available flags for the installed CLI version. Do not guess flag names.
+
+**No `postman.config.cjs` yet** — the first run generates and saves `postman.config.cjs`, writing these choices as the defaults for all future runs. Confirm both with the user before running:
+
+- *Test command*: check `package.json` scripts for a project-specific test command (e.g. `npm run test:e2e`). Present what you find and ask the user to confirm — the CLI defaults to `npx playwright test` when a Playwright config is found, but do not assume that is what they want.
+- *Collection*: check `postman/collections/` and list what is available. Ask the user which collection to use. If none exist, ask whether to generate one from captured traffic.
+
+Once confirmed, run `postman app test` with the appropriate flags (e.g. `--target-collection <path>` or `--generate-collection`) — the CLI generates and saves `postman.config.cjs` automatically. Do not write the config file manually.
+
+Running `postman app test` without a collection in a non-interactive context exits with code 2 unless a collection source is provided explicitly.
+
+**`postman.config.cjs` exists** — the config is the source of truth. Run `postman app test` without extra flags. Individual config values can be overridden per-run without editing the file; consult `postman app test --help` for the override flags.
+
+**Capture-only mode** — when the goal is to stage and review traffic before committing a collection manually, there is a mode that skips collection matching and writes captured traffic as a collection to disk. Use this only as a review step, not the normal run path.
+
+---
+
+## Config File (`postman.config.cjs`)
+
+Lives at the **repository root**. The generated file includes comments explaining every field — read it for the full reference. It stays current with the CLI version installed in the repo.
+
+To edit config for common needs:
+- **Change the test command** — update `command`
+- **Add or change a collection** — update `targets.default.collections`
+- **Exclude noisy requests** — add `filters` (urlPatterns, methods, headers)
+- **Rewrite URLs before matching** — add `transformers` (config entries that normalize staging/proxy prefixes before the CLI matches captured URLs against the collection)
+- **Multiple named environments** — add entries under `targets`
+
+A **target** is a named set of collections + optional environment. The `default` target is used when no `--target` flag is passed. Individual values can be overridden per-run without editing config — consult `postman app test --help` for the override flags.
+
+---
+
+## Debugging
+
+**If a flag in this skill is unrecognized** (e.g. `--yes`, `--generate-collection`, `--dry-run`) or the behaviour described here doesn't match what you see, check the CLI version first:
+```bash
+postman --version
+```
+This skill targets the latest CLI release. If the version is outdated, load the `bootstrap` skill for installation and update steps, then re-run. The `--help` output for each command shows the flags actually available in the installed version.
+
+Read the CLI error output first — it names the specific failure and what to fix.
+
+### Requests show "not matched" in the summary table
+
+Run with `--verbose --no-report-events` to see the unmatched URLs without publishing a diagnostic run to Application Inventory. Then:
+
+- Wrong collection selected — check `targets.default.collections` in config or override with the target-collection flag.
+- URLs have a staging prefix or proxy path — add a `transformers` entry in `postman.config.cjs` to rewrite them before matching.
+
+---
+
+> **Note — Exit code:** The CLI exits with the **test runner's exit code** (Playwright's), not the Postman assertion pass/fail count. A run where Postman assertions fail but all Playwright `expect()` calls pass will exit 0. If you need CI to fail on Postman assertion failures, check the summary table output or the published results.
+
+---
+
+## Critical Rules
+
+1. **`postman application test` captures traffic; it does not drive requests.** The test runner (Playwright) drives the app; this command observes and asserts. If no test runner is running, nothing is captured.
+2. **`not matched` is not a test failure — it is a coverage gap.** Requests the CLI cannot find in a collection run no assertions and do not affect the exit code. A high not-matched count means the collection is incomplete for the traffic the app generates.
+3. **Transformers run before matching, not before capture.** The raw URL is stored; the transformer rewrites it for the matching step only. Use this to normalise staging/prod URL differences without losing the original for debugging.
+4. **Results are published per run.** Each invocation creates a new entry in Application Inventory. Pass `--report-events false` for dry runs or local debugging you do not want recorded.
+
+## Anti-patterns
+
+- **Capture-only mode is for reviewing traffic before committing to a collection** — use it when you want to inspect what the app generates before deciding on a collection structure. It is not a substitute for `--generate-collection`, which generates, tests, and saves to config in one step when no collection is configured.
+- **Do not run `postman app init`** — it is deprecated. `postman app test` runs the same setup on first use.
+- **Do not manually write `postman.config.cjs`** — the CLI generates it automatically on first run when you pass `--target-collection` or `--generate-collection`. Writing it by hand bypasses the CLI's generation logic.
+- **Do not combine capture-only mode with a target collection** — capture-only skips collection matching entirely; passing a collection alongside it has no effect and signals a misunderstanding of the mode.
+
+## Verification
+
+State captured / matched / not-matched / assertion counts from the summary table. Note whether results were published to Postman (`View results:` URL present) or kept local. If debugging a "not captured" issue, confirm which capture format was detected (Playwright JSON report or legacy NDJSON) and which directory the CLI scanned.
+
+Postman docs: https://learning.postman.com/docs/postman-cli/postman-cli-application/#postman-app-test

package/skills/bootstrap/SKILL.md

@@ -11,6 +11,17 @@ 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