@postman/postman-plugin 0.1.1-rc.0 → 0.1.2

package/skills/api-documentation/reference/rest-api-best-practices.md

@@ -0,0 +1,47 @@
+# REST API Design Practices 
+
+- **Resource naming.** Nouns, not verbs, in the path (`POST /orders`, not
+  `POST /createOrder`). Plural collections, consistent casing, nesting
+  reflects real relationships and rarely goes past two levels deep.
+- **HTTP methods.** GET is read-only and safe to repeat. POST creates.
+  PUT replaces a whole resource and is idempotent. PATCH updates part of
+  one. DELETE removes and is idempotent. Never use GET to change state.
+- **Status codes.** 2xx for success (201 + `Location` on create, 204 for
+  no body), 4xx for client mistakes (401 vs. 403 vs. 404 vs. 409 vs. 422
+  each mean something distinct), 5xx for server failure. Inconsistent
+  codes are one of the most common sources of client bugs.
+- **Error responses.** One consistent shape across every endpoint, with a
+  stable machine-readable `code` plus a human-readable `message`, and all
+  validation failures returned together rather than one at a time.
+- **Versioning.** Decide the strategy (URI path like `/v2/users`, or a
+  version header) before the first breaking change forces the question.
+  A breaking change is a removed/renamed field, a changed type, or a
+  changed auth requirement — additive changes don't need a new version.
+- **Pagination.** Page/offset pagination is simple but can skip or repeat
+  items when the underlying data changes mid-list; cursor-based
+  pagination avoids that and holds up better for feeds and high-write
+  data. Either way, return the metadata a client needs to fetch the next
+  page without guessing.
+- **Filtering, sorting, searching.** Query parameters with names that say
+  what they filter/sort on, not internal field names.
+- **Auth.** API keys for server-to-server; OAuth bearer tokens when a
+  request needs to represent a specific user, scoped rather than
+  all-or-nothing. HTTPS always. Rate limits communicated through response
+  headers, not discovered by hitting them.
+- **Idempotency.** GET/PUT/DELETE are naturally or by-design idempotent;
+  POST isn't, so a client that might retry a POST (payments, especially)
+  needs an idempotency key the server can recognize on retry.
+- **Content type and shape.** JSON by default; keep response bodies flat
+  rather than deeply nested, and let a client ask for only the fields it
+  needs on large resources.
+- **Observability.** Log method, endpoint, status, and latency per
+  request; return a request ID in the response so a client's bug report
+  can be traced to server-side logs.
+- **Backward compatibility.** Add fields instead of changing or removing
+  them where possible. When something really must go, announce it, give
+  a migration path, and run the old and new versions side by side for a
+  window — a deprecation header on responses beats a changelog entry
+  nobody reads.
+- **Testing.** Beyond the happy path: auth failures, validation errors,
+  rate limiting, and retries — the same edge cases a thin API-readiness
+  score (see `ai-readiness`) tends to catch missing coverage for.

package/skills/api-engineer/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: api-engineer
+description: Default entry point for API engineering work — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
+---
+
+# API Engineer
+
+## Foundations
+1. Contract comes first. Establish and document the contract before starting implementation.
+2. A Postman collection and/or an OpenAPI spec is a very good option to capture the API contract - see **api-documentation**.
+3. Always validate the change against the contract you started with. Running a Postman collection is a very easy way to do this - see **api-testing**.
+4. Always propose next steps. Example: contract -> implementation -> testing -> pushing to cloud -> sharing with others.
+5. Don't jump straight into implementation. Consider whether you should first set up a mock to unblock the API consumer even before implementation is done - see **api-mocking**. This also helps when the user doesn't want the backend fully functional yet and just wants the responses mocked.
+6. Don't push to the cloud workspace (`postman workspace push`) without user consent. The recommended way to push to the cloud is a CI step on PR merge - see **ci-integration**.
+7. For high-quality API search results, use **api-discovery**.
+8. No is an acceptable answer. Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment.
+9. Prefer filesystem-first Postman workflows. For an existing cloud workspace,
+   `postman workspace pull <id>` connects it and materializes its collections,
+   environments, and specs locally. When no cloud workspace exists, `postman
+   init --no-cloud` initializes the local structure. Work against those files,
+   validate them, and push only with user consent; sharing an already-bound
+   workspace means `workspace push`, not creating a duplicate. See
+   **bootstrap** for the lifecycle decision table.
+10. When actual use exposes a concrete Postman CLI gap or a misleading skill, handle the user's task first — then use `postman feedback` to report the gaps/bugs. Exclude secrets, user data, and proprietary content
+
+## Dos
+1. Prove it works - validate the task against the contract. See **api-testing**.
+2. Just do it - never block on the human. When tempted to ask "should I do X?" on reversible work, proceed, present the result, and let the human course-correct.
+3. Fight for good API design. See **api-documentation**.

package/skills/api-mocking/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: api-mocking
+description: Stands up a fake backend that behaves like a real API — from a collection or an OpenAPI spec, running locally or pushed to Postman's cloud for a durable URL — plus request-time scenario and status-code overrides for testing failure paths. Use when the user asks to "mock this API," "create a mock server," "fake the backend," "run tests without hitting the real API," or "simulate an error/out-of-stock response." Covers `postman mock`. Depends on bootstrap for the workspace id only once a mock is pushed to the cloud (`-w`, or the workspace linked in `.postman/resources.yaml`) — generating and running a mock locally needs nothing from bootstrap.
+---
+
+# API Mocking
+
+## Overview
+
+This skill covers the Postman CLI (`postman mock`) for **Code Mocks** — the
+code-based mock product. It is not the postman-app UI (Local Mode sidebar,
+Agent Mode tools, Simulations), nor the older classic/collection mocks that
+serve saved collection examples from a `*.mock.pstmn.io` URL — that's a
+different product (the MCP `createMock` flow), not this skill.
+
+A **local** mock is two files on disk: `config.yaml` (name, port, scenarios) and
+`default.js` — a plain Node HTTP server, and the mock itself, not a wrapper
+around one. Generating, inspecting, running, and calling a local mock work for
+a logged-out guest. Only sharing it — pushing to the cloud and deploying a
+durable URL — needs `postman login`. The progression is one model in three
+places: local folder ──`push`──▶ Code Mock (cloud definition) ──`deploy`──▶
+Mock Server (the reachable URL).
+
+Default path: write a local folder, then `mock push` later if something other
+than you needs to hit it over the network (a teammate, CI elsewhere, a webhook
+sender). A purely local mock answering a `postman request` on your machine
+never needs cloud. The exception is `generate -w`, which creates the mock in a
+workspace only and writes no local files — use that only when you intentionally
+skip the repo copy.
+
+## Process
+
+1. **Generate.** `postman mock generate -n NAME` with no source scaffolds a
+   sample shopping-cart mock (`POST /cart/items`, `GET /cart`, `POST /checkout`)
+   — the fastest way to a server that already answers, useful whenever the
+   point is exercising mock *behavior* rather than a specific API's shape. Pass
+   a real source — `postman mock generate SOURCE -n NAME`, where `SOURCE` is a
+   collection file/directory or an `openapi.yaml` — when the endpoints need to
+   mirror an actual API. Either form writes `config.yaml` + `default.js` into
+   `postman/mocks/NAME/` (default port 4500).
+   - `postman mock generate SOURCE --update ./postman/mocks/NAME` regenerates
+     the default handler from the source in place, keeping the existing name,
+     port, and scenarios. `--update` still needs the `SOURCE`; it cannot be
+     combined with `--output`.
+   - `-w <workspaceId>` saves the mock to a cloud workspace *instead of* the
+     repository — it writes no local files and requires being logged in. Cannot
+     be combined with `--output`, `--force`, or `--update`. Prefer local
+     generate + later `push` when you still need `mock run` from a folder.
+2. **Run it.** `postman mock run ./postman/mocks/NAME` starts the server and
+   prints the bound URL (`... at http://localhost:PORT`). If the port in
+   `config.yaml` is taken and `--port` wasn't passed explicitly, it falls back
+   to a free OS-assigned port instead of erroring — read the real port off that
+   line rather than assuming the configured one. Naming `--port N` explicitly
+   makes a taken port a hard error; `--port auto` always picks a free one.
+3. **Call it.** Plain `postman request localhost:PORT/route` returns the
+   default scenario's response. Two headers can change that per-request, with no
+   restart: `x-mock-scenario: <name>` selects a scenario the mock defines
+   (valid names live in `config.yaml`); a name the mock doesn't define is not an
+   error — it falls back to the default scenario. `x-mock-response-code: <code>`
+   filters an endpoint's saved example responses to the one with that status, so
+   it only changes anything when that endpoint actually has an example for that
+   code — mocks generated from a collection/spec with multiple example statuses
+   honor it; the built-in sample mock has one response per route and ignores it.
+   A wrong route comes back as `Endpoint not defined`. There's no hot reload: a
+   `default.js` edit does nothing until you Ctrl+C the running server and
+   `mock run` it again.
+4. **Push it, if it needs to leave your machine.**
+   `postman mock push ./postman/mocks/NAME` is safe to re-run — `Created` the
+   first time, `Updated` after — and records the cloud mapping in
+   `.postman/resources.yaml`; commit that change. If a mock server is already
+   live for this mock, the push updates what it serves.
+5. **Deploy it, for a URL that outlives your terminal.**
+   `postman mock deploy CLOUD_ID -s SLUG -y` prints
+   `https://SLUG.mock.<team-domain>.postman.dev`. Deployed private by default —
+   callers need a Postman API key (`x-api-key`) — add `--public` only when the
+   mock should be reachable by anyone with the URL. `--auto-deploy` re-publishes
+   the live server automatically whenever the mock changes; even without it, a
+   later `push` already updates a live server, so you only re-`deploy` for the
+   first URL or after taking the server down.
+6. **See who's calling it.** `postman mock get CLOUD_ID` (table or `--json`)
+   returns `mockServerId`; feed that into `postman mock log MOCK_SERVER_ID` for
+   call entries (filter with `--method` / `--status` / `--path` / `--since` /
+   `--until` / `--limit`, or `--json`). An empty log means the URL genuinely
+   hasn't been hit — a rejected caller still shows up, recorded with its failing
+   status code.
+7. **Tear down.**
+   - Local: `postman mock delete ./path --yes` — refuses while that mock is
+     **running** locally; stop `mock run` first.
+   - Cloud: `postman mock delete CLOUD_ID --yes` — refuses while the mock is
+     **running locally** *or* **deployed**; stop the local run and take the
+     mock server down first.
+   Cloud delete doesn't touch `.postman/resources.yaml`; drop that line by hand
+   afterward or the repo keeps claiming a mock that's gone.
+
+To point real request/assertion runs at a mock instead of hand-editing
+base-URL variables, see the `api-testing` skill's `--use-mock`/`--mock` flags
+on `collection run`.
+
+## The two ids that matter
+
+- **Code-mock id** — the `id` in `config.yaml`, and the id that `push` and
+  `generate -w` print (often the same value). Use it for `get`, `deploy`,
+  `delete`, and `run` by cloud id.
+- **`mockServerId`** — a different value from `mock get CLOUD_ID` (table or
+  `--json`). Use it for `mock log`, and nothing else.
+
+## Critical Rules
+
+1. **When you're not signed in, every gated cloud command fails closed:**
+   `Authentication required. Run postman login or provide --api-key`, exit 1,
+   nothing half-done. (Signed in but lacking access fails differently — a
+   permission or missing-workspace error.) Whether a command is gated is decided
+   by what you pass it, not the verb — `mock get`/`mock run` take either a local
+   path (ungated) or a cloud ID (gated); `mock list` is gated only when called
+   with no path.
+2. **`push` is what moves an existing local mock to the cloud — `-w` at
+   `generate` time is optional, not a fork you must choose up front.** A mock
+   built as a guest can be pushed and deployed later with no rework. Do not
+   assume `generate -w` left a `postman/mocks/NAME/` folder to `run`.
+3. **`--public` on `deploy` is the one action here with real exposure** — it
+   stands up a server anyone with the URL can hit, with no API key. The default
+   (private) is the safe one; confirm intent before adding it.
+4. **To change a mock:** refresh it from a source with
+   `postman mock generate SOURCE --update PATH`, or edit `default.js` by hand
+   and restart `mock run`. Never pass a code-mock id to `mock log` — that
+   command takes a `mockServerId`.
+5. **`-w`/`--workspace` only exists on `generate`, `list`, `push`, and
+   `deploy`.** `get`, `run`, `log`, and `delete` already take a path or an id
+   that says where the mock is — there's nothing left for `-w` to resolve on
+   those.
+
+## Verification
+
+A mock isn't done because `generate` or `run` exited 0 — hit it with
+`postman request` and check the actual status/body, or `mock get CLOUD_ID
+--json` for a cloud one, then state whether it ended up local or cloud, and
+(if deployed) private or public. For a scenario check, confirm a *valid* name
+from `config.yaml` actually changed the response — a typo'd name falls back to
+the default, so a 200 alone proves nothing. For a status-code check, use an
+endpoint that has an example for that code (not the sample mock). A passing
+exit code from `request` is not enough.

package/skills/api-monitoring/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: api-monitoring
+description: Creates, schedules, and manages Postman Monitors — recurring checks against a live API — triggers ad hoc runs, inspects job/run history to diagnose failures, and hosts self-hosted execution runners for monitors on a private network. Use when the user asks to "set up a monitor," "run this monitor now," "check monitor results," "pause/resume a monitor," or "set up a runner for our internal APIs." Covers `postman monitor` (create, update, delete, list, get, pause, resume, run, jobs, runs) and `postman runner` (start, list, regions).
+---
+
+# API Monitoring
+
+## Overview
+
+A Monitor is a recurring, scheduled check against a live API. The CLI now
+owns its full lifecycle: `monitor create`/`update`/`delete`/`pause`/`resume`
+manage the schedule and configuration, `monitor list`/`get` discover and
+inspect existing ones, `monitor run` triggers an ad hoc run, and `monitor
+jobs`/`monitor runs` inspect what actually happened during a run. There is
+no remaining task here that has to go through the Postman app.
+
+`postman runner` is a separate, infrastructure-level concern: it starts a
+self-hosted execution agent so Monitor runs can reach APIs that live behind
+a private network Postman's cloud can't reach directly, and it lists the
+values (Postman regions or self-hosted runner ids) that `monitor
+create`/`update --runner` accepts.
+
+## Creating and scheduling a monitor
+
+`monitor create -c <collectionId>` is the minimum — name defaults to the
+linked collection's own name. Workspace comes from `-w`, or falls back to
+the workspace named in the local `.postman/resources.yaml` manifest;
+without either, creation fails. `--schedule <cron>` plus `--timezone`
+(defaults to the host machine's zone) set when it fires; `--runner`
+(repeatable) says where from — a Postman region name (`postman runner
+regions`) or a self-hosted runner's id (`postman runner list`), and both
+can be mixed in the same monitor. `--notify-email` (repeatable) and
+`--notification-limit` control failure alerts. The run itself is shaped by
+the same options as a collection run — `--retry` (service caps at 2),
+`--timeout`, `--delay`, `--strict-ssl`/`--insecure`,
+`--follow-redirects`/`--block-redirects`, and dataset iteration via
+`--dataset-id`/`--dataset-view-id`/`--iteration-count`/
+`--iteration-strategy`. Creation triggers an immediate run by default; pass
+`--no-run-now` to skip that.
+
+## Updating, pausing, and deleting
+
+`monitor update <monitorId>` takes the same schedule/runner/notification/
+run-option flags as `create`, plus `--clear-notifications` to wipe every
+recipient. It cannot change the linked collection or environment — delete
+and recreate the monitor instead — and it does not pause or resume; use
+`monitor pause`/`monitor resume` for that. `monitor delete <monitorId>`
+prompts for confirmation unless `-y`/`--yes` is passed, and is permanent.
+
+## Discovering and inspecting monitors
+
+`monitor list` filters by `-w`/`-c`/`--environment`/`--owner`/`--team`/
+`--active`. `--runner <id>` filters to a *self-hosted* runner id (not a
+Postman region) and can't be combined with the other filters. Page with
+`--limit`/`--cursor`; `--offset` is accepted by the service but silently
+ignored, so the CLI rejects it locally rather than returning a page that
+looks right but isn't — use `--cursor` from the previous page's response.
+`--columns` picks which fields show, `-f`/`--filter` matches on name within
+the page already returned (not a server-side search), and `--sort name|active`
+orders it. `monitor get <monitorId>` shows one monitor's full configuration.
+
+## Triggering a run
+
+`monitor run <monitorId>` runs an existing Monitor synchronously and prints
+the result — useful in CI to get a pass/fail right after a deploy rather
+than waiting for the next scheduled tick. `-t/--timeout` (default 15
+minutes) caps how long the CLI waits for completion; a timeout hit here is
+the CLI giving up on waiting, not the Monitor itself failing. `--async`
+submits the run and returns immediately with its job id and Postman URL
+instead of waiting at all — reach for this over a long `-t` when the caller
+doesn't need the verdict inline. `--json` prints only the verdict as JSON,
+for scripting. `-x/--suppress-exit-code` overrides the default
+fail-on-failed-run exit code, for a caller that wants to see failures
+without breaking a pipeline step.
+
+## Diagnosing a run
+
+`monitor jobs list <monitorId>` lists a monitor's recent jobs; `monitor jobs
+get <jobId>` reports one job's terminal state and its per-region run
+outcomes — a monitor with runners in multiple regions runs once per region
+per job. `monitor runs get <runId>` goes one level deeper: which test
+assertions ran during one attempt, which failed, and why. Reach for these
+instead of re-running blind after a `-t` timeout, or whenever the task is
+explaining *why* a monitor failed rather than just that it did.
+
+## Private (self-hosted) runners
+
+A private runner — the CLI's `runner regions` calls the same thing a
+"private-runner" value — is an agent you run inside your own network so
+Monitor traffic originates there instead of from Postman's cloud IPs. Reach
+for one only when the monitored API sits behind a VPN, firewall, or on-prem
+network that Postman's cloud can't reach directly; a public API should just
+use a Postman region (`--runner us-east`, etc.) since that needs no
+infrastructure of your own to run or maintain.
+
+`runner start --id <id> --key <key>` (from the Postman app) registers a
+runner that executes monitor runs from your own infrastructure instead of
+Postman's cloud. Extra
+flags cover the runner's own networking: `--region eu` for EU residency,
+`--proxy`/`--egress-proxy`/`--egress-proxy-authz-url` for outbound routing,
+`--ssl-extra-ca-certs` for a private CA, and `--metrics`/`--metrics-port`
+for a health-check endpoint. Analytics are sent by default; `--no-report-events`
+opts out. `runner list` shows the team's registered self-hosted runners —
+feed an id from here into `monitor create/update --runner` or `monitor list
+--runner`. `runner regions` lists the Postman-region and private-runner
+values valid for `--runner` on `monitor create`/`update`, including a
+static IP where one is configured — check here before guessing a region
+string.
+
+## Critical Rules
+
+1. **`update` can't move a monitor to a different collection or environment,
+   and doesn't pause/resume it.** Delete and recreate for the former; use
+   `pause`/`resume` for the latter.
+2. **A `monitor run -t` timeout is a wait cap, not a monitor failure.**
+   Don't report "the monitor failed" from a timeout without checking
+   `monitor jobs get`/`monitor runs get` (or the Postman app) for what the
+   run actually did after the CLI gave up waiting — or avoid the wait
+   entirely with `--async`.
+3. **`--runner` on `monitor create`/`update` takes a region name or a
+   self-hosted runner id — check `runner regions`/`runner list` before
+   guessing a string,** and don't suggest `runner start` unless the target
+   API genuinely isn't reachable from Postman's cloud.
+4. **`monitor list --offset` doesn't work — use `--cursor`,** and
+   `--runner` there can't be combined with the other filters.
+5. **`monitor delete` is permanent.** Confirm intent before passing `-y` to
+   skip its prompt.
+
+## Verification
+
+State the monitor/job/run id and the actual pass/fail result or
+configuration change, not just that the command exited. For `run`, state
+whether it completed synchronously or was submitted `--async` (a job id is
+not yet a verdict — resolve it with `monitor jobs get` before reporting a
+result). If a self-hosted runner was started, confirm it registered (the
+Postman app, or `runner list`, shows it as connected) before assuming
+monitor runs will route through it.

package/skills/api-testing/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: api-testing
+description: Runs tests against an API from the command line — a single ad-hoc request, a full collection of pm.test assertions, or matching real captured app traffic against a collection contract. Use when the user asks to "test this endpoint," "run this collection," "check the API still works," or "verify my app's requests match the contract." Covers `postman request`, `postman collection run`, and `postman application test`. Depends on bootstrap when the target is a cloud collection or workspace-bound environment; a bare URL or local collection needs nothing from bootstrap.
+---
+
+# API Testing
+
+## Overview
+
+Three tools, matched to what already exists:
+
+| Have | Use |
+| --- | --- |
+| Just a URL to check, with no saved request | `postman request` |
+| A request already saved in a collection | `postman collection run <collection-path> -i <request-id-name-or-path>` |
+| A collection with `pm.test` assertions saved in it | `postman collection run` |
+| A real app (browser flow, CLI, service) whose traffic should match a collection's contract | `postman application test` |
+
+Don't reach for the heavier tool when the lighter one already answers the
+question — a one-off endpoint check doesn't need a collection, and a
+collection run doesn't need Playwright.
+
+## `postman request` — over curl, not instead of testing
+
+A single request with Postman's resolution built in: `-e` resolves
+`{{variables}}` from an environment file the same way a collection run
+would, `--auth-*` flags cover basic/bearer/digest/oauth/aws/etc. without
+hand-building headers, and `--retry`/`--timeout` handle flaky endpoints.
+`--script-post-request` can run `pm.test(...)` assertions inline — the exit
+code counts *failed assertions*, not just HTTP status, so a 200 with a
+failing test still exits nonzero. Useful for a quick check or a CI health
+check; not the place to accumulate assertions that should outlive one
+command — those belong saved in a collection.
+
+Before constructing a URL, headers, auth, and body on the command line, look
+for a matching `*.request.yaml` under `postman/collections/`. If it exists,
+execute the saved request through its collection:
+
+```bash
+postman collection run "postman/collections/Orders API" -i "create order"
+```
+
+Do not copy the saved YAML fields into `postman request`; that bypasses the
+collection's inherited variables, auth, scripts, and maintained payload. The
+`postman request` positional target is a URL, not a `.request.yaml` path. When
+there is no saved request but its body already lives in a separate file, keep
+the file as the source of truth with `--body @path/to/payload.json` instead of
+inlining its contents.
+
+## `collection run` — the assertion suite
+
+Debugging a request's behavior during a run (why a `pm.test` failed, what a
+request actually sends) means reading the request's own YAML — see the
+`collection-schema-v3` skill for that file format before assuming a field's
+shape.
+
+Runs every request in a collection (or a subset via `-i`, repeatable),
+executing whatever `pm.test` scripts are already saved in it.
+`-d`/`--iteration-data` (or the beta `--iteration-data-dataset` +
+`--iteration-data-view` pair) drives data-driven runs across a CSV/JSON
+file or a Postman Dataset. `-r junit,html` for CI-consumable reports.
+`--use-mock`/`--mock` redirects the run at a mock instead of a real backend
+(see the `api-mocking` skill) — reach for this to test request/assertion
+logic without depending on a live service.
+
+## `application test` — contract-matching real traffic
+
+This doesn't send its own requests. It runs your existing test command
+(`--command "npx playwright test"`, or config-driven via
+`postman.config.cjs` targets), captures the network traffic that command
+generates, and matches/asserts it against your Postman collections —
+answering "did my app's actual calls conform to the contract," not "does
+this endpoint respond correctly." `--capture-only` skips the matching step
+entirely and just exports what was captured as a new v3 collection,
+organized by host — a way to bootstrap a collection from real traffic
+rather than authoring one from scratch. Results upload to Postman
+automatically after each run; `--report-events=false` skips that for a run
+that shouldn't be recorded.
+
+## Critical Rules
+
+1. **Don't reach for `application test` for something a plain
+   `collection run` covers.** It exists specifically for matching *captured*
+   app traffic (via Playwright or similar), not for driving requests itself.
+2. **`postman request`'s exit code reflects failed `pm.test` assertions, not
+   HTTP status alone.** A nonzero exit on a 200 response usually means a
+   post-request script assertion failed, not a network problem.
+3. **Assertions meant to be reused belong in the collection, not on the
+   command line.** A `--script-post-request` test on `collection run` runs
+   once and leaves nothing for the next person; save it as a `pm.test` in
+   the request instead.
+4. **`--use-mock` is the way to test without a live backend** — prefer it
+   over standing up ad hoc fakes or skipping tests that need a dependency.
+5. **Reuse a saved request instead of reconstructing it.** If a matching v3
+   request exists, use `collection run <collection-path> -i <request>`; reserve
+   `postman request` for genuinely ad-hoc requests.
+
+## Verification
+
+State the actual result (pass/fail counts, exit code), not just that the
+command ran. For `application test`, state whether it ran in match mode or
+`--capture-only` — they answer different questions and shouldn't be
+reported the same way.