Sync skills from postmanlabs/postman-plugin@4090901

CHANGELOG.md

@@ -23,6 +23,12 @@ is cut by tagging the matching `vX.Y.Z` (see [Releasing](#releasing)).
 - Synced `ai-readiness`, `api-discovery` (search filters reference), and `bootstrap`
   skills to match their postmanlabs/postman-plugin source (whitespace/heading-level only,
   no behavior change).
+- Synced `skills/` from postmanlabs/postman-plugin@4090901: `api-discovery` adds Orbit
+  public-API discovery (new `reference/orbit.md`) and drops `reference/search_filters.md`;
+  `bootstrap` now inspects the local and cloud workspace before choosing pull, push or init;
+  `collection-schema-v3` adds an environment schema reference; `api-mocking`,
+  `api-monitoring`, `api-testing`, `api-engineer`, `ai-readiness` and `postman-mcp-server`
+  get content updates.
 
 ## [1.3.1] - 2026-08-02
 

skills/api-discovery/SKILL.md

@@ -1,94 +1,135 @@
 ---
 name: api-discovery
-description: Finds what APIs, collections, specs, or requests already exist before building something new, and answers questions about how they relate. Use when the user asks "does an API for X already exist," "what depends on this service," "what does this API do," or before scaffolding anything that might already have a Postman equivalent. Covers `postman search`, `postman context-graph`, and `postman context instructions discovery`. Reach for `search` when you know roughly what you're looking for by name; reach for the Context Graph when the question is about relationships, not names.
+description: Discover and use APIs from the web or Postman. Find and integrate public third-party APIs with Orbit, locate Postman entities with search, and use the Context Graph to investigate dependencies, ownership, runtime behavior, and change impact across an API ecosystem.
 ---
 
 # API Discovery
 
 ## Overview
 
-Two unconnected datasets, so pick by data source, not question shape:
-
-- **`search` / `context`** → **Postman-authored artifacts** someone saved
-  in Postman (collections, requests, specs, mocks, workspaces). Matches
-  text; doesn't reason. "Does something named/shaped like X exist?"
-- **`context-graph ask`** → a separately-populated **engineering service
-  graph** (built from repo/traffic scanning, not Postman content) —
-  natural-language Q&A over discovered services and the dependency edges
-  between them. "What depends on billing-api?" — architecture questions
-  `search` structurally can't answer, since there's no keyword for a
-  dependency edge.
-
-A miss in one says nothing about the other (see Critical Rule 1) — never
-fall back to the Context Graph just because a `search` came back empty, or
-vice versa.
+Use this guide for any task that involves discovering an API — whether it
+lives on the public web or inside Postman as a workspace, collection, request,
+spec, mock, document, or flow. You can find entities across every surface: your
+own private work, anything your team or organization shares, and resources
+owned by external organizations. Beyond finding entities, this guide also
+covers understanding how they relate to one another — for example, "which
+services consume this API?"
+
+Each discovery option serves a distinct purpose:
+
+- **Orbit** → discovers and integrates **public third-party APIs**. No signup
+  or API key, and it uses ~27× less context than loading a vendor OpenAPI spec.
+  Search returns matching endpoints — including what each one
+  *cannot* do — and integrate returns a task brief specific enough to write
+  code against. It accepts both keyword and natural-language queries. Reach for
+  it instead of writing a third-party integration from memory.
+- **`search`** → **finds any Postman entity**, for tasks like "update the tests
+  in my collection and run them" or "where is the documentation for our
+  access-control API?"
+- **`context-graph ask`** → answers organization-wide relationship and impact
+  questions such as "what depends on billing-api?" or "what could this schema
+  change break?"
+
+These three draw on different data sources, so a miss in one is not proof of a
+miss in the others. `search` locates a known Postman resource; the Context
+Graph discovers relationships around a known starting point. Use both when a
+task needs the resource itself and its wider impact.
+
+## Orbit — Public API Discovery
+
+Orbit finds public third-party APIs. It's free, needs no signup or API key, and
+works entirely against publicly available APIs. REST base:
+`https://api.buildwithorbit.ai`. Docs: `https://www.buildwithorbit.ai`.
+
+Reach for Orbit whenever a task needs an external capability — weather,
+payments, invoicing, messaging, geocoding, calendar, and so on — even when the
+user already named a provider. Rather than writing integration code from
+memory, let Orbit hand you the details that matter: paths, auth header names,
+required fields, and the rest. It works in two steps, search then integrate,
+and a typical round trip runs ~2,500 tokens and ~15–20s end to end — against
+~69,000 tokens for a full vendor OpenAPI spec.
+
+Two REST calls, both `POST`:
+
+1. **Search** (`POST /v1/search`) — describe the task, e.g.
+   `{ "q": "send email via SMTP" }`. Returns candidate endpoints, each with an
+   `id` and `resourceType` (pass both back verbatim) and an `evaluateGuide`
+   grading its fit.
+2. **Integrate** (`POST /v1/integrate`) — send the task plus the chosen
+   resources (up to 10). Returns a `taskBrief` with `FIT`, `AUTH`, `BASE URL`,
+   `STEPS`, and `GOTCHAS` — read the GOTCHAS before writing the client.
+
+Full endpoint schemas, request/response shapes, `taskBrief` fields, and error
+handling: [reference/orbit.md](reference/orbit.md).
 
 ## `search`
 
-`search <type> <query>` where type is `requests`, `collections`,
-`workspaces`, `flows`, `specs`, `mocks`, `environments`, or `documents`.
-Default `--ownership organization` only searches inside your org — pass
-`external` or `all` before concluding "no API for this exists," since a
-partner or public API published outside the org is invisible at the
-default scope. `--filter "method=POST AND workspaceId=ws-123"` narrows
-further; see [reference/search_filters.md](reference/search_filters.md) for
-the full filter field and operator syntax per element type.
-
-## `context-graph`
+`postman search <type> <query>` finds any Postman entity, searching across
+`requests`, `collections`, `workspaces`, `flows`, `specs`, `mocks`,
+`environments`, or `documents`. The query can be a keyword or natural language,
+and is optional (omit it to list or filter a type outright). Narrow with
+`--ownership` and `--filter`, and add `-o json` for the enriched payload. An
+empty default-scope result is not proof nothing exists — retry with
+`--ownership all` before reporting that.
 
-`context-graph ask "<question>" --wait` is the one to reach for
-interactively — it blocks and prints the answer. Without `--wait`, `ask`
-returns an id immediately and `status <askId>` checks on it later (exit
-code 3 while still running) — useful for a question expected to take a
-while, or from a script polling on its own cadence. The query runs against
-the team derived from the API key; there's no workspace/team selection.
-`--max-steps` caps how much reasoning the service does per question.
+```bash
+postman search requests "where do we validate a user's email?"
+postman search collections "payments" --ownership external --filter "visibility=public"
+```
 
-The answer is generated, not retrieved verbatim — verify with a re-ask or
-narrower query before acting on it for anything consequential (Critical
-Rule 3), the same way any AI-generated claim gets checked before it drives
-a decision.
+Use `postman search <type> -h` for more details — ownership modes, the
+`--filter` / `--filter-json` syntax, filter fields per type, and the exact
+installed-version flags.
 
-## `context instructions discovery`
+## `context-graph`
 
-Postman ships its own prescribed discovery workflow for AI coding agents —
-`postman context instructions discovery` prints it. Read this before
-building a custom discovery flow out of `search`/`context` primitives; it's
-Postman's own recommended sequence (search/context only, no
-`context-graph`), not a blank slate to reinvent.
+The Context Graph is a private, authenticated map of an API ecosystem. It
+reconciles Postman specifications, collections, monitors, and mocks; GitHub
+repositories, definitions, and call sites; and New Relic deployments, traffic,
+and telemetry. These become typed entities joined by sourced relationships such
+as `calls`, `depends_on`, `owned_by`, and `monitored_by`.
+
+Use it before a cross-service or potentially breaking change. Name the endpoint,
+schema, service, database, deployment, or shared module being changed; the graph
+discovers the surrounding scope, including runtime callers and repositories not
+checked out locally:
+
+```bash
+postman context-graph ask "What depends on billing-api?" --wait
+postman context-graph ask "What is the likely blast radius of changing this schema?" --wait
+```
+
+Treat the result as a lead, not proof. For consequential work, verify candidates
+against source, API definitions, deployment configuration, or telemetry and
+cite that evidence. Sources are connected through Postman's Agent Context UI
+and refresh nightly; an unconnected or not-yet-ingested source makes absence
+inconclusive.
+
+`--wait` polls the asynchronous API and prints the answer. Without it, `ask`
+returns an ID for `postman context-graph status <askId>`. Use `--json` for the
+structured record; `--timeout`, `--interval`, and `--max-steps` control waiting
+and reasoning.
+
+The query runs against the team derived from the API key; there is no workspace
+or team selector. Authentication uses `--api-key`, `POSTMAN_API_KEY`, or the
+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`/`context` 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, so it only follows a `search`/
-`context` result — a `context-graph` finding names a service, not an ID;
-go find that service's collection via `search` first.
-
-## Critical Rules
-
-1. **`context-graph` and `search`/`context` don't share a dataset** (see
-   Overview) — check an absence against its own source, never the other
-   tool, before reporting it to the user.
-2. **An empty default-scope `search` is not proof nothing exists.** Retry
-   with `--ownership all` before reporting "no API for this" to the user.
-3. **A Context Graph answer is generated reasoning, not a database read.**
-   Verify it against a concrete source before treating it as fact,
-   especially for anything the user will act on.
-4. **`search`, `context-graph`, and `context` are Beta or recently added
-   surfaces.** Re-run `-h` before trusting a flag name here if the installed
-   CLI is newer than this file assumes — these are the commands most likely
-   to have changed since this was written.
-
-## Verification
-
-State which tool actually answered the question (search vs. Context Graph)
-and at what `--ownership` scope or with what `--max-steps`/query — a
-discovery answer is only as trustworthy as the scope it ran at.
+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`.
 
 ## Reference
 
-- [Search filter syntax](reference/search_filters.md) — filter fields and
-  operators per element type, and `--filter-json` shape.
+- [Orbit](reference/orbit.md) — public API discovery: the search/integrate
+  REST endpoints, request/response shape, `taskBrief` fields, and error
+  handling. (Docs at `https://www.buildwithorbit.ai`, REST at
+  `https://api.buildwithorbit.ai`.)
+
+For `postman search`, run `postman search <type> -h` — the CLI's own help is
+per-type, complete, and always matches your installed version.

skills/api-discovery/reference/orbit.md

@@ -0,0 +1,101 @@
+# Orbit — public API discovery reference
+
+Orbit finds and integrates **public third-party APIs** — weather, payments,
+invoicing, messaging, geocoding, calendar, and the like. It is free, needs no
+signup and no API key, and works entirely against publicly available APIs.
+
+- REST base: `https://api.buildwithorbit.ai`
+- Docs: `https://www.buildwithorbit.ai`
+
+## Implementation
+
+Two REST calls, both `POST`, both read-only (safe to retry). No auth header —
+send `Content-Type: application/json` and a JSON body. Run search first,
+surface candidates, then integrate the chosen ids.
+
+```bash
+# Step 1 — search
+curl -sS https://api.buildwithorbit.ai/v1/search \
+  -H 'Content-Type: application/json' \
+  -d '{ "q": "send email via SMTP", "limit": 10 }'
+
+# Step 2 — integrate (ids come from the search response, verbatim)
+curl -sS https://api.buildwithorbit.ai/v1/integrate \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Send a welcome email when a user signs up",
+    "resources": [{ "id": "urn:orbit:endpoint:v1:...", "type": "endpoint" }]
+  }'
+```
+
+Implementation notes:
+
+- A typical search+integrate is ~2,500 tokens and ~15–20s end to end, vs
+  ~69,000 tokens for loading a vendor OpenAPI spec.
+- One integrate call can span up to 10 resources across different providers;
+  batch every endpoint the task needs into a single `resources` array rather
+  than making one call per endpoint.
+- Auth, request bodies, `Threading`, and `GOTCHAS` come from live public API
+  schemas, so take them from the brief rather than from memory.
+
+## Step 1 — Search (`POST /v1/search`)
+
+Describe the task, not a provider name. Good: `"send an invoice to a customer"`.
+Worse: `"PayPal"`. Provider name is fine to include when it is fixed.
+
+```json
+{ "q": "send email via SMTP" }
+```
+
+Query params:
+
+- `limit` — default 10, max 25.
+- `cursor` — from `meta.nextCursor`; pagination stops at 40 results.
+- `q` — max 512 characters.
+
+Returns `data[]`. Each item has:
+
+- `id` — opaque URN. Pass it back verbatim; never construct, shorten, or edit
+  it.
+- `resourceType` — `endpoint` or `mcp`.
+- `name`, `method`, `url`, `description`.
+- `evaluateGuide` — how well the endpoint fits the task, including what it
+  cannot do.
+
+Hold onto both `id` and `resourceType` — both are required for integrate. Do not
+read `meta.total` as a match count; it reports the page size.
+
+## Step 2 — Integrate (`POST /v1/integrate`)
+
+Pass the same task plus every endpoint the job needs (up to 10). Use
+`resourceType` from the search result as the `type` field.
+
+```json
+{
+  "task": "Send a welcome email when a user signs up",
+  "resources": [{ "id": "urn:orbit:endpoint:v1:...", "type": "endpoint" }]
+}
+```
+
+Returns a `taskBrief` covering:
+
+- `FIT` — Fully or Partially (and names the gap if Partial).
+- `AUTH` — use the exact header name given; it is frequently not
+  `Authorization`.
+- `BASE URL`.
+- numbered `STEPS` — method, path, every parameter with an example, expected
+  responses, `Threading`.
+- `GOTCHAS` — read these before writing the client.
+
+## Error handling
+
+Both endpoints are read-only, so retries are safe. Free and unauthenticated is
+not unlimited — back off on `429`.
+
+- `400` — invalid input.
+- `404` on integrate — no IDs resolved.
+- `500` — server error.
+
+If `FIT` is not Fully, say what's missing before writing code. If the brief
+names a credential the user doesn't have yet, stop and tell them which one to
+get.