@postman/postman-plugin 0.2.2 → 0.3.0

package/dist/source.js

@@ -5,15 +5,25 @@ export const GIT_URL = `https://github.com/${REPO}.git`;
 export const BRANCH = 'main';
 /** Unpinned, so `pi update` moves it with each `latest` release; test/pi-package.test.js checks the name. */
 export const PI_SOURCE = 'npm:@postman/postman-plugin';
-/** Must stay byte-identical to the shim in opencode/README.md; test/routes.test.js enforces it. */
+/**
+ * This repo's default branch, whose root package.json names the OpenCode entrypoint. Not a `#semver:` range: npm reads a
+ * version from any tag ending in one, so the installer's `@postman/postman-plugin@<version>` tags would match it too.
+ */
+export const OPENCODE_SPEC = `github:${REPO}`;
+/** The first OpenCode release of each major that installs `OPENCODE_SPEC`, found by bisecting the harness in opencode/scripts/test-plugin-add.js. */
+export const OPENCODE_MINIMUM = { 1: [1, 14, 33], 2: [2, 0, 4] };
+/** Pre-`plugin add` installs: a clone of the repo plus this one-line loader file. Must stay byte-identical to what those installs wrote, or the installer stops recognizing them. */
 export const OPENCODE_SHIM = "export { default } from '../postman-plugin/opencode/src/index.ts';\n";
 /** Pinned: this third-party CLI writes Kimi's plugin store for us, and an unpinned npx would run whatever is latest. */
 export const PLUGINS_CLI = 'plugins@1.3.4';
 // A git transport (not `file://`, which names a local path), optional user-info, then
 // GitHub's host and its `/`, or the scp-style `git@github.com:` form with no scheme.
-const GITHUB_PREFIX = /^(?:(?:https?|ssh|git|git\+ssh|ssh\+git|git\+https):\/\/)?(?:[^@/]+@)?github\.com[:/]/, 
-// User-info in a URL, or before an scp-style `host:path`; the conventional `git@` is kept.
-URL_USER_INFO = /^([a-z][a-z+.-]*:\/\/)(?!git@)[^@/]+@/i, SCP_USER_INFO = /^(?!git@)[^@/:]+@(?=[^/:]+:)/;
+const GITHUB_PREFIX = /^(?:(?:https?|ssh|git|git\+ssh|ssh\+git|git\+https):\/\/)?(?:[^/]*@)?github\.com[:/]/, 
+// User-info in a URL, or before an scp-style `host:path`. Greedy, because a password may hold an unescaped `@` and a
+// URL's host starts after the last one.
+URL_USER_INFO = /^([a-z][a-z+.-]*:\/\/)([^/?#]*)@/i, URL_USER_INFO_IN_TEXT = /([a-z][a-z+.-]*:\/\/)([^/?#\s]*)@/gi, SCP_USER_INFO_IN_TEXT = /(^|[\s"'`(=])([^/:\s"'`(=]*)@(?=[^@/:\s]+:)/gm, SCP_USER_INFO = /^()([^/:]*)@(?=[^@/:]+:)/, 
+// The conventional `git@` names no credential and is kept.
+withoutUserInfo = (match, before, info) => (info === 'git' ? match : before);
 function normalize(source) {
     return source.trim().toLowerCase()
         .replace(GITHUB_PREFIX, '')
@@ -26,5 +36,9 @@ export function isSameRepo(source, repo) {
 }
 /** Strips a URL's user-info, where a token would be, so a source can be printed. */
 export function redact(source) {
-    return source.replace(URL_USER_INFO, '$1').replace(SCP_USER_INFO, '');
+    return source.replace(URL_USER_INFO, withoutUserInfo).replace(SCP_USER_INFO, withoutUserInfo);
+}
+/** Strips the user-info of every URL in a command's output, which can echo a spec it was given. */
+export function redactText(text) {
+    return text.replace(URL_USER_INFO_IN_TEXT, withoutUserInfo).replace(SCP_USER_INFO_IN_TEXT, withoutUserInfo);
 }

package/dist/system.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { redact } from './source.js';
 // A missing file, or a path through something that isn't a directory. Anything else,
 // such as a file that exists but can't be read, must not pass for "absent".
 const ABSENT = ['ENOENT', 'ENOTDIR'];
@@ -30,8 +31,9 @@ function execute(file, args, env) {
         child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
     });
 }
+/** Formats a command for logs and failure messages, with the user-info of any URL in it redacted. */
 export function formatCommand(command, args) {
-    return [command, ...args].map((part) => (/^[\w@./:=~-]+$/.test(part) ? part : JSON.stringify(part))).join(' ');
+    return [command, ...args].map((part) => redact(part)).map((part) => (/^[\w@./:=~-]+$/.test(part) ? part : JSON.stringify(part))).join(' ');
 }
 export function createSystem({ dryRun = false, log = (line) => console.log(line) } = {}) {
     const env = process.env, platform = process.platform;
@@ -85,6 +87,17 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
                 throw error;
             }
         },
+        async readDir(dir) {
+            try {
+                return await fs.readdir(dir);
+            }
+            catch (error) {
+                if (ABSENT.includes(error.code ?? '')) {
+                    return [];
+                }
+                throw error;
+            }
+        },
         async probe(command, args) {
             return execute(await resolve(command), args, env);
         },
@@ -108,6 +121,12 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
                 await fs.rm(file, { recursive: true, force: true });
             }
         },
+        async rename(from, to) {
+            log(`  rename ${from} ${to}`);
+            if (!dryRun) {
+                await fs.rename(from, to);
+            }
+        },
         log
     };
 }

package/hooks/session-start-context.md

@@ -3,7 +3,7 @@ You have the Postman plugin.
 
 Before responding to any non-trivial API engineering task — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API or Postman Flow — load the `postman:api-engineer` skill and follow it. It is the default entry point and routes to the specific postman skills from there. Pure questions and trivial one-line edits don't need it.
 
-When the intent is already specific, you may enter directly into the relevant skill instead: `postman:bootstrap` (link this repo to a Postman workspace), `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`.
+When the intent is already specific, you may enter directly into the relevant skill instead: `postman:bootstrap` (link this repo to a Postman workspace), `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`, `postman:variables` (where a value or secret belongs and how to reference it).
 
 If you were dispatched as a subagent to execute a specific task, ignore this block — `postman:api-engineer` governs the orchestrating session, and it already shaped your dispatch.
 

package/mcp.pi.json

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

package/package.json

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

package/skills/api-discovery/SKILL.md

@@ -116,13 +116,29 @@ current `postman login` session, in that order.
 
 ## After discovery: reusing what was found
 
-`dependency add <type> <nameOrId>` formally adds a collection, environment,
-or mock found in another workspace as a dependency of the current one —
-the step after `search` finds something worth reusing (e.g., feeding
-`application test`'s contract matching), rather than copying it in by hand. It
-takes a Postman entity ID. If the Context Graph identifies a service or API to
-reuse, locate its collection with `search` first, then pass that entity ID to
-`dependency add`.
+Finding another service's workspace does not make it the workspace for the
+current repository. `workspace pull` is for working on the service that owns
+that workspace, from that service's repository. If the service is only a
+dependency, or the user only wants to inspect one of its resources, keep the
+current repository connected to its own workspace and use the dependency
+feature instead.
+
+Use `postman dependency add <type> <name-or-id>` to declare and download the
+selected resource rather than copying it by hand or pulling the other
+service's entire workspace. Supported types are `collection`, `environment`,
+and `mock`. Pass the entity ID returned by `search`, or use the entity name;
+when resolving a name in a specific workspace, add `--workspace
+<workspace-id>`. If the Context Graph identifies only a service or API, locate
+the concrete entity with `search` first.
+
+Dependencies are recorded in `.postman/resources.yaml` and downloaded under
+`postman/.dependencies/`, so the copy works locally straight away. Use
+`postman dependency list` to inspect declarations, `postman dependency
+install` to download declared dependencies after a clone or in CI, `postman
+dependency update` to refresh them from Postman, and `postman dependency
+remove <name-or-id>` to delete a declaration and its downloaded files. The
+`list`, `install`, `update`, and `remove` commands accept `--type <type>`;
+`install` and `update` can also target one declared dependency by name.
 
 ## Reference
 

package/skills/api-documentation/SKILL.md

@@ -10,11 +10,25 @@ 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 it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, **collection-schema-v3**.
-Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or 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)
@@ -31,4 +45,8 @@ Examples (in a Postman collection) are an excellent way to capture sample API re
 
 ## 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 instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.
+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.

package/skills/api-engineer/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: api-engineer
-description: Default entry point for API engineering work — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
+description: Makes coding agents faster and more accurate with fewer tokens when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
 ---
 
 # 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 -> pushing to cloud -> sharing with others.
-5. Don't jump straight into implementation. Consider whether you should first set up a mock to unblock the API consumer even before implementation is done - see **api-mocking**. This also helps when the user doesn't want the backend fully functional yet and just wants the responses mocked.
-6. Don't push to the cloud workspace (`postman workspace push`) without user consent. The recommended way to push to the cloud is a CI step on PR merge - see **ci-integration**.
+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. For an existing cloud workspace,
-   `postman workspace pull <id>` connects it and materializes its collections,
-   environments, and specs locally. When no cloud workspace exists, `postman
-   init --no-cloud` initializes the local structure. Work against those files,
-   validate them, and push only with user consent; sharing an already-bound
-   workspace means `workspace push`, not creating a duplicate. See
-   **bootstrap** for the lifecycle decision table.
+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**.

package/skills/api-mocking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-mocking
-description: Stands up a fake backend that behaves like a real API — from a collection or an OpenAPI spec, running locally or pushed to Postman's cloud for a durable URL — plus request-time scenario and status-code overrides for testing failure paths. Use when the user asks to "mock this API," "create a mock server," "fake the backend," "run tests without hitting the real API," or "simulate an error/out-of-stock response." Covers `postman mock`. Depends on bootstrap for the workspace id only once a mock is pushed to the cloud (`-w`, or the workspace linked in `.postman/resources.yaml`) — generating and running a mock locally needs nothing from bootstrap.
+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.
 ---
 
 # API Mocking
@@ -9,25 +9,29 @@ description: Stands up a fake backend that behaves like a real API — from a co
 
 This skill covers the Postman CLI (`postman mock`) for **Code Mocks** — the
 code-based mock product. It is not the postman-app UI (Local Mode sidebar,
-Agent Mode tools, Simulations), nor the older classic/collection mocks that
+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 cloud and deploying a
+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 (cloud definition) ──`deploy`──▶
+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 cloud. The exception is `generate -w`, which creates the mock in a
+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
@@ -42,7 +46,7 @@ skip the repo copy.
      the default handler from the source in place, keeping the existing name,
      port, and scenarios. `--update` still needs the `SOURCE`; it cannot be
      combined with `--output`.
-   - `-w <workspaceId>` saves the mock to a cloud workspace *instead of* the
+   - `-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.
@@ -66,18 +70,18 @@ skip the repo copy.
    `mock run` it again.
 4. **Push it, if it needs to leave your machine.**
    `postman mock push ./postman/mocks/NAME` is safe to re-run — `Created` the
-   first time, `Updated` after — and records the cloud mapping in
+   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 CLOUD_ID -s SLUG -y` prints
+   `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 CLOUD_ID` (table or `--json`)
+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
@@ -86,34 +90,58 @@ skip the repo copy.
 7. **Tear down.**
    - Local: `postman mock delete ./path --yes` — refuses while that mock is
      **running** locally; stop `mock run` first.
-   - Cloud: `postman mock delete CLOUD_ID --yes` — refuses while the mock is
+   - 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.
-   Cloud delete doesn't touch `.postman/resources.yaml`; drop that line by hand
+   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 cloud id.
-- **`mockServerId`** — a different value from `mock get CLOUD_ID` (table or
+  `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 cloud command fails closed:**
+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 cloud ID (gated); `mock list` is gated only when called
+   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 cloud — `-w` at
+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`.
@@ -132,8 +160,8 @@ on `collection run`.
 ## Verification
 
 A mock isn't done because `generate` or `run` exited 0 — hit it with
-`postman request` and check the actual status/body, or `mock get CLOUD_ID
---json` for a cloud one, then state whether it ended up local or cloud, and
+`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

package/skills/api-simulation/SKILL.md

@@ -0,0 +1,186 @@
+---
+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.
+---
+
+# 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
+```
+
+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.**