@postman/postman-plugin 0.3.0 → 0.4.0

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.

package/skills/api-simulation/SKILL.md

@@ -1,186 +1,138 @@
 ---
 name: api-simulation
-description: The local development loop for a service that calls other APIs — find its dependencies in the code and the Context Graph, give each one a mock (the owning team's, or one generated from its contract), serve them together from one `.sim.yaml` on one port, run the real service against it, read the simulation's log to see what each dependency served, and ship it with the simulation in the PR. Can also inject latency, error, rate-limit or chaos per dependency. Use when the user is building or changing an endpoint that calls other services, or asks to "simulate my dependencies," "mock everything this service calls," or "run this end to end locally." Covers `postman simulation`. Builds on api-discovery for finding dependencies and their owners' mocks, and on api-mocking for the rest.
+description: Runs your code for real against stand-ins for the HTTP services it calls, served together as one environment on one local port or one deployed URL, whether that code is a service you're changing, a frontend, a test suite or a demo. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors ("what happens to a booking if the email service is down?"), by running each failure instead of reading the code. Applies even when nobody says mock or simulation. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.
 ---
 
 # API Simulation
 
-## Overview
-
-A simulation serves several mocks on one local port. Each member has a
-**routeKey**, its address: with `routing: path` (the default) a dependency
-lives at `http://localhost:<port>/<routeKey>`, and the routeKey is stripped
-before the mock sees the request. The service under test runs for real and is
-never a member.
-
-```yaml
-# postman/simulations/feeds-dev.sim.yaml
-simulation: feeds-dev
-routing: path
-mocks:
-  - routeKey: acs
-    path: ../mocks/acs/config.yaml
-  - routeKey: workspaces
-    path: ../.dependencies/mocks/workspace-service/config.yaml
+A simulation serves several mocks as one environment, each reached by its
+routeKey: as a path prefix by default, or as an `x-mock-slug` header when the
+caller's paths can't change.
+
+Run your code against it rather than stubbing its HTTP client in tests or
+calling the real services. A stub skips the client, config, timeouts and
+error handling that will run in production; the real services need
+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.
+
+`postman simulation` needs CLI 1.70.0 or later (`postman --version`; an older
+CLI answers `postman simulation -h` with its general help).
+
+## Building it
+
+- **Members are the code's HTTP dependencies.** Databases, queues and caches
+  aren't; run them locally. **api-discovery** can find calls made through
+  shared code; ask about the repo by its `git remote` name, because a close
+  name matches another repo.
+- **Each member needs a mock: see `api-mocking`,** which looks for the owning
+  team's published mock before building one. For a question, one built from
+  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".
+- **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.
+
+## 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:
+
+```bash
+postman simulation run postman/simulations/checkout-dev.sim.yaml --port 4900 --output ndjson > sim.ndjson 2> sim.err &
 ```
 
-Running a local `.sim.yaml` works signed out. Running one by id, the Context
-Graph, `search`, `dependency` and anything in a workspace need `postman login`.
-`postman simulation` needs Postman CLI 1.70.0 or later (`postman update`);
-earlier releases have only the older `postman simulate run`.
-
-## Commands
-
-Most commands work either on a local `.sim.yaml` or on a simulation in a
-workspace:
-
-| Command | With a `.sim.yaml` path | With a simulation id |
-| --- | --- | --- |
-| `create -n <name> --mock <ref>=<routeKey>` | Writes `postman/simulations/<name>.sim.yaml` from mock paths | Creates one in the workspace from mock ids (`-w`). Don't mix the two |
-| `list` | Lists `postman/simulations/` | `-w <workspaceId>` lists the workspace's |
-| `get <pathOrId>` | Reads the file | Fetches it |
-| `run <pathOrId>` | Serves the members on one port | Fetches the members, then serves them locally |
-| `push <path>` | Uploads each member mock, then the simulation, to the linked workspace. A member pulled with `dependency add` goes up as a copy | — |
-| `deploy <id>` | — | Serves it at a URL, **public by default** (rule 7). `--private` requires an API key |
-| `delete <pathOrId>` | Deletes the file, not its mocks | Deletes it and takes its URL down |
-
-## Process
-
-1. **Find what the change calls.** If a `.sim.yaml` in `postman/simulations/`
-   already covers the change, skip to step 4. Otherwise read the code path
-   you're changing: its HTTP clients, their base-URL settings, and any call
-   the change adds. Only HTTP dependencies become members; queues, databases
-   and caches run as real local instances. When signed in, check that list
-   against the Context Graph, which also sees calls made through shared code
-   and other repositories:
-   `postman context-graph ask "What services and APIs does <repo-name> call?" --wait`.
-   Use the repository's name from `git remote get-url origin`, not the
-   folder's: a wrong name answers "no dependencies", not an error. A call the
-   change adds isn't in the graph yet.
-
-2. **Get each dependency's mock from its owner first.** This needs
-   `postman login`; signed out, ask the user to sign in rather than writing
-   mocks (rule 5). For every dependency, in this order:
-   1. Find the owner's workspace:
-      `postman context-graph ask "Which Postman workspace holds the collections and mocks for <service>?" --wait`.
-      If the workspace it names has neither, find the owner's with
-      `postman search workspaces "<service>"`.
-   2. List that workspace's mocks:
-      `postman search mocks --filter "workspaceId=<id>"`. A name match in
-      another workspace is not ownership.
-   3. If the owner has one, pull it with `postman dependency add mock <mockId>`
-      and use the copy as it is, even if the owner also deployed it.
-   4. Only if the owner has none, make one: pull their collection with
-      `postman dependency add collection <id>` and run `postman mock generate`
-      on it (see `api-mocking`). Keep the endpoints this path calls and answer
-      `501` for the rest, so a missed call fails loudly. Make it stateful when
-      the change writes something and reads it back.
-
-3. **Compose the simulation.**
-
-   ```bash
-   postman simulation create -n feeds-dev \
-     --mock ./postman/mocks/acs=acs \
-     --mock ./postman/.dependencies/mocks/workspace-service=workspaces
-   ```
-
-   Each `=<routeKey>` names a member: lowercase letters, digits, `-` and `_`.
-   Schema: [reference/sim_yaml_schema.md](reference/sim_yaml_schema.md).
-
-4. **Run it and point the service at it.**
-
-   ```bash
-   postman simulation run postman/simulations/feeds-dev.sim.yaml --port 4900 --output ndjson > sim.ndjson 2> sim.err &
-   ```
-
-   Keep stderr out of `sim.ndjson` so every line parses; start-up errors land
-   in `sim.err`. It's up when the `listening` event lists each member's
-   address. Set each upstream base URL to `http://localhost:4900/<routeKey>`,
-   never to a mock server's URL.
-
-   Stop it with
-   `pkill -INT -f "simulation run postman/simulations/feeds-dev.sim.yaml"`:
-   every member stops, and the closing `summary` event counts the requests
-   served and failed. `kill $!` reaches only the `postman` launcher, which
-   ignores it, so the simulation keeps serving. In a terminal of its own,
-   Ctrl+C works too.
-
-5. **Develop and test, reading the simulation log after each call.** Call
-   the changed route on the real service with `postman request` or its
-   collection (see `api-testing`). Every request a member served is a
-   `request` event in `sim.ndjson`, with its `routeKey`, `method`, `path`,
-   `statusCode`, `duration` in milliseconds, and both bodies. Check that each
-   upstream call you expect is there, on the right member, with the status you
-   expect. Restart the service after a code change, and the simulation after a
-   mock edit. A response from the simulation itself means wiring, not code:
-   - `404 Unknown simulation member`: the path has no valid routeKey. The body
-     lists the valid ones. It isn't logged.
-   - `501`: an upstream call you haven't modelled yet. Add it to your own
-     mock. For a pulled one, fork it into `postman/mocks/` first.
-   - `502 Proxy error`: the member's handler crashed. See `sim.ndjson`.
-
-6. **Optionally, fail a dependency.** Worth doing when the change has to
-   survive an upstream that errors or is slow, but not required. Copy the
-   baseline `.sim.yaml`, give that member a condition, run the service
-   against it, and report what it did.
-
-   ```yaml
-     - routeKey: workspaces
-       path: ../.dependencies/mocks/workspace-service/config.yaml
-       scenarios:
-         - overrides:
-             conditions:
-               error: { status_code: 503 }
-   ```
-
-   The conditions are `latency`, `error`, `rate_limit` and `chaos`; the schema
-   has all four. Each applies to every route on that member, and the first to
-   fail a request ends it, so fail a dependency one way at a time. An injected
-   error, `429` or chaos failure never reaches the mock and isn't logged, so
-   judge it by what the service returned.
-
-7. **Ship.** Commit your mocks, the `.sim.yaml` files and
-   `.postman/resources.yaml`, but not `sim.ndjson`: it records request
-   headers and bodies, tokens included. After a clone,
-   `postman dependency install` restores the pulled mocks. Running the
-   simulation in CI is optional: start it as in step 4 before the test step,
-   and stop it after.
-
-## Critical Rules
-
-1. **The service under test is never a member.** If nothing real runs, use
-   `api-mocking`.
-2. **Unique routeKeys and an explicit `--port`.** A member's own `port:` is
-   ignored. Without `--port`, a busy 3000 silently moves to a random port.
-3. **Members share one `pm.state` store.** Two stateful mocks that use the
-   same key read and overwrite each other's records, so give each its own keys.
-4. **Only `overrides.conditions` inject faults.** A bare
-   `scenarios: - path: …/default.js` entry, as the Postman app writes, adds
-   none. `overrides.bypass` is ignored.
-5. **Never write or generate a mock for a dependency before searching its
-   owner's workspace.** A mock you write encodes your assumptions; the
-   owner's encodes their contract and their state.
-6. **Pull an owner's mock even when it's deployed.** Only members take faults
-   and log requests, and a private mock server needs an `x-api-key` your
-   service won't send. Never edit `postman/.dependencies/`:
-   `dependency update` overwrites it. To change a pulled mock, copy it into
-   `postman/mocks/` and call it a fork.
-7. **Confirm before a public deploy.** `simulation deploy` without
-   `--private`, or with `-y`, serves every member's mock to anyone with the
-   URL. Ask the user first; a local `run` needs no deploy at all.
-
-## Verification
-
-Starting is not the same as being used. Before you report, read the whole
-log: every member on the path should have `request` events with the statuses
-you expect. A member with none isn't wired or isn't on this path.
-
-Report:
-
-- **How the simulation performed:** for each member, the requests it served
-  and their statuses, and anything unexpected, such as a `501`, a `502` or a
-  member that was never called.
-- **Where each mock came from:** for each dependency, the owner workspace you
-  searched, what you found there, and whether its mock was pulled, forked or
-  generated here.
-- **What ran for real.**
+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
+it after a mock edit.
+
+Point the caller at it without changing what the code does once deployed.
+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.
+
+## Reading the log
+
+A passing test command doesn't show the dependency path ran: read
+`sim.ndjson`. A member with no `request` events isn't wired or isn't on this
+path. Some answers come from the simulation itself and mean wiring, not code:
+
+- `404 Unknown simulation member`: a base URL lost its routeKey, or a client
+  sent the wrong `x-mock-slug`.
+- `501`, or a generated mock's `404 Endpoint not defined`: a call the mock
+  doesn't model yet.
+- `502 Proxy error`: the member's process died, usually an async throw in a
+  mock without `interceptRequests: true`. It stays down and logs nothing
+  until you restart; run that mock alone with `postman mock run` to see why.
+
+## When a dependency goes down
+
+Run it rather than reason from the code: each way of going down takes a
+different path through the caller, and a stub skips the client code that
+picks the path. Fail the one dependency in each shape that matters, a run
+each, with the others answering normally:
+
+- **Unreachable:** point its base URL at a port nothing listens on.
+- **Hanging:** give its member a `latency` condition longer than the
+  client's timeout. If the client sets none, that is the finding: Node's
+  `fetch` waits about five minutes, so say so rather than wait it out.
+- **An error with a JSON body:** the `error` condition.
+- **An error with an HTML body,** as proxies send: a copy of its mock whose
+  default handler answers `500` with HTML. No condition can do this.
+
+Only `overrides.conditions` on a member change it. Members always serve
+their default handler and ignore `x-mock-scenario`, and a `scenarios` entry
+with just a `path`, as the Postman app writes, does nothing. Fields and the
+other conditions are in [reference/sim_yaml_schema.md](reference/sim_yaml_schema.md). An injected
+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.
+
+## 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
+`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
+logged as sent. In CI, `postman dependency install` needs `POSTMAN_API_KEY`,
+and `postman collection run <collection> --simulation <file> --port <n>`
+starts and stops the simulation around a collection run.
+
+`postman simulation push` uploads every member to the workspace, so ask
+first. It fails on a pulled member, which keeps its owner's `id:`; copy it to
+`postman/mocks/` and delete that line.
+
+## Rules
+
+1. **What you're testing is never a member.** It must run for real, or the
+   test only proves the mock.
+2. **Pull the owner's mock even if it's deployed.** Only members take
+   conditions and appear in the log, and a private mock server wants a key
+   your code won't send.
+3. **`simulation deploy` is public by default,** unlike `mock deploy`. Ask
+   before deploying without `--private`; a local run needs no deploy.
+
+## Before you say it works
+
+Claim nothing until what you're testing actually ran: a service printed
+that it's listening and answered your request, or the frontend or test
+suite finished, and its calls are in the log. If its start command exited
+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.