From 7b31d577944cf9388a154a695ff67f488b85b606 Mon Sep 17 00:00:00 2001
From: Avdev4J <37835668+avdev4j@users.noreply.github.com>
Date: Thu, 3 Sep 2026 12:13:05 +0200
Subject: [PATCH 1/8] Update skill to match current Orbit API reference

The endpoint moved from fabric-gateway.postmanlabs.com/api/search to
api.buildwithorbit.ai/v1/search. Corrected the parameters against the
published OpenAPI spec and verified both endpoints live:

- limit/cursor are query parameters, not body fields; q is the only
  accepted body field (max 512 chars) and unknown fields return 400
- meta.nextCursor is absent on the last page, not null
- results carry resourceType (plus provider/product from the live API)
- pagination caps at 40 results per query

Also adds the /v1/integrate endpoint, which turns selected search
results into a task brief covering auth, base URLs, and request steps.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                               |  12 +-
 skills/discover/SKILL.md                |  46 ++++--
 skills/discover/references/orbit-api.md | 191 +++++++++++++++++++-----
 3 files changed, 196 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index 0316c35..b3c2cbe 100644
--- a/README.md
+++ b/README.md
@@ -28,13 +28,17 @@ Search for multiple capabilities at once:
 
 For each matching API, Orbit returns:
 
-- **Name** and **description** of the endpoint
+- **Name**, **description**, and **provider** of the endpoint
 - **Method** and **URL** for the API call
 - **evaluateGuide** -- structured guidance covering:
   - What the endpoint does
   - What it's best used for
   - What it does not support
 
+Once you've picked endpoints, Orbit can also generate a **task brief** -- the auth
+requirements, base URLs, ordered request steps, and gotchas needed to write the
+integration.
+
 Results are saved to `orbit-output/` as markdown files for reference.
 
 ## Design process
@@ -49,7 +53,9 @@ Orbit works best when you use it at the start of a project to build an API bluep
 
 4. **Iterate.** Use those gaps as your next round of queries. "Find me APIs that handle payment refunds" or "I need an auth provider that supports token refresh." Each round narrows the design.
 
-5. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
+5. **Get the task brief.** Once the endpoint set is settled, the agent sends the selected endpoints plus your task to Orbit's integrate endpoint and gets back a brief covering auth, base URLs, and the request sequence -- the implementation plan, before you write code.
+
+6. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
 
 The goal is to make API selection decisions intentionally at design time, not discover limitations mid-sprint after you've already integrated half the stack.
 
@@ -64,5 +70,7 @@ The goal is to make API selection decisions intentionally at design time, not di
 
 ## Links
 
+- [Orbit documentation](https://www.buildwithorbit.ai/)
+- [Orbit API reference](https://www.buildwithorbit.ai/api-reference)
 - [Postman API Network](https://www.postman.com/explore)
 - [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)
diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md
index 052d47c..eabb19a 100644
--- a/skills/discover/SKILL.md
+++ b/skills/discover/SKILL.md
@@ -1,11 +1,12 @@
 ---
-description: "Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do."
+description: "Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick."
 allowed-tools: ["Bash", "Write", "Read"]
 ---
 
 # orbit:discover
 
-Search the Postman API Network for APIs matching a capability query.
+Search the Postman API Network for APIs matching a capability query, then optionally
+generate an integration task brief for the endpoints you select.
 
 ## Input
 
@@ -15,22 +16,39 @@ Multiple capabilities: comma-separated or as separate arguments.
 ## Steps
 
 1. Read `references/orbit-api.md` for the API contract.
-2. For each capability query, POST to the Orbit search endpoint using curl.
-3. Parse the JSON response. For each result, extract:
-   - `name`, `method`, `url`
-   - `evaluateGuide` — the agent-oriented breakdown of what the endpoint does, what it's good for, and what it doesn't support
-4. Format results as a readable markdown table or list grouped by capability.
-5. Save output to `orbit-output/<slugified-query>.md`.
-6. Present a summary to the user highlighting the top matches and their evaluateGuide insights.
+2. For each capability query, `POST https://api.buildwithorbit.ai/v1/search` using curl.
+   No auth header is needed. The body takes exactly one field, `q` (max 512 chars) —
+   any other body field returns `400`. Use the `limit` query parameter (default 10,
+   max 25) to control page size.
+3. Parse the JSON response. For each result in `data`, extract:
+   - `id` — the `urn:orbit:endpoint:v1:...` identifier. Keep it verbatim; it's needed
+     for step 6.
+   - `resourceType`, `name`, `method`, `url`, and `provider` when present
+   - `evaluateGuide` — the agent-oriented breakdown of what the endpoint does, what
+     it's good for, and what it doesn't support
+4. If more results are needed and `meta.nextCursor` is present, repeat the request with
+   `?cursor=<nextCursor>` as a **query parameter** — not a body field. `nextCursor` is
+   absent (not null) on the last page. Pagination caps at 40 results per query.
+5. Format results as a readable markdown list grouped by capability, and save to
+   `orbit-output/<slugified-query>.md`.
+6. If the user has a concrete task in mind and endpoints look like a fit, offer to call
+   `POST https://api.buildwithorbit.ai/v1/integrate` with `{"task": "...", "resources":
+   [{"id": "<id from search>", "type": "<resourceType>"}]}`. Save the returned
+   `data[0].taskBrief` to `orbit-output/<slugified-task>-brief.md` — it contains the
+   auth requirements, base URLs, ordered steps, and gotchas needed to write the
+   integration.
+7. Present a summary to the user highlighting the top matches and their evaluateGuide
+   insights, especially the "Not supported" lines.
 
 ## Output format
 
 For each API result:
 
 ```
-### <name>
+### <name> (<provider>)
 - **Method:** <method>
 - **URL:** <url>
+- **ID:** <id>
 - **Evaluate Guide:** <evaluateGuide summary>
 ```
 
@@ -39,5 +57,9 @@ Group results under `## <capability query>` headings when multiple queries are r
 ## Notes
 
 - If a query returns zero results, say so — don't fabricate endpoints.
-- The `evaluateGuide` field is the key value: it tells you what an API is good for and what it can't do, saving trial-and-error.
-- Orbit is designed for agent consumption (compact payloads, structured guidance) vs human browsing on the Postman API Network website.
+- Never construct or edit an `id`. Pass search `id`s to `/v1/integrate` byte-for-byte.
+- The `evaluateGuide` field is the key value: it tells you what an API is good for and
+  what it can't do, saving trial-and-error.
+- On `429`, back off and retry — both endpoints are read-only, so retries are safe.
+- Orbit is designed for agent consumption (compact payloads, structured guidance) vs
+  human browsing on the Postman API Network website.
diff --git a/skills/discover/references/orbit-api.md b/skills/discover/references/orbit-api.md
index 07591b7..f917c4b 100644
--- a/skills/discover/references/orbit-api.md
+++ b/skills/discover/references/orbit-api.md
@@ -1,78 +1,191 @@
 # Orbit API Reference
 
-## Endpoint
+Docs: https://www.buildwithorbit.ai/api-reference
+OpenAPI: https://www.buildwithorbit.ai/openapi.json
 
-```
-POST https://fabric-gateway.postmanlabs.com/api/search
-Content-Type: application/json
-```
+**Base URL:** `https://api.buildwithorbit.ai`
+
+No authentication is required. Only `Content-Type: application/json` is needed.
+
+There are two endpoints: `/v1/search` finds candidate endpoints, `/v1/integrate` turns
+the ones you pick into a task brief.
+
+---
+
+## POST /v1/search
+
+Describe your goal in `q`. Returns matching public endpoints, each with an
+`evaluateGuide` explaining what it does, when to use it, and its limitations.
 
-## Request
+### Query parameters
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `limit` | integer | 10 | Results per page. Min 1, max 25. |
+| `cursor` | string | — | Pass `meta.nextCursor` from the previous response. Omit for the first page. |
+
+### Request body
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `q` | string | Yes | Natural language query, keywords, an API name, or a question. 1–512 characters. |
+
+`q` is the only accepted body field — unknown fields return `400`.
 
 ```json
-{
-  "q": "your search query"
-}
+{ "q": "Add tracking details for an existing paypal order" }
 ```
 
-The query should describe the capability you need — e.g., "payment processing for subscriptions", "send transactional email", "geocoding addresses".
-
-## Example curl
+### Example curl
 
 ```bash
-curl -s -X POST https://fabric-gateway.postmanlabs.com/api/search \
-  -H "Content-Type: application/json" \
+curl -s -X POST 'https://api.buildwithorbit.ai/v1/search?limit=10' \
+  -H 'Content-Type: application/json' \
   -d '{"q": "payment processing"}' | jq .
 ```
 
-## Response schema
+### Response (200)
 
 ```json
 {
   "data": [
     {
-      "id": "string",
-      "name": "string",
+      "id": "urn:orbit:endpoint:v1:...:brevo:send-a-transactional-ema",
+      "resourceType": "endpoint",
+      "name": "Send a transactional email",
       "description": "string",
-      "method": "GET | POST | PUT | PATCH | DELETE",
-      "url": "string (the API endpoint URL)",
-      "evaluateGuide": "string (agent-oriented usage guidance)"
+      "method": "POST",
+      "url": "https://api.brevo.com/v3/smtp/email",
+      "evaluateGuide": "string",
+      "provider": "Brevo",
+      "product": "Brevo"
     }
   ],
   "meta": {
-    "q": "string (echo of search query)",
-    "total": "number (total matching results)",
-    "nextCursor": "string | null (pagination cursor)"
+    "q": "send transactional email",
+    "total": 2,
+    "nextCursor": "eyJmcm9tIjoyfQ=="
   }
 }
 ```
 
-## Field descriptions
-
 | Field | Description |
 |-------|-------------|
-| `id` | Unique identifier for the API endpoint |
+| `id` | Opaque identifier of the form `urn:orbit:endpoint:v1:...`. Pass it back verbatim to `/v1/integrate` — never parse or construct it. |
+| `resourceType` | Kind of entity, e.g. `endpoint`. Pass it to `/v1/integrate` as the resource's `type`. |
 | `name` | Human-readable name of the endpoint |
-| `description` | Brief description of what the endpoint does |
-| `method` | HTTP method (GET, POST, PUT, PATCH, DELETE) |
-| `url` | The API endpoint URL |
-| `evaluateGuide` | Agent-oriented guidance — what the endpoint does, what it's good for ("Use for"), and what it can't do ("Not supported"). This is the key differentiator for AI agent consumption |
+| `description` | What the endpoint does (may be empty) |
+| `method` | HTTP method used to call the endpoint |
+| `url` | URL the endpoint is called at |
+| `evaluateGuide` | Three-part evaluation: brief summary, recommended use cases, unsupported use cases/limitations |
+| `provider` / `product` | Owning provider and product (returned by the live API; not in the published OpenAPI spec, so treat as optional) |
 
-## The evaluateGuide field
+`meta` carries `q`, `total`, and `nextCursor`. **`nextCursor` is absent on the last
+page** — check for its presence rather than comparing to `null`.
+
+### Pagination
+
+Pass `nextCursor` as the `cursor` **query parameter** (not a body field):
+
+```bash
+curl -s -X POST 'https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoyfQ==' \
+  -H 'Content-Type: application/json' \
+  -d '{"q": "payment processing"}'
+```
+
+Pagination stops at 40 results total; a cursor past 40 is rejected.
+
+### Errors
+
+`400` invalid input · `429` rate limited · `500` server error.
+Error bodies are RFC 9457 problem details: `type`, `title`, `status`, `detail`, `instance`.
+
+---
+
+## POST /v1/integrate
 
-The `evaluateGuide` is what makes Orbit results agent-friendly. It provides structured guidance so an AI agent can quickly decide whether an API fits its needs without trial-and-error:
+After selecting endpoints from `/v1/search`, send them here along with the task you
+want to accomplish. Returns a **task brief** with the information and steps needed to
+call those endpoints.
 
-- **What it does** — a concise description of the endpoint's purpose
-- **Use for** — specific scenarios where this endpoint is the right choice
-- **Not supported** — capabilities this endpoint does not cover, preventing wasted integration effort
+Takes no query parameters.
 
-## Pagination
+### Request body
 
-When `meta.nextCursor` is non-null, pass it as `"cursor"` in the next request body to fetch more results:
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `task` | string | Yes | What you want to accomplish. 1–512 characters, must contain non-whitespace. |
+| `resources` | array | Yes | Endpoints to integrate. Each item needs `id` and `type`. |
+| `resources[].id` | string | Yes | The `id` from a `/v1/search` result, verbatim. |
+| `resources[].type` | string | Yes | The result's `resourceType`. Currently only `endpoint`. |
 
 ```json
 {
-  "q": "payment processing",
-  "cursor": "value-from-nextCursor"
+  "task": "Build an app to post current weather to Slack",
+  "resources": [
+    { "id": "urn:orbit:endpoint:v1:...:weatherapi-com:current-weather-json", "type": "endpoint" },
+    { "id": "urn:orbit:endpoint:v1:...:slack:send-message-to-slack", "type": "endpoint" }
+  ]
 }
 ```
+
+### Example curl
+
+```bash
+curl -s -X POST https://api.buildwithorbit.ai/v1/integrate \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Send a transactional email when a user signs up",
+    "resources": [
+      { "id": "urn:orbit:endpoint:v1:...:sendmux:send-a-single-email", "type": "endpoint" }
+    ]
+  }' | jq -r '.data[0].taskBrief'
+```
+
+### Response (200)
+
+```json
+{
+  "data": [
+    { "taskBrief": "string" }
+  ]
+}
+```
+
+The `taskBrief` is a multi-line document covering FIT, AUTH (including which
+credentials you must supply), BASE URL, STEPS with parameters and expected responses,
+dependencies between steps, and important considerations. It is built from the
+selected endpoints' schemas plus shared variables, auth settings, and descriptions
+defined by their parent APIs.
+
+### Errors
+
+`400` invalid input · `404` none of the `id`s could be resolved · `429` rate limited ·
+`500` server error.
+
+---
+
+## Idempotency
+
+Both endpoints are read-only and never create or mutate data, so retries are safe and
+no idempotency key is needed. Search results may change as the public catalog changes;
+task brief wording may vary between otherwise identical calls.
+
+## The evaluateGuide field
+
+`evaluateGuide` is what makes Orbit results agent-friendly. It is a newline-separated
+string in three parts, so an agent can decide whether an API fits without
+trial-and-error:
+
+- **Summary** — a concise description of the endpoint's purpose
+- **`Use for:`** — specific scenarios where this endpoint is the right choice
+- **`Not supported:`** — capabilities this endpoint does not cover, preventing wasted
+  integration effort
+
+Example:
+
+```
+Sends a transactional email through Brevo's SMTP API, enabling an agent to deliver an email payload to recipients.
+Use for: send transactional messages, deliver notifications, send account emails
+Not supported: inbound email processing, contact management, campaign analytics
+```

From 9b7205f63ebcb0dee613d78830acd6c1428615ac Mon Sep 17 00:00:00 2001
From: Avdev4J <37835668+avdev4j@users.noreply.github.com>
Date: Thu, 3 Sep 2026 12:21:01 +0200
Subject: [PATCH 2/8] Bundle Orbit's MCP server and drive it from the skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ships .mcp.json so installing the plugin wires up Orbit's search and
integrate tools with no user setup (HTTP transport, no auth). The skill
now calls those tools instead of constructing curl commands, which moves
the API contract server-side — Orbit can change parameters without
breaking installed copies of the plugin.

The skill keeps everything that is actually this plugin's value: capability
decomposition, reading "Not supported" lines as design gaps, iteration, and
saving the blueprint to orbit-output/.

references/orbit-api.md is retained as a documented REST fallback for when
the MCP server is unreachable. Verified both tools live against
mcp.buildwithorbit.ai; their schemas also surface two constraints missing
from the published OpenAPI spec: integrate caps resources at 10, and both
tools accept an optional clientName for usage analytics.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .mcp.json                               |  8 +++
 README.md                               | 18 +++++
 plugin.json                             |  2 +-
 skills/discover/SKILL.md                | 87 ++++++++++++++++---------
 skills/discover/references/orbit-api.md | 43 +++++++++++-
 5 files changed, 126 insertions(+), 32 deletions(-)
 create mode 100644 .mcp.json

diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..d736b0c
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "orbit": {
+      "type": "http",
+      "url": "https://mcp.buildwithorbit.ai/mcp"
+    }
+  }
+}
diff --git a/README.md b/README.md
index b3c2cbe..04b0069 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,10 @@ Orbit is Postman's API discovery service built specifically for AI agent consump
 claude plugin add Postman-Devrel/orbit-claudecode-plugin
 ```
 
+The plugin bundles Orbit's MCP server, so there's nothing else to configure -- no API
+key, no `claude mcp add`. Installing the plugin wires up the `search` and `integrate`
+tools, and the skill drives them.
+
 ## Usage
 
 ```
@@ -59,6 +63,20 @@ Orbit works best when you use it at the start of a project to build an API bluep
 
 The goal is to make API selection decisions intentionally at design time, not discover limitations mid-sprint after you've already integrated half the stack.
 
+## How it works
+
+The plugin is a thin workflow layer over Orbit's MCP server:
+
+| | Provided by |
+|---|---|
+| `search` / `integrate` tools, request + response schemas | Orbit's MCP server (bundled) |
+| Capability decomposition, gap analysis, iteration, saved blueprint | This plugin's skill |
+
+Keeping the API contract on the server side means Orbit can change its parameters
+without breaking installed copies of the plugin. If the MCP server is ever
+unreachable, the skill falls back to the documented REST endpoints in
+[references/orbit-api.md](skills/discover/references/orbit-api.md).
+
 ## Orbit vs postman:search
 
 | | Orbit (`orbit:discover`) | Postman Search (`postman:search`) |
diff --git a/plugin.json b/plugin.json
index bc0215a..04e85c7 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "orbit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
   "skills": "./skills/"
 }
diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md
index eabb19a..a81beee 100644
--- a/skills/discover/SKILL.md
+++ b/skills/discover/SKILL.md
@@ -1,12 +1,20 @@
 ---
 description: "Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick."
-allowed-tools: ["Bash", "Write", "Read"]
+allowed-tools:
+  - "mcp__plugin_orbit_orbit__search"
+  - "mcp__plugin_orbit_orbit__integrate"
+  - "Bash"
+  - "Write"
+  - "Read"
 ---
 
 # orbit:discover
 
-Search the Postman API Network for APIs matching a capability query, then optionally
-generate an integration task brief for the endpoints you select.
+Search the Postman API Network for APIs matching a capability query, then generate an
+integration task brief for the endpoints you select.
+
+This plugin bundles Orbit's MCP server, so the `search` and `integrate` tools are
+available without setup. No authentication is required.
 
 ## Input
 
@@ -15,30 +23,44 @@ Multiple capabilities: comma-separated or as separate arguments.
 
 ## Steps
 
-1. Read `references/orbit-api.md` for the API contract.
-2. For each capability query, `POST https://api.buildwithorbit.ai/v1/search` using curl.
-   No auth header is needed. The body takes exactly one field, `q` (max 512 chars) —
-   any other body field returns `400`. Use the `limit` query parameter (default 10,
-   max 25) to control page size.
-3. Parse the JSON response. For each result in `data`, extract:
-   - `id` — the `urn:orbit:endpoint:v1:...` identifier. Keep it verbatim; it's needed
-     for step 6.
-   - `resourceType`, `name`, `method`, `url`, and `provider` when present
-   - `evaluateGuide` — the agent-oriented breakdown of what the endpoint does, what
-     it's good for, and what it doesn't support
-4. If more results are needed and `meta.nextCursor` is present, repeat the request with
-   `?cursor=<nextCursor>` as a **query parameter** — not a body field. `nextCursor` is
-   absent (not null) on the last page. Pagination caps at 40 results per query.
-5. Format results as a readable markdown list grouped by capability, and save to
-   `orbit-output/<slugified-query>.md`.
-6. If the user has a concrete task in mind and endpoints look like a fit, offer to call
-   `POST https://api.buildwithorbit.ai/v1/integrate` with `{"task": "...", "resources":
-   [{"id": "<id from search>", "type": "<resourceType>"}]}`. Save the returned
-   `data[0].taskBrief` to `orbit-output/<slugified-task>-brief.md` — it contains the
-   auth requirements, base URLs, ordered steps, and gotchas needed to write the
-   integration.
-7. Present a summary to the user highlighting the top matches and their evaluateGuide
-   insights, especially the "Not supported" lines.
+1. **Decompose.** Break the request into one focused capability query per intent. Run
+   each as a separate `search` call — do not cram intents into one query.
+
+2. **Search.** Call `mcp__plugin_orbit_orbit__search` for each capability:
+   - `q` — the query (required, max 512 chars)
+   - `limit` — results per page (default 10, max 25)
+   - `clientName` — pass `"claude-code/orbit-plugin"` for anonymous usage analytics
+
+   Query style matters. Include the product or provider name alongside the endpoint
+   detail: `"PayPal create invoice"` or `"PayPal API to create an invoice"`. Avoid
+   jumbled keyword piles (`"paypal invoice payment delivery ordering"`) and avoid
+   `OR`-separated queries — run separate calls instead.
+
+3. **Extract.** For each result in `data`, keep:
+   - `id` — the `urn:orbit:endpoint:v1:...` identifier. Preserve it verbatim; step 5
+     needs it. Never parse, edit, or construct one.
+   - `resourceType` — needed as `type` in step 5
+   - `name`, `method`, `url`, `provider`
+   - `evaluateGuide` — the three-part breakdown: summary, `Use for:`, `Not supported:`
+
+4. **Paginate if needed.** If `meta.nextCursor` is present, call `search` again with
+   `cursor` set to that value. `nextCursor` is *absent* on the last page, not null.
+   Pagination caps at 40 results per query.
+
+5. **Integrate.** When the user has a concrete task and the endpoint set looks right,
+   call `mcp__plugin_orbit_orbit__integrate`:
+   - `task` — what they're building (required, max 512 chars)
+   - `resources` — **1 to 10** entries of `{id, type}`, where `id` and `type` come from
+     a search result's `id` and `resourceType`. More than 10 is rejected; if the user
+     needs more, split into several calls by sub-task.
+
+   Save the returned `taskBrief` to `orbit-output/<slugified-task>-brief.md`. It covers
+   auth requirements, base URLs, ordered request steps, parameters, inter-step
+   dependencies, and gotchas.
+
+6. **Save and summarize.** Write the search results to
+   `orbit-output/<slugified-query>.md` and present the top matches to the user, leading
+   with the `Not supported:` lines — those are the design gaps worth acting on.
 
 ## Output format
 
@@ -57,9 +79,16 @@ Group results under `## <capability query>` headings when multiple queries are r
 ## Notes
 
 - If a query returns zero results, say so — don't fabricate endpoints.
-- Never construct or edit an `id`. Pass search `id`s to `/v1/integrate` byte-for-byte.
+- Never construct or edit an `id`. Pass search `id`s to `integrate` byte-for-byte.
 - The `evaluateGuide` field is the key value: it tells you what an API is good for and
   what it can't do, saving trial-and-error.
-- On `429`, back off and retry — both endpoints are read-only, so retries are safe.
+- Both tools are read-only and safe to retry. On a rate-limit error, back off and retry.
 - Orbit is designed for agent consumption (compact payloads, structured guidance) vs
   human browsing on the Postman API Network website.
+
+## Fallback
+
+If the MCP tools are unavailable — the server is unreachable, or you're running in an
+environment where the plugin's MCP server did not load — read
+`references/orbit-api.md` and call the equivalent REST endpoints with curl. The
+request and response shapes are identical.
diff --git a/skills/discover/references/orbit-api.md b/skills/discover/references/orbit-api.md
index f917c4b..eaf7864 100644
--- a/skills/discover/references/orbit-api.md
+++ b/skills/discover/references/orbit-api.md
@@ -1,8 +1,14 @@
-# Orbit API Reference
+# Orbit API Reference — REST fallback
 
 Docs: https://www.buildwithorbit.ai/api-reference
 OpenAPI: https://www.buildwithorbit.ai/openapi.json
 
+> **Prefer the MCP tools.** This plugin bundles Orbit's MCP server, so
+> `mcp__plugin_orbit_orbit__search` and `mcp__plugin_orbit_orbit__integrate` are
+> normally available and carry live, self-describing schemas. Use the REST calls below
+> only when those tools are unavailable. See [MCP tools](#mcp-tools) at the end for the
+> mapping.
+
 **Base URL:** `https://api.buildwithorbit.ai`
 
 No authentication is required. Only `Content-Type: application/json` is needed.
@@ -115,7 +121,7 @@ Takes no query parameters.
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `task` | string | Yes | What you want to accomplish. 1–512 characters, must contain non-whitespace. |
-| `resources` | array | Yes | Endpoints to integrate. Each item needs `id` and `type`. |
+| `resources` | array | Yes | Endpoints to integrate, 1–10 items. Each item needs `id` and `type`. The MCP tool schema enforces a max of 10; the published OpenAPI spec omits the limit, so assume it applies to REST too and split larger sets across calls. |
 | `resources[].id` | string | Yes | The `id` from a `/v1/search` result, verbatim. |
 | `resources[].type` | string | Yes | The result's `resourceType`. Currently only `endpoint`. |
 
@@ -189,3 +195,36 @@ Sends a transactional email through Brevo's SMTP API, enabling an agent to deliv
 Use for: send transactional messages, deliver notifications, send account emails
 Not supported: inbound email processing, contact management, campaign analytics
 ```
+
+---
+
+## MCP tools
+
+The plugin bundles Orbit's MCP server (`https://mcp.buildwithorbit.ai/mcp`, HTTP
+transport, no auth) via `.mcp.json`. It exposes two tools that map one-to-one onto the
+REST endpoints and return identical payloads:
+
+| MCP tool | REST equivalent |
+|----------|-----------------|
+| `mcp__plugin_orbit_orbit__search` | `POST /v1/search` |
+| `mcp__plugin_orbit_orbit__integrate` | `POST /v1/integrate` |
+
+Differences from REST:
+
+- `limit` and `cursor` are ordinary tool arguments, not query parameters.
+- Both tools accept an optional `clientName` string for anonymous usage analytics.
+  Pass `"claude-code/orbit-plugin"`.
+- `integrate` declares `resources` as 1–10 items in its schema.
+
+The tool schemas are the authoritative contract — they are fetched live from the
+server, so they stay correct even when this file drifts.
+
+### Query guidance (from the tool description)
+
+- Use focused keyword queries including the product or provider name plus the endpoint
+  detail — e.g. `"PayPal create invoice"`.
+- Natural language works too — e.g. `"PayPal API to create an invoice"`.
+- Avoid jumbled queries cramming unrelated keywords together — e.g.
+  `"paypal invoice payment delivery payments ordering"`.
+- Avoid `OR`-separated queries — e.g. `"paypal invoice OR paypal create invoice"`.
+- To explore multiple intents, make a separate call per intent.

From f96266966b8cc9e107a80ad0074950d99cfd9a67 Mon Sep 17 00:00:00 2001
From: Avdev4J <37835668+avdev4j@users.noreply.github.com>
Date: Thu, 3 Sep 2026 12:46:19 +0200
Subject: [PATCH 3/8] Fix manifest location and add marketplace manifest

Claude Code only reads .claude-plugin/plugin.json; the root-level
plugin.json was silently ignored (`claude plugin validate` reported
"Validating components" rather than a manifest). The plugin name would
have fallen back to the directory name, making the skill
/orbit-claudecode-plugin:discover and the MCP tools
mcp__plugin_orbit_claudecode_plugin_orbit__*, which would not have matched
the allowed-tools entries in SKILL.md.

Also drops the "skills" field (a Codex convention; Claude Code
auto-discovers skills/ at the plugin root) and adds author/homepage.

Adds .claude-plugin/marketplace.json so the repo is installable as a
marketplace, matching the pattern already used by devrel-claude-code-skills.

Verified end-to-end: plugin installs as orbit@orbit-marketplace, the
bundled MCP server reports plugin:orbit:orbit connected, and
/orbit:discover resolves mcp__plugin_orbit_orbit__search and completes a
real search plus integration brief.

Narrows the integrate guidance: the schema allows 10 resources, but a
5-resource call returned a one-line restatement instead of a brief while a
2-resource call returned the full document, so the skill now advises
several focused calls.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json | 24 ++++++++++++++++++++++++
 .claude-plugin/plugin.json      | 10 ++++++++++
 plugin.json                     |  6 ------
 skills/discover/SKILL.md        |  8 +++++---
 4 files changed, 39 insertions(+), 9 deletions(-)
 create mode 100644 .claude-plugin/marketplace.json
 create mode 100644 .claude-plugin/plugin.json
 delete mode 100644 plugin.json

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..2e19ce4
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,24 @@
+{
+  "name": "orbit-marketplace",
+  "owner": {
+    "name": "Postman DevRel"
+  },
+  "metadata": {
+    "description": "Agent-friendly API discovery from the Postman API Network"
+  },
+  "plugins": [
+    {
+      "name": "orbit",
+      "source": ".",
+      "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+      "version": "1.1.0",
+      "author": {
+        "name": "Postman DevRel"
+      },
+      "homepage": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+      "repository": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+      "keywords": ["api", "discovery", "postman", "orbit", "agent", "mcp"],
+      "category": "developer-tools"
+    }
+  ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..b8876c9
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,10 @@
+{
+  "name": "orbit",
+  "version": "1.1.0",
+  "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+  "author": {
+    "name": "Postman DevRel"
+  },
+  "homepage": "https://github.com/Postman-Devrel/orbit-claudecode-plugin",
+  "repository": "https://github.com/Postman-Devrel/orbit-claudecode-plugin"
+}
diff --git a/plugin.json b/plugin.json
deleted file mode 100644
index 04e85c7..0000000
--- a/plugin.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
-  "name": "orbit",
-  "version": "1.1.0",
-  "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
-  "skills": "./skills/"
-}
diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md
index a81beee..c9e2e8b 100644
--- a/skills/discover/SKILL.md
+++ b/skills/discover/SKILL.md
@@ -50,9 +50,11 @@ Multiple capabilities: comma-separated or as separate arguments.
 5. **Integrate.** When the user has a concrete task and the endpoint set looks right,
    call `mcp__plugin_orbit_orbit__integrate`:
    - `task` — what they're building (required, max 512 chars)
-   - `resources` — **1 to 10** entries of `{id, type}`, where `id` and `type` come from
-     a search result's `id` and `resourceType`. More than 10 is rejected; if the user
-     needs more, split into several calls by sub-task.
+   - `resources` — entries of `{id, type}`, where `id` and `type` come from a search
+     result's `id` and `resourceType`. The schema allows up to 10, but **keep calls
+     narrow — 2 or 3 related endpoints**. Wide calls have been observed to return a
+     one-line restatement instead of a real brief. To cover more endpoints, make
+     several focused calls grouped by sub-task rather than one wide call.
 
    Save the returned `taskBrief` to `orbit-output/<slugified-task>-brief.md`. It covers
    auth requirements, base URLs, ordered request steps, parameters, inter-step

From 938daad9715757f976b902f09185aaabab2660ea Mon Sep 17 00:00:00 2001
From: Avdev4J <37835668+avdev4j@users.noreply.github.com>
Date: Thu, 3 Sep 2026 13:01:31 +0200
Subject: [PATCH 4/8] Fix install instructions

`claude plugin add` is not a subcommand. Installing from a repo takes two
steps: register the marketplace, then install the plugin from it. Also
documents --plugin-dir for local development.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                                     |  11 +-
 ...a-street-address-into-coordinates-brief.md | 102 ++++++++++++++++++
 orbit-output/geocode-an-address.md            | 101 +++++++++++++++++
 3 files changed, 213 insertions(+), 1 deletion(-)
 create mode 100644 orbit-output/geocode-a-street-address-into-coordinates-brief.md
 create mode 100644 orbit-output/geocode-an-address.md

diff --git a/README.md b/README.md
index 04b0069..437fd82 100644
--- a/README.md
+++ b/README.md
@@ -9,13 +9,22 @@ Orbit is Postman's API discovery service built specifically for AI agent consump
 ## Install
 
 ```bash
-claude plugin add Postman-Devrel/orbit-claudecode-plugin
+claude plugin marketplace add Postman-Devrel/orbit-claudecode-plugin
+claude plugin install orbit@orbit-marketplace
 ```
 
 The plugin bundles Orbit's MCP server, so there's nothing else to configure -- no API
 key, no `claude mcp add`. Installing the plugin wires up the `search` and `integrate`
 tools, and the skill drives them.
 
+Then run `/orbit:discover <capability>` in a new session.
+
+To hack on it locally without installing, point Claude Code at a checkout:
+
+```bash
+claude --plugin-dir ./orbit-claudecode-plugin
+```
+
 ## Usage
 
 ```
diff --git a/orbit-output/geocode-a-street-address-into-coordinates-brief.md b/orbit-output/geocode-a-street-address-into-coordinates-brief.md
new file mode 100644
index 0000000..64bed9f
--- /dev/null
+++ b/orbit-output/geocode-a-street-address-into-coordinates-brief.md
@@ -0,0 +1,102 @@
+# Task brief: geocode a street address into latitude/longitude
+
+Generated by Orbit MCP `integrate`.
+
+**Task:** Geocode a street address into latitude/longitude coordinates, with a fallback provider if the
+primary returns no match.
+
+**Resources:**
+- `urn:orbit:endpoint:v1:1LKGXlgOcG8yPK3VhFCHNE60JlxB03MXIW5CoS2ccJgvfeT904cCPC7A9Jhwn:google:geocode`
+- `urn:orbit:endpoint:v1:aNIlwdaRLputqrxxn10U3re76azr1Y0s:apifreaks:forward-geocoding-search`
+- `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wC6IltepH9qOrLRZfOyXTl8wroVvRNLKfjqCWiuY530ygaI1g:esri:search-address`
+
+---
+
+## FIT
+
+Fully. The supplied Google Maps, APIFreaks, and ArcGIS requests all geocode a street address and return
+coordinates, so they provide primary and fallback coverage. All three requests serve the task and are
+presented as alternatives; do not call more than one unless the preceding provider returns no match.
+
+## AUTH
+
+The alternatives use different authentication schemes:
+
+- **Google Maps (option 1):** API key in the query parameter `key`; supply the Google Maps Platform API key.
+- **APIFreaks (option 2):** API key in the query parameter `apiKey` as shown by the request; the collection
+  also documents the preferred `X-apiKey` header, but the request schema does not include that header.
+- **ArcGIS (option 3):** access token in the query parameter `token`.
+
+## BASE URL
+
+- Google Maps (option 1): `https://maps.googleapis.com`
+- APIFreaks (option 2): `https://api.apifreaks.com`
+- ArcGIS (option 3): `https://geocode-api.arcgis.com`
+
+## STEPS
+
+Choose one geocoding alternative; use the next option only if the previous one returns no match.
+
+### Option 1 — `GET /maps/api/geocode/json`
+
+Params:
+- `address` (string) — e.g. `1600 Amphitheatre Parkway, Mountain View, CA`; query parameter. Required unless
+  using `components` instead.
+- `key` (string) — your Google Maps Platform API key; query parameter.
+- `Accept` (string) — `application/json`; request header.
+- Also accepts: `bounds`, `components`, `latlng`, `location_type`, `place_id`, `result_type`, `language`,
+  `region` — query parameters.
+
+Returns: `200 OK` with a JSON object containing `results` (array). Each result may include
+`formatted_address`, `address_components` (array), `geometry` with `location.lat` and `location.lng`,
+`geometry.location_type`, `place_id`, and `types`; the top-level `status` is `OK` in the example.
+
+Threading: none.
+
+### Option 2 — `GET /v1.0/geocoder/search`
+
+Params:
+- `query` (string) — e.g. `1600 Amphitheatre Parkway, Mountain View, CA`; query parameter.
+- `apiKey` (string) — your APIFreaks API key; query parameter.
+- `limit` (integer) — e.g. `1` for a single best match; query parameter, optional, range 1–40.
+- `format` (string) — `json`; query parameter, optional.
+- `Accept` (string) — `application/json`; request header.
+- `Accept-Language` (string) — `en`; request header, optional.
+- Also accepts: `min_lat`, `max_lat`, `min_lon`, `max_lon` — query parameters for a complete viewbox.
+
+Returns: `200 OK` with a JSON array of result objects containing `lat` and `lon` numbers, plus fields such as
+`name`, `full_address`, and `bounding_box`. An invalid or missing key returns `401` with an error object
+containing `status` and `message`.
+
+Threading: none.
+
+### Option 3 — `GET /arcgis/rest/services/World/GeocodeServer/findAddressCandidates`
+
+Params:
+- `singleLine` (string) — e.g. `1600 Pennsylvania Ave NW, DC`; query parameter.
+- `f` (string) — `json`; query parameter.
+- `token` (string) — a valid ArcGIS access token; query parameter.
+
+Returns: `200 OK` with an object containing `spatialReference` (`wkid` and `latestWkid`) and `candidates`
+(array). Each candidate may contain `address`, `location.x` (longitude), `location.y` (latitude), `score`,
+`attributes`, and `extent`.
+
+Threading: none.
+
+## GOTCHAS
+
+- These providers are alternatives for the same geocoding capability, not sequential workflow steps. Try a
+  fallback only when the selected provider returns no match.
+- URL-encode address text and query parameters; Google address input and ArcGIS `singleLine` are query
+  parameters, not request bodies.
+- Google requires at least one of `address` or `components`; avoid duplicating the same address components in
+  both because this can produce zero results.
+- APIFreaks viewbox filtering requires all four coordinates (`min_lat`, `max_lat`, `min_lon`, `max_lon`)
+  together, with minimum values no greater than maximum values.
+- The collection has an empty APIFreaks `apiKeyValue`, and the ArcGIS `ACCESS_TOKEN` is unresolved in the
+  supplied data; provide valid credentials before calling.
+- Normalize coordinate conventions when switching providers: Google returns latitude as
+  `geometry.location.lat` and longitude as `geometry.location.lng`; APIFreaks returns `lat` and `lon`; ArcGIS
+  returns longitude in `location.x` and latitude in `location.y`.
+- APIFreaks successful calls may consume credits and may return an `X-AF-Credits-Cost` response header; its
+  example shows a cost of `2`.
diff --git a/orbit-output/geocode-an-address.md b/orbit-output/geocode-an-address.md
new file mode 100644
index 0000000..b4781ec
--- /dev/null
+++ b/orbit-output/geocode-an-address.md
@@ -0,0 +1,101 @@
+# Orbit search: geocode an address
+
+Queries run against the Postman API Network via Orbit MCP `search`.
+
+## Query 1 — "geocode an address to latitude and longitude coordinates"
+
+### Geocode a set of addresses (Esri)
+- **Method:** POST
+- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses
+- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wIlJkgG3SsddzdPg120qLbT8jPv9KZ4Px1KW7Dr68cWfyziqn:esri:geocode-a-set-of-address`
+- **Evaluate Guide:** Batch geocodes multiple addresses through ArcGIS World Geocoding and returns matched location data.
+  - Use for: batch address geocoding, coordinate lookup, address matching
+  - Not supported: reverse geocoding, routing, map rendering
+
+### Geocode location A (Esri)
+- **Method:** GET
+- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
+- **ID:** `urn:orbit:endpoint:v1:MXWIl9HGTDmcWiItQRwD3gUh3ZEQSdm8FPNlbZA7YDStdvUN3KMgFMNQezk:postman:geocode-location-a`
+- **Evaluate Guide:** Geocodes one address with ArcGIS findAddressCandidates and returns candidate locations ranked by match quality.
+  - Use for: single-address geocoding, candidate matching, coordinate lookup
+  - Not supported: batch geocoding, reverse geocoding, route planning
+
+### Forward Geocode (Geocode Address → Coordinates) (Radar)
+- **Method:** GET
+- **URL:** https://api.radar.io/v1/geocode/forward
+- **ID:** `urn:orbit:endpoint:v1:aGr31osDAu5ruWnQqtVGDCATuOKMjyvj:radar:forward-geocode-geocode`
+- **Evaluate Guide:** No `evaluateGuide` returned. Description notes publishable-key auth, `query` as the only required
+  param, optional `layers` / `country` / `lang`, confidence values of exact/interpolated/fallback, and a default
+  rate limit of 10 rps.
+
+### Geocode address (Rhombus Systems)
+- **Method:** POST
+- **URL:** https://api2.rhombussystems.com/api/location/geoCode
+- **ID:** `urn:orbit:endpoint:v1:1JhNlBQCc1sts2sRHe0epV5cfTdtKjMEzGhhcubCitLILYU4Cm3nWPgPvB3Gm:rhombus:geocode-address`
+- **Evaluate Guide:** Converts an address into latitude and longitude coordinates using the Rhombus location service.
+  - Use for: address geocoding, coordinate lookup, location normalization
+  - Not supported: reverse geocoding, routing, map display
+
+### Lookup the latitude,longitude of an address (HPE Aruba Networking)
+- **Method:** GET
+- **URL:** https://172.16.3.20/gms/rest/location/addressToLocation
+- **ID:** `urn:orbit:endpoint:v1:1MvBXWcfBS1o5lqsUf9Fzwd5ermbKHMyh53VK0F3WSQNfBEaTiSPH2vyX3RbM:hpe:lookup-the-latitude-long`
+- **Evaluate Guide:** Resolves an address to an ordered array of matching latitude and longitude locations in EdgeConnect SD-WAN.
+  - Use for: address geocoding, best-match lookup, location resolution
+  - Not supported: reverse geocoding, routing, network configuration
+  - Note: private RFC1918 host — appliance-local, not a public service.
+
+Reverse-geocoding results also returned by this query (not a fit for forward geocoding): Pinball Map,
+Cloudmersive, Vedika, OpenWeather, Meteoprog, OneMap SG, Esri reverseGeocode.
+
+## Query 2 — "forward geocoding convert street address string into coordinates"
+
+### geocode (Google)
+- **Method:** GET
+- **URL:** https://maps.googleapis.com/maps/api/geocode/json
+- **ID:** `urn:orbit:endpoint:v1:1LKGXlgOcG8yPK3VhFCHNE60JlxB03MXIW5CoS2ccJgvfeT904cCPC7A9Jhwn:google:geocode`
+- **Evaluate Guide:** Supports address-to-coordinate and coordinate-to-address geocoding, including lookups by place identifier.
+  - Use for: forward geocoding, reverse geocoding, place ID lookup, mapping addresses
+  - Not supported: navigation, distance matrices, map imagery
+
+### Forward Geocoding - Search (Address to Coordinates) (APIFreaks)
+- **Method:** GET
+- **URL:** https://api.apifreaks.com/v1.0/geocoder/search
+- **ID:** `urn:orbit:endpoint:v1:aNIlwdaRLputqrxxn10U3re76azr1Y0s:apifreaks:forward-geocoding-search`
+- **Evaluate Guide:** Finds coordinates and structured location details from a free-form address, place, or landmark query.
+  - Use for: geocoding addresses, locating landmarks, resolving place names, getting bounding boxes
+  - Not supported: coordinate-to-address lookup, routing, map tiles
+
+### Forward Geocoding (Address to Coordinates) (APIFreaks — duplicate variant)
+- **Method:** GET
+- **URL:** https://api.apifreaks.com/v1.0/geocoder/search
+- **ID:** `urn:orbit:endpoint:v1:aNIlwdqeBGW8B9diAdC77BeVBZKt9iWC:apifreaks:forward-geocoding-addres`
+- **Evaluate Guide:** Finds WGS84 coordinates and structured address details from free-form address, place, or business queries.
+  - Use for: geocoding addresses, finding businesses, resolving place names, limiting results
+  - Not supported: coordinate-to-address lookup, routing, map tiles
+
+### Search address (Esri)
+- **Method:** GET
+- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
+- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wC6IltepH9qOrLRZfOyXTl8wroVvRNLKfjqCWiuY530ygaI1g:esri:search-address`
+- **Evaluate Guide:** Geocodes one address or place description and returns matching location candidates.
+  - Use for: address search, place lookup, finding candidate coordinates
+  - Not supported: batch geocoding, reverse geocoding, route planning
+
+### Search street intersection (Esri)
+- **Method:** GET
+- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
+- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5x11h3g8SR0wVANRygVh6H2T5Wg3f1cisEC2FG2OHgtvn0eNxo:esri:search-street-intersecti`
+- **Evaluate Guide:** No `evaluateGuide` returned. Same operation as Search address with `category=intersection`.
+
+### Get Address (PositionStack, via a Postman demo collection)
+- **Method:** GET
+- **URL:** http://api.positionstack.com/v1/forward
+- **ID:** `urn:orbit:endpoint:v1:1I4UV9Fqy4Y3DrgUgFkLIEJ18gBzKrO9HqAFQSw8yzykvkIvK4d36OIcgnwMY:more:get-address`
+- **Evaluate Guide:** No `evaluateGuide` returned. Plain HTTP and wrapped in a Slack-bot demo collection.
+
+## Coverage notes
+
+- Both queries reported `meta.total: 15` with a `nextCursor` present; pagination caps at 40 results per query.
+  Further pages were not fetched.
+- Neither query surfaced Mapbox, HERE, OpenCage, or Nominatim.

From 90fff32c2db0d2a163b4aa3fd76aeb3850c94519 Mon Sep 17 00:00:00 2001
From: Talia Kohan <162498597+buildwithtalia@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:13:05 -0700
Subject: [PATCH 5/8] removing Postman API Network from messaging

---
 .claude-plugin/marketplace.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 2e19ce4..423d695 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -4,13 +4,13 @@
     "name": "Postman DevRel"
   },
   "metadata": {
-    "description": "Agent-friendly API discovery from the Postman API Network"
+    "description": "Agent-friendly API discovery"
   },
   "plugins": [
     {
       "name": "orbit",
       "source": ".",
-      "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+      "description": "Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
       "version": "1.1.0",
       "author": {
         "name": "Postman DevRel"

From 6529d8d48e6bae3a57a4bd03eb561df5de44f671 Mon Sep 17 00:00:00 2001
From: Talia Kohan <162498597+buildwithtalia@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:13:32 -0700
Subject: [PATCH 6/8] removing Postman API Network from messaging

---
 .claude-plugin/plugin.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index b8876c9..0e9a488 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "orbit",
   "version": "1.1.0",
-  "description": "Discover APIs from the Postman API Network using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
+  "description": "Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.",
   "author": {
     "name": "Postman DevRel"
   },

From 0c86e4e924d317a17340fe2f0fe3e064504a92fd Mon Sep 17 00:00:00 2001
From: Talia Kohan <talia.kohan@postman.com>
Date: Wed, 9 Sep 2026 11:19:21 -0700
Subject: [PATCH 7/8] Drop the orbit-output file-saving pattern

Per review: writing results to disk is not a pattern used elsewhere, and
the skill has no reason to leave files behind. The search results and the
task brief are presented to the user in the conversation instead.

- skills/discover/SKILL.md: step 5 no longer writes the taskBrief to
  orbit-output/<task>-brief.md; step 6 becomes "Summarize" rather than
  "Save and summarize"
- README.md: drops the "Results are saved to orbit-output/" line and the
  "Save the blueprint" design-process step, which now ends at the task
  brief

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                |  4 ----
 skills/discover/SKILL.md | 10 ++++------
 2 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 437fd82..a1091db 100644
--- a/README.md
+++ b/README.md
@@ -52,8 +52,6 @@ Once you've picked endpoints, Orbit can also generate a **task brief** -- the au
 requirements, base URLs, ordered request steps, and gotchas needed to write the
 integration.
 
-Results are saved to `orbit-output/` as markdown files for reference.
-
 ## Design process
 
 Orbit works best when you use it at the start of a project to build an API blueprint before writing code. Here's the workflow:
@@ -68,8 +66,6 @@ Orbit works best when you use it at the start of a project to build an API bluep
 
 5. **Get the task brief.** Once the endpoint set is settled, the agent sends the selected endpoints plus your task to Orbit's integrate endpoint and gets back a brief covering auth, base URLs, and the request sequence -- the implementation plan, before you write code.
 
-6. **Save the blueprint.** The agent saves results to `orbit-output/` as a structured file you can reference throughout the project. This becomes your API design document, readable by both humans and agents.
-
 The goal is to make API selection decisions intentionally at design time, not discover limitations mid-sprint after you've already integrated half the stack.
 
 ## How it works
diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md
index c9e2e8b..c9ed534 100644
--- a/skills/discover/SKILL.md
+++ b/skills/discover/SKILL.md
@@ -56,13 +56,11 @@ Multiple capabilities: comma-separated or as separate arguments.
      one-line restatement instead of a real brief. To cover more endpoints, make
      several focused calls grouped by sub-task rather than one wide call.
 
-   Save the returned `taskBrief` to `orbit-output/<slugified-task>-brief.md`. It covers
-   auth requirements, base URLs, ordered request steps, parameters, inter-step
-   dependencies, and gotchas.
+   The returned `taskBrief` covers auth requirements, base URLs, ordered request steps,
+   parameters, inter-step dependencies, and gotchas.
 
-6. **Save and summarize.** Write the search results to
-   `orbit-output/<slugified-query>.md` and present the top matches to the user, leading
-   with the `Not supported:` lines — those are the design gaps worth acting on.
+6. **Summarize.** Present the top matches to the user, leading with the
+   `Not supported:` lines — those are the design gaps worth acting on.
 
 ## Output format
 

From 98196482ccddde23a7809dcfe5b3db0060addd3e Mon Sep 17 00:00:00 2001
From: Talia Kohan <talia.kohan@postman.com>
Date: Thu, 10 Sep 2026 08:47:17 -0700
Subject: [PATCH 8/8] Drop Postman API Network references and the committed
 output samples

Per review: Orbit is a separate product, so the plugin should not present
itself as a front-end for the Postman API Network.

README.md
- Intro now matches the manifest wording: "Discover APIs using Postman
  Orbit, an agent-friendly search API designed for AI-powered app design"
- "Unlike browsing the Postman API Network in a browser" -> "an API catalog"
- Removed the Postman API Network entry from Links
- "How it works" table no longer credits the skill with a "saved
  blueprint", which went away with the file-saving pattern

skills/discover/SKILL.md
- Skill description and the opening line no longer name the API Network
- The agent-vs-human note now says "an API catalog in a web UI"
- Dropped "Write" from allowed-tools; the skill writes no files now

Deleted orbit-output/, which held two committed sample outputs. Nothing
referenced them and nothing produces them any more.

The "Orbit vs postman:search" comparison is left alone: it contrasts two
tools rather than positioning Orbit as part of the Network.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                                     |   7 +-
 ...a-street-address-into-coordinates-brief.md | 102 ------------------
 orbit-output/geocode-an-address.md            | 101 -----------------
 skills/discover/SKILL.md                      |   7 +-
 4 files changed, 6 insertions(+), 211 deletions(-)
 delete mode 100644 orbit-output/geocode-a-street-address-into-coordinates-brief.md
 delete mode 100644 orbit-output/geocode-an-address.md

diff --git a/README.md b/README.md
index a1091db..8a59c82 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # Orbit Claude Code Plugin
 
-Discover APIs from the [Postman API Network](https://www.postman.com/explore) using Postman Orbit -- an agent-friendly search API designed for AI-powered app design.
+Discover APIs using Postman Orbit, an agent-friendly search API designed for AI-powered app design.
 
 ## What is Orbit?
 
-Orbit is Postman's API discovery service built specifically for AI agent consumption. Unlike browsing the Postman API Network in a browser, Orbit returns compact, structured payloads with `evaluateGuide` fields that tell agents exactly what each API endpoint can and can't do. This lets agents make integration decisions without trial-and-error.
+Orbit is Postman's API discovery service built specifically for AI agent consumption. Unlike browsing an API catalog in a browser, Orbit returns compact, structured payloads with `evaluateGuide` fields that tell agents exactly what each API endpoint can and can't do. This lets agents make integration decisions without trial-and-error.
 
 ## Install
 
@@ -75,7 +75,7 @@ The plugin is a thin workflow layer over Orbit's MCP server:
 | | Provided by |
 |---|---|
 | `search` / `integrate` tools, request + response schemas | Orbit's MCP server (bundled) |
-| Capability decomposition, gap analysis, iteration, saved blueprint | This plugin's skill |
+| Capability decomposition, gap analysis, iteration | This plugin's skill |
 
 Keeping the API contract on the server side means Orbit can change its parameters
 without breaking installed copies of the plugin. If the MCP server is ever
@@ -95,5 +95,4 @@ unreachable, the skill falls back to the documented REST endpoints in
 
 - [Orbit documentation](https://www.buildwithorbit.ai/)
 - [Orbit API reference](https://www.buildwithorbit.ai/api-reference)
-- [Postman API Network](https://www.postman.com/explore)
 - [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)
diff --git a/orbit-output/geocode-a-street-address-into-coordinates-brief.md b/orbit-output/geocode-a-street-address-into-coordinates-brief.md
deleted file mode 100644
index 64bed9f..0000000
--- a/orbit-output/geocode-a-street-address-into-coordinates-brief.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Task brief: geocode a street address into latitude/longitude
-
-Generated by Orbit MCP `integrate`.
-
-**Task:** Geocode a street address into latitude/longitude coordinates, with a fallback provider if the
-primary returns no match.
-
-**Resources:**
-- `urn:orbit:endpoint:v1:1LKGXlgOcG8yPK3VhFCHNE60JlxB03MXIW5CoS2ccJgvfeT904cCPC7A9Jhwn:google:geocode`
-- `urn:orbit:endpoint:v1:aNIlwdaRLputqrxxn10U3re76azr1Y0s:apifreaks:forward-geocoding-search`
-- `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wC6IltepH9qOrLRZfOyXTl8wroVvRNLKfjqCWiuY530ygaI1g:esri:search-address`
-
----
-
-## FIT
-
-Fully. The supplied Google Maps, APIFreaks, and ArcGIS requests all geocode a street address and return
-coordinates, so they provide primary and fallback coverage. All three requests serve the task and are
-presented as alternatives; do not call more than one unless the preceding provider returns no match.
-
-## AUTH
-
-The alternatives use different authentication schemes:
-
-- **Google Maps (option 1):** API key in the query parameter `key`; supply the Google Maps Platform API key.
-- **APIFreaks (option 2):** API key in the query parameter `apiKey` as shown by the request; the collection
-  also documents the preferred `X-apiKey` header, but the request schema does not include that header.
-- **ArcGIS (option 3):** access token in the query parameter `token`.
-
-## BASE URL
-
-- Google Maps (option 1): `https://maps.googleapis.com`
-- APIFreaks (option 2): `https://api.apifreaks.com`
-- ArcGIS (option 3): `https://geocode-api.arcgis.com`
-
-## STEPS
-
-Choose one geocoding alternative; use the next option only if the previous one returns no match.
-
-### Option 1 — `GET /maps/api/geocode/json`
-
-Params:
-- `address` (string) — e.g. `1600 Amphitheatre Parkway, Mountain View, CA`; query parameter. Required unless
-  using `components` instead.
-- `key` (string) — your Google Maps Platform API key; query parameter.
-- `Accept` (string) — `application/json`; request header.
-- Also accepts: `bounds`, `components`, `latlng`, `location_type`, `place_id`, `result_type`, `language`,
-  `region` — query parameters.
-
-Returns: `200 OK` with a JSON object containing `results` (array). Each result may include
-`formatted_address`, `address_components` (array), `geometry` with `location.lat` and `location.lng`,
-`geometry.location_type`, `place_id`, and `types`; the top-level `status` is `OK` in the example.
-
-Threading: none.
-
-### Option 2 — `GET /v1.0/geocoder/search`
-
-Params:
-- `query` (string) — e.g. `1600 Amphitheatre Parkway, Mountain View, CA`; query parameter.
-- `apiKey` (string) — your APIFreaks API key; query parameter.
-- `limit` (integer) — e.g. `1` for a single best match; query parameter, optional, range 1–40.
-- `format` (string) — `json`; query parameter, optional.
-- `Accept` (string) — `application/json`; request header.
-- `Accept-Language` (string) — `en`; request header, optional.
-- Also accepts: `min_lat`, `max_lat`, `min_lon`, `max_lon` — query parameters for a complete viewbox.
-
-Returns: `200 OK` with a JSON array of result objects containing `lat` and `lon` numbers, plus fields such as
-`name`, `full_address`, and `bounding_box`. An invalid or missing key returns `401` with an error object
-containing `status` and `message`.
-
-Threading: none.
-
-### Option 3 — `GET /arcgis/rest/services/World/GeocodeServer/findAddressCandidates`
-
-Params:
-- `singleLine` (string) — e.g. `1600 Pennsylvania Ave NW, DC`; query parameter.
-- `f` (string) — `json`; query parameter.
-- `token` (string) — a valid ArcGIS access token; query parameter.
-
-Returns: `200 OK` with an object containing `spatialReference` (`wkid` and `latestWkid`) and `candidates`
-(array). Each candidate may contain `address`, `location.x` (longitude), `location.y` (latitude), `score`,
-`attributes`, and `extent`.
-
-Threading: none.
-
-## GOTCHAS
-
-- These providers are alternatives for the same geocoding capability, not sequential workflow steps. Try a
-  fallback only when the selected provider returns no match.
-- URL-encode address text and query parameters; Google address input and ArcGIS `singleLine` are query
-  parameters, not request bodies.
-- Google requires at least one of `address` or `components`; avoid duplicating the same address components in
-  both because this can produce zero results.
-- APIFreaks viewbox filtering requires all four coordinates (`min_lat`, `max_lat`, `min_lon`, `max_lon`)
-  together, with minimum values no greater than maximum values.
-- The collection has an empty APIFreaks `apiKeyValue`, and the ArcGIS `ACCESS_TOKEN` is unresolved in the
-  supplied data; provide valid credentials before calling.
-- Normalize coordinate conventions when switching providers: Google returns latitude as
-  `geometry.location.lat` and longitude as `geometry.location.lng`; APIFreaks returns `lat` and `lon`; ArcGIS
-  returns longitude in `location.x` and latitude in `location.y`.
-- APIFreaks successful calls may consume credits and may return an `X-AF-Credits-Cost` response header; its
-  example shows a cost of `2`.
diff --git a/orbit-output/geocode-an-address.md b/orbit-output/geocode-an-address.md
deleted file mode 100644
index b4781ec..0000000
--- a/orbit-output/geocode-an-address.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Orbit search: geocode an address
-
-Queries run against the Postman API Network via Orbit MCP `search`.
-
-## Query 1 — "geocode an address to latitude and longitude coordinates"
-
-### Geocode a set of addresses (Esri)
-- **Method:** POST
-- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses
-- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wIlJkgG3SsddzdPg120qLbT8jPv9KZ4Px1KW7Dr68cWfyziqn:esri:geocode-a-set-of-address`
-- **Evaluate Guide:** Batch geocodes multiple addresses through ArcGIS World Geocoding and returns matched location data.
-  - Use for: batch address geocoding, coordinate lookup, address matching
-  - Not supported: reverse geocoding, routing, map rendering
-
-### Geocode location A (Esri)
-- **Method:** GET
-- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
-- **ID:** `urn:orbit:endpoint:v1:MXWIl9HGTDmcWiItQRwD3gUh3ZEQSdm8FPNlbZA7YDStdvUN3KMgFMNQezk:postman:geocode-location-a`
-- **Evaluate Guide:** Geocodes one address with ArcGIS findAddressCandidates and returns candidate locations ranked by match quality.
-  - Use for: single-address geocoding, candidate matching, coordinate lookup
-  - Not supported: batch geocoding, reverse geocoding, route planning
-
-### Forward Geocode (Geocode Address → Coordinates) (Radar)
-- **Method:** GET
-- **URL:** https://api.radar.io/v1/geocode/forward
-- **ID:** `urn:orbit:endpoint:v1:aGr31osDAu5ruWnQqtVGDCATuOKMjyvj:radar:forward-geocode-geocode`
-- **Evaluate Guide:** No `evaluateGuide` returned. Description notes publishable-key auth, `query` as the only required
-  param, optional `layers` / `country` / `lang`, confidence values of exact/interpolated/fallback, and a default
-  rate limit of 10 rps.
-
-### Geocode address (Rhombus Systems)
-- **Method:** POST
-- **URL:** https://api2.rhombussystems.com/api/location/geoCode
-- **ID:** `urn:orbit:endpoint:v1:1JhNlBQCc1sts2sRHe0epV5cfTdtKjMEzGhhcubCitLILYU4Cm3nWPgPvB3Gm:rhombus:geocode-address`
-- **Evaluate Guide:** Converts an address into latitude and longitude coordinates using the Rhombus location service.
-  - Use for: address geocoding, coordinate lookup, location normalization
-  - Not supported: reverse geocoding, routing, map display
-
-### Lookup the latitude,longitude of an address (HPE Aruba Networking)
-- **Method:** GET
-- **URL:** https://172.16.3.20/gms/rest/location/addressToLocation
-- **ID:** `urn:orbit:endpoint:v1:1MvBXWcfBS1o5lqsUf9Fzwd5ermbKHMyh53VK0F3WSQNfBEaTiSPH2vyX3RbM:hpe:lookup-the-latitude-long`
-- **Evaluate Guide:** Resolves an address to an ordered array of matching latitude and longitude locations in EdgeConnect SD-WAN.
-  - Use for: address geocoding, best-match lookup, location resolution
-  - Not supported: reverse geocoding, routing, network configuration
-  - Note: private RFC1918 host — appliance-local, not a public service.
-
-Reverse-geocoding results also returned by this query (not a fit for forward geocoding): Pinball Map,
-Cloudmersive, Vedika, OpenWeather, Meteoprog, OneMap SG, Esri reverseGeocode.
-
-## Query 2 — "forward geocoding convert street address string into coordinates"
-
-### geocode (Google)
-- **Method:** GET
-- **URL:** https://maps.googleapis.com/maps/api/geocode/json
-- **ID:** `urn:orbit:endpoint:v1:1LKGXlgOcG8yPK3VhFCHNE60JlxB03MXIW5CoS2ccJgvfeT904cCPC7A9Jhwn:google:geocode`
-- **Evaluate Guide:** Supports address-to-coordinate and coordinate-to-address geocoding, including lookups by place identifier.
-  - Use for: forward geocoding, reverse geocoding, place ID lookup, mapping addresses
-  - Not supported: navigation, distance matrices, map imagery
-
-### Forward Geocoding - Search (Address to Coordinates) (APIFreaks)
-- **Method:** GET
-- **URL:** https://api.apifreaks.com/v1.0/geocoder/search
-- **ID:** `urn:orbit:endpoint:v1:aNIlwdaRLputqrxxn10U3re76azr1Y0s:apifreaks:forward-geocoding-search`
-- **Evaluate Guide:** Finds coordinates and structured location details from a free-form address, place, or landmark query.
-  - Use for: geocoding addresses, locating landmarks, resolving place names, getting bounding boxes
-  - Not supported: coordinate-to-address lookup, routing, map tiles
-
-### Forward Geocoding (Address to Coordinates) (APIFreaks — duplicate variant)
-- **Method:** GET
-- **URL:** https://api.apifreaks.com/v1.0/geocoder/search
-- **ID:** `urn:orbit:endpoint:v1:aNIlwdqeBGW8B9diAdC77BeVBZKt9iWC:apifreaks:forward-geocoding-addres`
-- **Evaluate Guide:** Finds WGS84 coordinates and structured address details from free-form address, place, or business queries.
-  - Use for: geocoding addresses, finding businesses, resolving place names, limiting results
-  - Not supported: coordinate-to-address lookup, routing, map tiles
-
-### Search address (Esri)
-- **Method:** GET
-- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
-- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5wC6IltepH9qOrLRZfOyXTl8wroVvRNLKfjqCWiuY530ygaI1g:esri:search-address`
-- **Evaluate Guide:** Geocodes one address or place description and returns matching location candidates.
-  - Use for: address search, place lookup, finding candidate coordinates
-  - Not supported: batch geocoding, reverse geocoding, route planning
-
-### Search street intersection (Esri)
-- **Method:** GET
-- **URL:** https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
-- **ID:** `urn:orbit:endpoint:v1:1I4Uh1tYHMK5x11h3g8SR0wVANRygVh6H2T5Wg3f1cisEC2FG2OHgtvn0eNxo:esri:search-street-intersecti`
-- **Evaluate Guide:** No `evaluateGuide` returned. Same operation as Search address with `category=intersection`.
-
-### Get Address (PositionStack, via a Postman demo collection)
-- **Method:** GET
-- **URL:** http://api.positionstack.com/v1/forward
-- **ID:** `urn:orbit:endpoint:v1:1I4UV9Fqy4Y3DrgUgFkLIEJ18gBzKrO9HqAFQSw8yzykvkIvK4d36OIcgnwMY:more:get-address`
-- **Evaluate Guide:** No `evaluateGuide` returned. Plain HTTP and wrapped in a Slack-bot demo collection.
-
-## Coverage notes
-
-- Both queries reported `meta.total: 15` with a `nextCursor` present; pagination caps at 40 results per query.
-  Further pages were not fetched.
-- Neither query surfaced Mapbox, HERE, OpenCage, or Nominatim.
diff --git a/skills/discover/SKILL.md b/skills/discover/SKILL.md
index c9ed534..e0807d1 100644
--- a/skills/discover/SKILL.md
+++ b/skills/discover/SKILL.md
@@ -1,16 +1,15 @@
 ---
-description: "Discover APIs from the Postman API Network using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick."
+description: "Discover APIs using Orbit's agent-friendly search. Returns endpoints with evaluateGuide fields showing what each API can and can't do, and can generate an integration task brief for the ones you pick."
 allowed-tools:
   - "mcp__plugin_orbit_orbit__search"
   - "mcp__plugin_orbit_orbit__integrate"
   - "Bash"
-  - "Write"
   - "Read"
 ---
 
 # orbit:discover
 
-Search the Postman API Network for APIs matching a capability query, then generate an
+Search Orbit for APIs matching a capability query, then generate an
 integration task brief for the endpoints you select.
 
 This plugin bundles Orbit's MCP server, so the `search` and `integrate` tools are
@@ -84,7 +83,7 @@ Group results under `## <capability query>` headings when multiple queries are r
   what it can't do, saving trial-and-error.
 - Both tools are read-only and safe to retry. On a rate-limit error, back off and retry.
 - Orbit is designed for agent consumption (compact payloads, structured guidance) vs
-  human browsing on the Postman API Network website.
+  human browsing of an API catalog in a web UI.
 
 ## Fallback