@postman/postman-plugin 0.3.0 → 0.4.0

package/skills/api-documentation/SKILL.md

@@ -1,52 +1,47 @@
 ---
 name: api-documentation
-description: Generate filesystem-first agent friendly api documentation that you can share with your teammates without hassle. Use when the user asks to "publish API docs," "generate documentation for this API," "put this on the API Network," "share a docs link for this collection or spec," or "why do my docs look empty." 
+description: Use when defining or improving an API contract, generating documentation from a collection or OpenAPI spec, publishing API docs, or sharing a documentation link. Makes auth, inputs, responses, and examples reusable by callers, tests, and mocks. Use for requests such as "publish API docs".
 ---
-The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.
 
 # API Documentation
-When working on any API task, the first step is to establish and capture the contract.
-API documentation can be done in two predominant ways:
-1. through a Postman collection,
-2. with an OpenAPI spec
 
-It is recommended to create both. They serve different, complementary use
-cases, and the Postman CLI can generate one from the other. Use the artifact
-that represents the current source of truth rather than recreating its
-operations by hand. Postman collections are human-friendly and enable other
-capabilities such as mocks, monitors, SDKs, and specifications. Collections
-created or edited directly on disk use the v3 format described by
-**collection-schema-v3**.
-
-Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
-
-## Generate a collection from a specification
-
-When an OpenAPI specification already defines the contract, generate a Postman
-collection from it in one command:
-
-```bash
-postman spec generate collection <spec-path-or-id> -n "<collection-name>"
-```
-
-## Good practices for API design
-
-See [reference/rest-api-best-practices.md](reference/rest-api-best-practices.md)
-for the practices well-documented APIs tend to already follow: resource
-naming, HTTP method/status-code usage, error response shape, versioning,
-pagination, filtering, auth, idempotency, and backward compatibility. A
-spec or collection that already follows these renders documentation with
-nothing left to fix.
-
-### Examples
-Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
-1. anyone can look at them to see how your API behaves,
-2. they can be used to generate a mock from your collection in a single command.
-
-## Workflow
-1. Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
-2. Choose the source of truth — a Postman collection, an OpenAPI specification,
-   or both. Recommend both when their complementary uses benefit the task.
-3. If the specification is authoritative, generate the collection with
-   `postman spec generate collection` instead of manually duplicating its
-   operations.
+A maintained contract gives callers enough information to integrate without
+reading the implementation. Keeping descriptions and examples beside the API
+artifacts lets the same knowledge support documentation, tests, and mocks,
+with changes reviewable alongside code.
+
+1. Start from the existing source of truth. An OpenAPI spec describes the
+   interface for tooling; a Postman collection adds runnable requests,
+   examples, and assertions. Maintain both when both uses matter, with an
+   explicit direction of generation or synchronization so they do not become
+   competing definitions. Local edits need **bootstrap** only when setup or
+   bindings are unresolved.
+2. When the spec is authoritative, reuse its operations with
+   `postman spec generate collection <spec-path-or-id> -n "<collection-name>"`.
+   Inspect the generated result before replacing an existing collection:
+   maintained scripts and examples carry knowledge beyond endpoint shapes.
+3. Describe what changes a caller's decision: required versus optional inputs,
+   auth and scopes, response guarantees, pagination, retryable failures, and
+   side effects. Derive guarantees from the agreed contract or verified
+   behavior; label unresolved design choices instead of inventing them.
+   Use [REST design guidance](reference/rest-api-best-practices.md) when a
+   design choice affects usability or compatibility, not to redesign an
+   unrelated interface while filling a documentation gap.
+4. Save examples that clarify consequential cases, including relevant errors.
+   Examples become inputs for mocks as well as explanations for readers;
+   a success-only example can hide the failure path callers must handle.
+   Use **collection-schema-v3** for local collection edits and **variables**
+   to keep credentials out of reusable requests and examples.
+5. Choose delivery by audience. Local artifacts support Git review;
+   publishing to the bound workspace makes them available to teammates with
+   access (see **bootstrap**). A workspace push does not itself publish a
+   public docs page or change permissions. For a public documentation link,
+   use **postman-mcp-server**'s documentation workflow and the available
+   publishing tool; establish the intended audience before public exposure.
+
+## Verification
+
+Check that the edited artifact parses and its examples agree with the
+contract. For a publication, inspect the resulting page and report its actual
+link and visibility; a successful upload alone does not show readers usable
+documentation. State any behavior that remains undocumented or unverified.

package/skills/api-engineer/SKILL.md

@@ -1,29 +1,84 @@
 ---
 name: api-engineer
-description: Makes coding agents faster and more accurate with fewer tokens when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
+description: Use when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API. Guides decisions using reusable local API contracts, tests, and mocks, plus organization-wide dependency context, and routes to the relevant Postman skills. Use for requests such as "implement this endpoint".
 ---
 
 # API Engineer
 
-## Foundations
-Postman's skills, CLI, and Context Graph help coding agents go faster from development to production with higher accuracy and fewer tokens. Work from local files and workspace context first.
-
-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 -> updating the workspace context -> sharing with others.
-5. When the code you're changing calls other services over HTTP, use **api-simulation**: the Context Graph finds those dependencies, `postman dependency add mock <name-or-id>` pulls in each owner's mock that search finds (see **api-discovery**), and your real service runs against all of them on one port. For a stand-in backend with no real service of your own, use **api-mocking**. Mocks and simulations are persisted in your repo, so they're cheap to reuse when you resume.
-6. Don't push to the workspace (`postman workspace push`) without user consent. The recommended way to push 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. A quick overview of starting the work could be (more details in **bootstrap**):
-   -> if starting a new project: start by doing `postman init`. This scaffolds the relevant folders and provisions an agent-scoped session without requiring a normal Postman login.
-   -> if another service is only a dependency or something you want to inspect, use **api-discovery** and `postman dependency add <type> <name-or-id>` to add the relevant collection, environment, or mock. This materializes that entity under `postman/.dependencies/` and records it in `.postman/resources.yaml` without changing this repository's workspace binding.
-Work against those local files and validate them. When the repository is bound to a workspace, push to persist that context for future work and share it with others.
-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
-11. Postman secret variables let agents resolve user secrets without reading their values. See the **variables** skill.
-
-## 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**.
+Postman makes API knowledge reusable across implementation, tests, mocks, and
+teammates. Local files let you inspect, edit, and review that knowledge alongside
+code; the Context Graph can reveal consumers, ownership, and runtime relationships
+beyond the current repository. Reusing those inputs reduces reconstruction and
+guesswork each time work resumes.
+
+1. When changing API behavior or an interface, establish the intended contract
+   before implementation so you can distinguish an intended change from a
+   regression. Reuse the existing contract; update it where behavior changes.
+   Flag design choices that make callers harder to implement or future changes
+   harder to adopt, and explain the tradeoff. See **api-documentation**.
+2. Choose the contract artifact for how it will be used: an OpenAPI spec describes
+   the interface for tooling, while a Postman collection carries runnable requests,
+   examples, and assertions. Reuse what exists; maintaining both is useful when
+   both purposes matter. See **api-documentation**.
+3. Match verification to the behavior at risk. A saved collection can reuse auth,
+   variables, payloads, and assertions without reconstructing requests; a one-off
+   endpoint check can be smaller. Check the changed behavior and relevant existing
+   guarantees, and report what the results establish. See **api-testing**.
+4. When you need an API, its owner, or the impact of a change, use **api-discovery**.
+   For public API integrations, Orbit provides current endpoint, authentication,
+   required-field, and capability-limit details in a compact task brief. Use it
+   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,
+   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
+   for real against mocks of those services instead of stubs or the real
+   services. Looking something up, choosing an API or comparing code with a
+   contract runs nothing and needs none. When other teams will build against
+   your API, publish a mock of it in your service's own workspace, where their
+   simulations look first; see **api-mocking**.
+6. Keep specs, collections, environments, and mocks in local files so changes can
+   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
+   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
+   credentials without exposing their values to the agent or committed files.
+   See **variables**.
+10. 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;
+   use the capture URL as a subscriber to inspect events your API sends.
+
+Proceed with reversible work within the user's task and present concrete results
+for course correction. Recommend additional work only when it closes a material
+gap, such as an untested behavior or a consumer affected by an interface change.
+Decline unnecessary setup or scope and explain why it would not help the task.
+
+Important: If a CLI command says an operation isn't allowed because credits
+or usage are exhausted, or the current plan does not permit it, follow
+**bootstrap**'s "Subscription or usage limit" section instead of retrying or
+trying to find a workaround.
+
+## Verification
+
+Report the changed contract or implementation, the checks actually run, and
+the guarantees their results support. Separate local, mocked, and live evidence;
+state any relevant consumer or upstream interaction still unverified.
+
+If actual use exposes a CLI gap or misleading skill, see **bootstrap**'s
+"Reporting CLI and skill gaps" section so the defect can be addressed for future
+work.

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.