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

package/skills/api-mocking/SKILL.md

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

package/skills/api-monitoring/SKILL.md

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

package/skills/api-testing/SKILL.md

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

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: bootstrap
+description: Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.
+---
+
+# Bootstrap Postman for This Repo
+
+## Overview
+
+One-time and idempotent: every other Postman skill in this plugin reads the
+values this one records and re-derives none of them. Finding an existing
+`postman/` tree or an OpenAPI file is a signal to inspect, not to assume this
+repo is already set up.
+
+## Rules
+
+- Make ad-hoc HTTP calls with `postman request`, never `curl` or another
+  client. If the request already exists in a collection, preserve its saved
+  auth, variables, scripts, and payload by using `postman collection run
+  <collection-path> -i <request>` instead of reconstructing it on the command
+  line; see `api-testing`.
+- Never invent a subcommand or a flag. Run `-h` first and believe it.
+- Lint specs with `postman spec lint`, never `postman api …` — the API Builder
+  is deprecated in v12+ and the CLI prints no warning.
+- Local commands need no login; only commands that reach the Postman
+  workspace do. Don't force a login the task doesn't need.
+- A missing `postman` binary means install it. Route to `postman-mcp-server`
+  only after an install has been attempted and actually failed.
+- Never fabricate a workspace id, spec path, or collections directory. Report
+  the gap and stop.
+- Never echo an API key or session token into output, logs, or summaries.
+- "Present" is not "current": check the version and existing links before
+  setting anything up.
+- Wire up an existing repo only. Never scaffold a new API or a starter spec.
+- Write no host-specific paths — the same `skills/` directory loads on every
+  route.
+- Do not use `init` or `workspace create` to share or import a workspace that
+  already exists. Choose the direction of sync from the lifecycle table below.
+
+## Ask the CLI: `-h`
+
+The CLI is self-describing at different levels. Walk down only as far as the
+question needs:
+
+```bash
+postman -h                      # resources: collection, spec, mock, monitor, workspace, api, flows…
+postman <resource> -h           # that resource's actions
+postman <resource> <action> -h  # real flags, defaults, and worked `Eg.` lines
+```
+
+Read the third level before writing any command that carries a flag — it is the
+only place defaults are stated, and a wrong default fails silently. Live output
+is authoritative over any summary, including this file. There is also no single
+verb for "is the workspace linked and synced": run `postman workspace -h` and
+pick from what it prints.
+
+---
+
+# Process
+
+Three steps, in order. Stop at the first that fails and report which one.
+
+## 1. Resolve the CLI
+
+### 1.1 Check what is already there
+
+**Present, and at which version?**
+
+```bash
+command -v postman && postman --version
+```
+
+**Current?** Never blocking — no network is a normal answer. But don't call a
+feature missing without having made this comparison.
+
+```bash
+npm view postman-cli version
+```
+
+### 1.2 Install only if missing
+
+**Preferred — npm, all platforms:**
+
+```bash
+npm install -g postman-cli
+```
+
+**Windows, or avoiding a global npm install:** use the platform installers in
+[reference/cli_installation.md](reference/cli_installation.md). Every route puts
+`postman` on `PATH`.
+
+**Updating a copy that already exists:** use the same route that installed it.
+curl-installed binaries don't take `npm install -g` cleanly.
+
+**If every route fails:** name what blocked you — no Node, no shell, no write
+access, or a hosted session that cannot install — then hand off to the
+`postman-mcp-server` skill. An attempted install that actually failed is the
+only thing that qualifies.
+
+## 2. Establish the filesystem and workspace bindings
+
+### 2.1 Authenticate only if this step needs it
+
+Local commands need no login, and `postman init` is among them — its own help
+says *"No authentication, and safe in CI."* Skip this entirely unless the
+command you're about to run pulls or pushes an existing workspace, or shares
+one with a team.
+
+**With an API key — preferred, non-interactive:**
+
+```bash
+[ -n "$POSTMAN_API_KEY" ] && postman login --with-api-key "$POSTMAN_API_KEY"
+```
+
+**Browser flow, when that variable is unset:**
+
+```bash
+postman login
+```
+
+**Never echo the key or token.** Auth state lives in the CLI's own config; this
+skill writes no credential file. Report that authentication succeeded, nothing
+more.
+
+### 2.2 Inspect both sides before choosing a command
+
+Read `.postman/resources.yaml` for `localResources` and `workspace.id`, and
+inspect the local `postman/` tree. When the user names an existing workspace or
+asks to import, sync, or share one, use `workspace list --json` and `workspace
+get <id> --elements --json` to confirm the workspace side. Never create a
+second workspace merely because this repository is not connected yet.
+
+Prefer filesystem-first work: materialize an existing workspace with
+`workspace pull <id>`, or initialize local files with `postman init --no-cloud`
+when no workspace exists. Then inspect, edit, diff, and validate the
+version-controlled files before any push.
+
+| Existing state and intent | Use | Why |
+| --- | --- | --- |
+| No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |
+| No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |
+| Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |
+| Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |
+| Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |
+| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |
+| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |
+
+If “share” also requires changing a personal workspace's visibility or team
+permissions, inspect its metadata first. `push` synchronizes entities; it does
+not change access control. Do not create a replacement to work around a missing
+metadata-update command.
+
+`workspace diff` is read-only. Match its push strategy to the intended push.
+`--push-strategy force-sync` can delete workspace entities absent locally, so use it
+only when the user explicitly requests mirroring and approves the shown
+deletions. Do not add `-y` merely to bypass a prompt.
+
+### 2.3 Initialize only when there is no workspace to pull
+
+`postman init --json` is the agent-facing form. It writes
+`.postman/resources.yaml` and scaffolds `postman/` for specs, collections and
+environments. Downstream skills read that file and nothing else.
+
+```bash
+postman init --json --no-cloud               # local only, no workspace
+postman init --json --visibility personal    # also create and bind a workspace
+```
+
+Use `--visibility` only when a new workspace is actually wanted. If the
+workspace already exists, use `pull` to enable the filesystem workflow;
+use `push` only when publishing local changes to an already-bound workspace.
+
+**The workspace step is interactive** without `--no-cloud` or `--visibility`.
+
+**Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.
+Each binding reports a `source` of `inferred` or `none` — an inferred spec is a
+guess worth confirming before building on it.
+
+**Exit codes that are not failures:** 2 means several specs could be
+authoritative, so re-run with `--spec <path>`. 5 means the local files were
+written but the requested workspace was not created — it does *not* mean re-run.
+
+## 3. Verify and report
+
+### 3.1 Checkpoints
+
+- `postman --version` returned a real version.
+- Auth is confirmed, or established as not required for this task.
+- `.postman/resources.yaml` names a spec or a collections directory.
+- `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`
+  leaves it empty and still exits 0, which is a pass, not a gap.
+- After `pull`, expected workspace entities exist under `postman/`. After
+  `push`, report created/updated entities and conflicts; do not claim a
+  workspace is shared unless its access level permits the intended teammates.
+
+"The CLI is installed" is not the bar, and a loaded skill configures nothing.
+
+### 3.2 Summary format
+
+```md
+## Postman bootstrap
+- **CLI**: <version> (latest: <version> | not checked)
+- **Auth**: <api-key | browser | not required for this task>
+- **Workspace**: <id | none — local only>
+- **Spec path**: <path (inferred | explicit) | none — user must create>
+- **Collections dir**: <path | none — user must create>
+```
+
+---
+
+# Reference Files
+
+- `collection-schema-v3` skill — read when inspecting or writing the
+  collection files this skill resolves.
+- [CLI Installation](reference/cli_installation.md) — read for install, update
+  and uninstall commands per platform.

package/skills/bootstrap/reference/cli_installation.md

@@ -0,0 +1,58 @@
+# Postman CLI Installation
+
+A global install, on `PATH`, installed by one of three tools depending on
+platform. Whichever one put the binary there is the one to use again when
+updating it — mixing tools leaves two `postman` binaries and a `PATH`
+question.
+
+## Install
+
+**npm (all platforms):**
+
+```bash
+npm install -g postman-cli
+```
+
+**macOS, Linux, and WSL (curl):**
+
+```bash
+curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"
+```
+
+## Check for drift
+
+```bash
+postman --version              # installed
+npm view postman-cli version   # latest published
+```
+
+## Update
+
+Run the same command that installed it — the npm, curl or PowerShell line
+above, whichever put the binary there. Using a different one leaves two
+`postman` binaries and a `PATH` question. Never `npm install -g` over a copy
+that came from the curl installer or a system package manager.
+
+The CLI has no self-update verb. `postman skills update` is a different
+thing: it refreshes a repository's committed `postman/skills/`, not the
+binary.
+
+## Uninstall
+
+npm installations:
+
+```bash
+npm uninstall -g postman-cli
+```
+
+Other install methods: delete the `postman` binary from its install
+directory (`%USERPROFILE%\AppData\Local\Microsoft\WindowsApps` on Windows,
+`/usr/local/bin` on macOS/Linux/WSL).
+
+Source: https://learning.postman.com/docs/postman-cli/postman-cli-installation/