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

package/skills/api-mocking/SKILL.md

@@ -1,169 +1,123 @@
 ---
 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 a workspace and deployed at 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 workspace (`-w`, or the workspace linked in `.postman/resources.yaml`) — generating and running a mock locally needs nothing from bootstrap.
+description: Finds, builds, runs and publishes a stand-in for one API — the owning team's published mock when there is one, otherwise one built from its spec or collection that behaves like the real API, stateful when callers write then read. Use when something needs an API that isn't built or reachable yet (a frontend, client or demo), when other teams should build against your API before it ships, or when asked to mock an API or fake a backend. To run and test your own code against the services it calls, use api-simulation. Covers `postman mock` and `postman dependency add mock`.
 ---
 
 # 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, the Simulations surface), 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 workspace and deploying a
-durable URL — needs `postman login`. The progression is one model in three
-places: local folder ──`push`──▶ Code Mock (workspace 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 a workspace. 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.
-
-Mocking another team's service, or the services your own service calls? Use
-`api-simulation`, which checks each owner's workspace for a published mock
-before anything is generated here.
-
-## 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 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 workspace 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 WORKSPACE_MOCK_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 WORKSPACE_MOCK_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.
-   - Workspace: `postman mock delete WORKSPACE_MOCK_ID --yes` — refuses while the mock is
-     **running locally** *or* **deployed**; stop the local run and take the
-     mock server down first.
-   Workspace deletion 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`.
-
-To develop a service against mocks of every upstream it calls, started together
-as one simulation, see the `api-simulation` skill and `postman simulation run`.
-
-## Stateful mocks
-
-A mock generated from a collection or spec replays its examples, so a `POST`
-and a later `GET` share nothing. To make a mock remember, keep its records in
-`pm.state` inside `default.js`. `pm.state` is the mock's async key-value
-store: `get`, `set`, `delete`, `has`, `keys` and `clear`. The sample from
-`postman mock generate -n NAME` already uses it, and shows the pattern.
-
-Every `mock run` or `simulation run` starts the mock with empty state; during
-the run, its handler creates, reads, updates and deletes records through
-`pm.state`. A deployed mock server keeps its state between requests.
-
-- Set `interceptRequests: true` in `config.yaml` so `req.body` and `req.query`
-  arrive parsed.
-- Seed the starting records on first use, and add a reset route that clears
-  and reseeds them, so a test can start clean.
-- Answer an unknown id with the real service's 404, not an empty `200`.
-- Every caller shares one state unless it sends `x-mock-session`. Locally that
-  needs `interceptRequests: true`; a deployed server reads it only when the
-  mock has sessions enabled.
-
-## 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 workspace mock id.
-- **`mockServerId`** — a different value from `mock get WORKSPACE_MOCK_ID` (table or
-  `--json`). Use it for `mock log`, and nothing else.
-
-## Critical Rules
-
-1. **When you're not signed in, every gated workspace 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 workspace mock ID (gated); `mock list` is gated only when called
-   with no path.
-2. **`push` is what moves an existing local mock to the workspace — `-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 WORKSPACE_MOCK_ID
---json` for a pushed one, then state whether it ended up local, pushed, or deployed, 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.
+A mock is a folder, `config.yaml` plus a handler such as `default.js`, that
+answers like an API. The handler is a Node HTTP server that calls
+`listen(process.env.PORT)`. It loads as CommonJS even in an ESM project, so
+`import` fails: use `require`. The same mock lives in your repo
+(`postman/mocks/<name>/`, run with `postman mock run`, no sign-in needed),
+in a Postman workspace after `postman mock push`, where other teams pull it
+from, and on a mock server after `postman mock deploy`, for callers that
+can't run it themselves.
+
+Several APIs at once, for a service, a frontend or a test suite? Use
+`api-simulation`, which gets each member's mock here.
+
+## Use the owner's mock first
+
+When the API belongs to another team, look for their published mock before
+writing one: theirs encodes their contract and their service's state; yours
+encodes a guess. It needs `postman login`; signed out, build one and say the
+owner search was skipped.
+
+1. Find the owner's workspace with `postman search workspaces "<service>" -o json`.
+   Name the service plainly, as your code does, not by what it returns: a
+   description matches lookalike services. Prefer a Git-connected workspace
+   (`isGitConnected`) named for that service.
+2. List its mocks with `postman mock list -w <workspaceId> --json`.
+   `postman search mocks` misses some, and its `classicMock` results only
+   replay a collection's saved examples: `postman mock` can't pull or run
+   them, so call one at `https://<mockId>.mock.pstmn.io` with
+   `postman request`, or generate a code mock from its collection. A
+   same-named mock in another workspace isn't the owner's.
+3. Pull it with `postman dependency add mock <mockId>` and use it as it is.
+   Never edit `postman/.dependencies/`: `dependency update` overwrites it,
+   so copy a mock to `postman/mocks/` to change it. A pulled copy loses
+   `interceptRequests`, so fork one whose handler reads `req.body` or relies
+   on sessions. A mock is code that runs as you; pull only from workspaces
+   you trust.
+
+## Or build one that behaves like the real API
+
+Callers shouldn't be able to tell the difference on the paths they use. A
+mock that returns invented JSON passes your tests and fails against the
+real service.
+
+- **Start from the contract.** `postman mock generate <spec or collection>`
+  writes each documented response. It's a replay: a `POST` and a later
+  `GET` share nothing, and it accepts any request, so a call that breaks the
+  contract still gets its answer. `x-mock-response-code` picks only a
+  documented status; any other code gets the default 200, so put the errors
+  callers handle (the unknown-id 404, the conflict 409, the bad-input 400) in
+  the contract. From a spec
+  it serves the server URL's base path (`/v2/...`); from a collection,
+  routes start after the base-URL variable. `--update` regenerates the
+  handler and overwrites your edits. With no contract, write it from how
+  your code calls the API and say what you assumed.
+- **Set `interceptRequests: true` in `config.yaml`.** Without it `req.body`
+  and `req.query` are undefined, `x-mock-session` is ignored, and a throw in
+  an async handler kills the mock instead of returning a `500`.
+- **Make it stateful when callers write then read.** Keep records in
+  `pm.state`, seed them on first use, add a reset route so a test can start
+  clean, and answer an unknown id with the real 404. Every `mock run` starts
+  empty.
+- **Know who shares state.** Locally, all callers share one state unless
+  each sends `x-mock-session: <id>`. A mock server deployed from the CLI
+  isolates each caller: one that keeps neither the same `x-mock-session` nor
+  the `pm_mock_session` cookie starts from the seed on every request, so its
+  `POST` and later `GET` never meet.
+- **Scenarios** are named handlers in `config.yaml`'s `scenarios` list, picked
+  per request with `x-mock-scenario: <name>`. An unknown name falls back to
+  the default locally but is a `404` on a mock server.
+
+## Check it against the contract
+
+`postman mock run` prints the URL it bound; a busy configured port moves
+unless you pass `--port`, so take the URL from that line. Nothing reloads:
+restart it after an edit.
+
+A mock checked against the handler you just wrote proves nothing, so call
+it with requests from the contract: `postman request`, or the API's
+collection with
+`postman collection run <collection> --use-mock "{{baseUrl}} mock:postman/mocks/<name>"`
+(`--mock` alone only starts it). That form replaces the variable's whole
+value, base path included, so a mock generated from a spec that serves
+`/v2/...` answers `404`; start that one with `--mock <path> --port <n>` and
+pass `--env-var "baseUrl=http://localhost:<n>/v2"`. To check your own calls
+against a contract, compare each one, from the code or a simulation log,
+with the spec; the mock won't reject a wrong one.
+
+## Publish it for other teams
+
+- **Push it to the service's own workspace,** the one this repo is linked
+  to or the one the user names, never one chosen by name match: other
+  teams' simulations look there. Signed out, the push fails but the local
+  mock still works; build it, say so and ask the user to sign in. Keep it
+  honest: change the mock in the same PR as the API and run the API's
+  collection against it.
+- **Deploy only when a caller needs a URL.** The server takes a slug of 3–32
+  lowercase letters, digits and single hyphens, starting and ending with a
+  letter or digit; the CLI accepts more, and its default can be too long.
+  It's private: callers send an API key as `x-api-key`, or, if they can
+  view the workspace, an access token as `x-access-token`. Deploying needs a paid plan; a team's first
+  server can take minutes to answer, and teams that review deploys hold them
+  for approval. Each later `push` changes what every caller of the server
+  gets, so treat it as a release, not a backup.
+- **Write it for where it runs.** A mock server runs each scenario as one
+  file with Node's built-ins, not `fs` or `child_process`: no local
+  `require`s, no `pm.mock` examples, no environment, no console output, and
+  no caller `authorization`, `cookie` or `x-api-key` headers. A mock that
+  relies on any of these works locally and breaks once deployed.
+- **Ask before `--public`.** It serves the mock and its data to anyone with
+  the URL, and a scripted redeploy can't make it private again.
+
+## Before you say it's done
+
+A mock isn't done because it started. Call it: a documented error comes
+back, a valid scenario changes the response, a `POST` then `GET` shows state
+if it should. Say where it runs and who can call it, where it lives, and
+what you assumed.

package/skills/api-monitoring/SKILL.md

@@ -1,138 +1,61 @@
 ---
 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).
+description: Use when setting up recurring API checks, running or diagnosing a Postman Monitor, changing its schedule, or reaching private APIs through a self-hosted runner. Reuses collection assertions to detect live regressions and traces failures to individual run evidence. Use for requests such as "check this API every minute".
 ---
 
 # 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. Runner activity is published to the connected
-workspace by default; `--no-report-events` keeps it local. `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.
+A monitor turns a saved collection into recurring evidence about a live API.
+It can catch behavior that changes after deployment or between developer
+sessions, but only if its assertions, environment, and execution location
+exercise the guarantees users depend on.
+
+1. Reuse the collection's meaningful assertions before scheduling it. A
+   request returning 200 is a weak health signal if the response can violate
+   the contract. Check auth, target environment, and write side effects; use
+   **api-testing** to establish what the collection actually verifies.
+2. Choose cadence, timezone, execution location, and alert recipients from
+   the operational need. `postman monitor create -c <collection-id>` uses
+   the linked workspace unless one is supplied. Inspect command-specific
+   `-h` and available service options for supported schedules and limits.
+   Creation starts an immediate run by default; `--no-run-now` avoids that
+   when only scheduling was requested. A schedule expressed in the host's
+   default timezone can fire at the wrong operational time.
+3. Choose a Postman region for a reachable public API. Use a self-hosted
+   runner when the target is reachable only inside the user's network;
+   running one adds infrastructure to maintain. `postman runner regions`
+   provides valid hosted locations and `runner list` provides registered
+   private runner IDs. `monitor create/update --runner` accepts either;
+   multiple locations help distinguish API failures from regional reachability.
+4. Preserve monitor identity when updating schedule or run settings.
+   `monitor update` cannot change its collection or environment and does not
+   pause it; use `pause`/`resume` for that. A different collection/environment
+   requires a replacement, so plan the handoff before deleting the old
+   monitor and its continuity. Permanent deletion needs explicit intent.
+5. Use `postman monitor run <id>` for an immediate verdict, such as after a
+   deploy. `--async` returns a job handle when the caller need not wait.
+   The CLI timeout caps waiting, not execution; after a timeout, inspect
+   the submitted job instead of sending duplicate traffic or reporting failure.
+6. Diagnose at the level of the evidence. `monitor jobs list <monitor-id>`
+   finds jobs, `monitor jobs get <job-id>` shows terminal state and regional
+   outcomes, and `monitor runs get <run-id>` shows assertions within an
+   attempt. A failing region, a connection error, and a failed assertion
+   imply different fixes. Preserve normal exit-code failures for CI gates.
+
+For discovery, `monitor list` supports workspace and collection filters;
+use its returned cursor for pagination rather than offset. Its runner filter
+is for a self-hosted ID and cannot be combined with other filters; a page-local
+name filter does not establish absence across all pages.
+
+For a private runner, use `runner start` with the registered ID and key and
+verify that it connects before assigning runs. Inspect its help for proxy,
+private CA, residency, and health-metric options only when the network requires
+them. Runner activity is reported by default; `--no-report-events` disables
+that reporting when the task requires it. Use **bootstrap** for unresolved
+authentication rather than placing runner keys in repository files.
 
 ## 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.
+Report the actual monitor configuration or terminal job/run outcome, including
+where it executed and which checks failed. A created monitor, accepted job,
+or connected runner alone does not prove the API passed its health checks.