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

package/README.md

@@ -21,10 +21,10 @@ dependencies, ownership, runtime behavior, and the likely impact of a change.
 Install Postman in every compatible coding agent detected on your machine:
 
 ```bash
-npx @postman/postman-plugin@next
+npx @postman/postman-plugin
 ```
 
-One command configures **Claude Code, Codex, Cursor, Kimi Code and OpenCode**.
+One command configures **Claude Code, Codex, Cursor, Kimi Code, OpenCode and Pi**.
 Run it again to update, `status` to see what's installed, and `remove` to
 uninstall; `--agent <id>` limits any of them to one agent.
 
@@ -54,6 +54,18 @@ claude plugin install postman@postman
 codex plugin add postman@postman
 ```
 
+### Pi
+
+[View Postman in Pi's package gallery](https://pi.dev/packages/@postman/postman-plugin)
+
+```bash
+pi install npm:@postman/postman-plugin
+```
+
+`pi update npm:@postman/postman-plugin` updates it. Sign in to Postman's MCP
+server with `/mcp login postman` inside a Pi session. The shell's `pi mcp login`
+doesn't load extensions, so it reports no server named `postman`.
+
 ## Highlights
 
 ### Filesystem-first API development

package/dist/cli.js

@@ -20,7 +20,13 @@ Options:
   -y, --yes     Don't ask for confirmation (required when not in a terminal)
   --dry-run     Print what would change without changing anything
   -h, --help    Show this help
-  -v, --version Show the version`;
+  -v, --version Show the version
+
+Exit codes:
+  0  Done, or nothing needed doing
+  1  Something failed or was blocked, you cancelled, or install found no agent
+  2  Bad usage, or confirmation needed but no terminal (use --yes)
+  3  Done, except a step only you can do (printed as "next:")`;
 function version() {
     const manifest = new URL('../package.json', import.meta.url);
     return JSON.parse(fs.readFileSync(manifest, 'utf8')).version;

package/dist/hosts/index.js

@@ -3,4 +3,5 @@ import { codex } from './codex.js';
 import { cursor } from './cursor.js';
 import { kimi } from './kimi.js';
 import { opencode } from './opencode.js';
-export const HOSTS = [claudeCode, codex, cursor, kimi, opencode];
+import { pi } from './pi.js';
+export const HOSTS = [claudeCode, codex, cursor, kimi, opencode, pi];

package/dist/hosts/kimi.js

@@ -46,10 +46,13 @@ export const kimi = {
             if (!(await system.which('npx'))) {
                 blocked('npx is not on PATH');
             }
-            await mustRun(system, 'npx', ['-y', PLUGINS_CLI, 'add', REPO, '--target', 'kimi', '--yes'], {
+            // Only picks the verb: an unreadable store must not stop the install that could repair it.
+            const installed = await kimi.status(system).then((status) => status.installed, () => null);
+            // An explicit --package outranks the npm_config_package an outer `npx -p` exports to us.
+            await mustRun(system, 'npx', ['-y', `--package=${PLUGINS_CLI}`, 'plugins', 'add', REPO, '--target', 'kimi', '--yes'], {
                 env: { DISABLE_TELEMETRY: '1', DO_NOT_TRACK: '1' }
             });
-            return result('done', `installed ${PLUGIN_ID} into ${kimiHome(system)}`, NEXT);
+            return result('done', `${installed ? 'updated' : 'installed'} ${PLUGIN_ID} in ${kimiHome(system)}`, NEXT);
         });
     },
     async remove(system) {

package/dist/hosts/pi.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { PI_SOURCE, REPO, isSameRepo, redact } from '../source.js';
+import { failed, guard, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+const NEXT = 'Restart Pi, or run `/reload` in an open session, for the change to take effect.', GIT_PREFIX = /^git:/, 
+// Pi's ref is everything after the first `@` in the repo path, slashes included. The path starts
+// after the scp-style `host:` or after the host, so an `@` in URL user-info is never a ref.
+SCP_WITH_REF = /^(git@[^:]+:[^@]*)@/, URL_WITH_REF = /^((?:[a-z][a-z0-9+.-]*:\/\/)?[^/]*\/[^@]*)@/i;
+function agentDir(system) {
+    const dir = system.env.PI_CODING_AGENT_DIR;
+    if (!dir) {
+        return path.join(system.home, '.pi', 'agent');
+    }
+    return dir === '~' || dir.startsWith('~/') ? path.join(system.home, dir.slice(1)) : dir;
+}
+function withoutRef(source) {
+    const url = source.replace(GIT_PREFIX, '');
+    return (url.match(SCP_WITH_REF) ?? url.match(URL_WITH_REF))?.[1] ?? url;
+}
+// Pi keys an npm package by its name, so a pinned `npm:@postman/postman-plugin@x` is this
+// package too. A git install of this repo is another package loading the same skills.
+const settingsFile = (system) => path.join(agentDir(system), 'settings.json'), isOurPackage = (source) => source === PI_SOURCE || source.startsWith(`${PI_SOURCE}@`), isRepoClone = (source) => !source.startsWith('npm:') && isSameRepo(withoutRef(source), REPO);
+/** Every package source in Pi's user settings, or `null` when the file can't be parsed. */
+async function packageSources(system) {
+    const text = await system.readFile(settingsFile(system));
+    if (text === null) {
+        return [];
+    }
+    // Pi parses the file the same way, so a file that fails here fails in `pi` too.
+    const settings = parseJson(text.replace(/^\uFEFF/, ''));
+    if (!settings || (settings.packages !== undefined && !Array.isArray(settings.packages))) {
+        return null;
+    }
+    return (settings.packages ?? [])
+        .map((entry) => (typeof entry === 'string' ? entry : entry?.source))
+        .filter((source) => typeof source === 'string');
+}
+async function readableSources(system) {
+    return (await packageSources(system)) ?? failed(`${settingsFile(system)} is not valid JSON; fix it and re-run`);
+}
+export const pi = {
+    id: 'pi',
+    name: 'Pi',
+    route: 'installer/package.json',
+    async detect(system) {
+        return (await system.which('pi')) !== null;
+    },
+    async status(system) {
+        const sources = await packageSources(system);
+        if (sources === null) {
+            return { installed: null, detail: `could not read ${settingsFile(system)}`, notes: [] };
+        }
+        const ours = sources.find(isOurPackage), notes = [
+            ...(ours && ours !== PI_SOURCE ? [`${ours} is pinned, so an update leaves it at that version`] : []),
+            ...sources.filter(isRepoClone).map((source) => `${redact(source)} loads the same skills and will be removed`)
+        ];
+        return ours ?
+            { installed: true, detail: `${ours} in ${settingsFile(system)}`, notes } :
+            { installed: false, detail: 'not installed', notes };
+    },
+    install(system) {
+        return guard(async () => {
+            const sources = await readableSources(system), installed = sources.some(isOurPackage);
+            // Replacement first: if it fails, a git copy of this repo is still a working one.
+            await mustRun(system, 'pi', [installed ? 'update' : 'install', PI_SOURCE]);
+            for (const source of sources.filter(isRepoClone)) {
+                await mustRun(system, 'pi', ['remove', source]);
+            }
+            return result('done', `${installed ? 'updated' : 'installed'} ${PI_SOURCE} in ${settingsFile(system)}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const sources = await readableSources(system), targets = [...(sources.some(isOurPackage) ? [PI_SOURCE] : []), ...sources.filter(isRepoClone)];
+            if (!targets.length) {
+                return result('skipped', 'not installed');
+            }
+            for (const source of targets) {
+                await mustRun(system, 'pi', ['remove', source]);
+            }
+            return result('done', `removed ${targets.map(redact).join(', ')}`, NEXT);
+        });
+    }
+};

package/dist/pi-extension.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** In the tarball, where `prepack` staged the repo's shared files beside `dist/`. */
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), ENTRY_SKILL = 'api-engineer', SECTION = 'postman';
+/** Pi's skill names are un-namespaced; the shared mandate names them `postman:<skill>` for the other routes. */
+export function toPiSessionContext(source) {
+    return source.replace(/`postman:([a-z0-9-]+)`/g, '`$1`');
+}
+/** Reads the mandate and the MCP config from `root`, which is laid out like the repository root. */
+export function postmanExtension(root) {
+    return (pi) => {
+        const mandate = toPiSessionContext(fs.readFileSync(path.join(root, 'hooks', 'session-start-context.md'), 'utf8')), { mcpServers } = JSON.parse(fs.readFileSync(path.join(root, 'mcp.pi.json'), 'utf8'));
+        // A `postman` server in the user's own mcp.json takes precedence over this registration.
+        for (const [name, server] of Object.entries(mcpServers)) {
+            pi.registerMcpServer(name, server);
+        }
+        // Pi's stand-in for the SessionStart hook. The mandate routes to a skill, so it goes only
+        // where that skill loaded; `pi config` can disable it.
+        pi.on('before_agent_start', ({ systemPromptOptions }) => {
+            if (systemPromptOptions.skills.some((skill) => skill.name === ENTRY_SKILL)) {
+                systemPromptOptions.sections[SECTION] = mandate;
+            }
+        });
+    };
+}
+export default postmanExtension(packageRoot);

package/dist/run.js

@@ -1,6 +1,5 @@
-export const EXIT = { ok: 0, failed: 1, usage: 2 };
-// `manual` counts: the command did not finish, and a script needs to know the user has a step left.
-const INCOMPLETE = ['failed', 'blocked', 'manual'];
+export const EXIT = { ok: 0, failed: 1, usage: 2, manual: 3 };
+const FAILED = ['failed', 'blocked'];
 function padEnd(text, width) {
     return text + ' '.repeat(Math.max(1, width - text.length));
 }
@@ -76,11 +75,15 @@ export async function run(system, hosts, options) {
         }
     }
     if (!targets.length) {
-        system.log(`No supported coding agent found. Supported: ${joinNames(requested)}.`);
+        system.log(options.agents.length ?
+            'None of the requested agents was found.' :
+            `No supported coding agent found. Supported: ${joinNames(requested)}.`);
         reports.forEach((report) => system.log(`  ${report.result.message}`));
-        return reports.length && options.command !== 'status' ? EXIT.failed : EXIT.ok;
+        // Nothing to remove is a clean remove; nothing to install into is not a successful install.
+        return options.command === 'install' || (options.command === 'remove' && reports.length) ? EXIT.failed : EXIT.ok;
     }
-    system.log('Found:');
+    // "Found:" over "not installed" read to agents as "not found"; the header says both things.
+    system.log(`Found ${targets.length} coding agent${targets.length === 1 ? '' : 's'}. Postman in each:`);
     printStatuses(system, targets, width);
     reports.forEach((report) => system.log(`  ${padEnd(report.host.name, width)}${report.result.message}`));
     if (options.command === 'status') {
@@ -90,12 +93,12 @@ export async function run(system, hosts, options) {
     // remove also clears duplicates and half-finished installs that status doesn't count.
     const command = options.command;
     if (!options.yes && !system.dryRun) {
+        const verb = command === 'install' ? 'install or update Postman in' : 'remove Postman from', names = joinNames(targets.map((target) => target.host));
         if (!options.isTTY) {
-            system.log('\nNot running in a terminal, so there is no one to confirm. Re-run with --yes.');
+            system.log(`\nNothing changed: there is no terminal to confirm in. To ${verb} ${names}, re-run with --yes (add --agent <id> for only some).`);
             return EXIT.usage;
         }
-        const verb = command === 'install' ? 'Install or update Postman in' : 'Remove Postman from';
-        if (!(await options.confirm(`\n${verb} ${joinNames(targets.map((target) => target.host))}? [Y/n] `))) {
+        if (!(await options.confirm(`\n${verb[0].toUpperCase()}${verb.slice(1)} ${names}? [Y/n] `))) {
             system.log('Cancelled.');
             return EXIT.failed;
         }
@@ -110,5 +113,8 @@ export async function run(system, hosts, options) {
     for (const { host, result } of reports) {
         system.log(`  ${padEnd(host.name, width)}${padEnd(result.outcome, 9)}${result.message.split('\n')[0]}`);
     }
-    return reports.some(({ result }) => INCOMPLETE.includes(result.outcome)) ? EXIT.failed : EXIT.ok;
+    if (reports.some(({ result }) => FAILED.includes(result.outcome))) {
+        return EXIT.failed;
+    }
+    return reports.some(({ result }) => result.outcome === 'manual') ? EXIT.manual : EXIT.ok;
 }

package/dist/source.js

@@ -1,8 +1,10 @@
-/** Where every host's copy of the plugin comes from. The npm package carries no skills. */
+/** Where every host's copy of the plugin comes from. Pi alone installs the npm package instead. */
 export const REPO = 'postmanlabs/postman-plugin';
 export const GIT_URL = `https://github.com/${REPO}.git`;
 /** The branch every clone this installer makes tracks. */
 export const BRANCH = 'main';
+/** Unpinned, so `pi update` moves it with each `latest` release; test/pi-package.test.js checks the name. */
+export const PI_SOURCE = 'npm:@postman/postman-plugin';
 /** Must stay byte-identical to the shim in opencode/README.md; test/routes.test.js enforces it. */
 export const OPENCODE_SHIM = "export { default } from '../postman-plugin/opencode/src/index.ts';\n";
 /** Pinned: this third-party CLI writes Kimi's plugin store for us, and an unpinned npx would run whatever is latest. */

package/hooks/session-start-context.md

@@ -0,0 +1,11 @@
+<EXTREMELY_IMPORTANT>
+You have the Postman plugin.
+
+Before responding to any non-trivial API engineering task — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API or Postman Flow — load the `postman:api-engineer` skill and follow it. It is the default entry point and routes to the specific postman skills from there. Pure questions and trivial one-line edits don't need it.
+
+When the intent is already specific, you may enter directly into the relevant skill instead: `postman:bootstrap` (link this repo to a Postman workspace), `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`.
+
+If you were dispatched as a subagent to execute a specific task, ignore this block — `postman:api-engineer` governs the orchestrating session, and it already shaped your dispatch.
+
+User instructions (project instruction files such as AGENTS.md or CLAUDE.md, and direct requests) take precedence over this mandate.
+</EXTREMELY_IMPORTANT>

package/mcp.pi.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "postman": {
+      "type": "http",
+      "url": "https://mcp.postman.com/mcp",
+      "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
+      "headers": {
+        "X-Source": "postman-pi-plugin",
+        "X-Plugin-Version": "0.1.2",
+        "User-Agent": "postman-pi-plugin/0.1.2"
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.1.1-rc.0",
-  "description": "Installs the Postman plugin into every supported coding agent on this machine.",
+  "version": "0.1.2",
+  "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",
   "author": {
@@ -17,6 +17,8 @@
   },
   "bugs": "https://github.com/postmanlabs/postman-plugin/issues",
   "keywords": [
+    "pi-package",
+    "pi",
     "postman",
     "claude-code",
     "codex",
@@ -29,13 +31,26 @@
     "postman-plugin": "dist/cli.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "skills/",
+    "hooks/session-start-context.md",
+    "mcp.pi.json"
   ],
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://assets.getpostman.com/common-share/postman-logo-horizontal-320x132.png"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build && node scripts/pack-docs.js stage",
-    "postpack": "node scripts/pack-docs.js clean",
-    "test": "npm run build && node --test test/*.test.js"
+    "prepack": "npm run build && node scripts/pack-repo-files.js stage",
+    "postpack": "node scripts/pack-repo-files.js clean",
+    "test": "npm run build && node --test test/*.test.js",
+    "test:pi-harness": "node scripts/pi-harness.js"
   },
   "devDependencies": {
     "@types/node": "24.5.2",

package/skills/ai-readiness/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ai-readiness
+description: Scores a Postman collection or an OpenAPI spec for how well an AI agent can discover, understand, call, and recover from errors with it — missing examples, undocumented errors, and ambiguous parameters all cost points. Use when the user asks "is my API agent-ready," "can AI agents use my API," "how agent-friendly is my API," or wants to scan, score, or improve a collection or spec for AI/agent consumption. Covers `postman collection ai-readiness` and `postman spec ai-readiness`.
+---
+
+# AI Readiness
+
+## Overview
+
+An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet.
+
+Two ways to run this check, same rubric family, different target — pick by what exists:
+
+- `collection ai-readiness <collectionId/path>` scores a Postman collection
+  — by cloud ID, local file path, or a `postman/collections/<name>`
+  local-mode directory.
+- `spec ai-readiness <spec>` scores an OpenAPI specification directly — by
+  cloud ID or local file path — with no collection involved at all.
+
+
+
+## Scoring
+
+The command computes and prints the score itself — read the fields it
+gives you, don't recompute them:
+
+- **`readiness`** (score 0-100 + bucket) is the headline number. Buckets,
+  low to high: **Limited → Fair → Good → Excellent**.
+- **`confidence`** (`high`/`medium`/`low`) says how many signals it
+  could actually measure vs. had to mark `unknown` — a data-quality
+  caveat, not part of the score.
+
+## Interpreting Results
+
+Report the bucket, score, and confidence the command actually printed
+— don't infer a percentage band. Doc coverage is a modifier via its
+adjustment, not a separate gate; call it out by name when it's `low`,
+since recommendations flag that first. Also state which verb ran
+(`collection` vs. `spec` `ai-readiness`), which target was scored
+(local path vs. cloud ID), the output mode, and — if `--min-score` was
+set — the resulting exit code, not just "it passed."
+
+You can ask user if they would like to set this check with a min score guarantee to run on their CI.
+
+## Reference
+
+- `collection-schema-v3` skill — what saved examples and descriptions look
+  like in the git-synced format this command reads.
+- `ci-integration` skill — where `--min-score` fits as a pipeline gate
+  alongside `spec lint`/`collection lint`/`workspace lint`.

package/skills/api-discovery/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: api-discovery
+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
+
+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`
+
+`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.
+
+```bash
+postman search requests "where do we validate a user's email?"
+postman search collections "payments" --ownership external --filter "visibility=public"
+```
+
+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-graph`
+
+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` 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
+
+- [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.

package/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.

package/skills/api-documentation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: api-documentation
+description: Generate filesystem-first agent friendly api documentation that you can share with your teammates without hassle. Use when the user asks to "publish API docs," "generate documentation for this API," "put this on the API Network," "share a docs link for this collection or spec," or "why do my docs look empty." 
+---
+The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.
+
+# API Documentation
+When working on any API task, the first step is to establish and capture the contract.
+API documentation can be done in two predominant ways:
+1. through a Postman collection,
+2. with an OpenAPI spec
+
+It is recommended to create both. They serve different, complementary use cases, and it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, **collection-schema-v3**.
+Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or spec.
+
+Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
+
+## Good practices for API design
+
+See [reference/rest-api-best-practices.md](reference/rest-api-best-practices.md)
+for the practices well-documented APIs tend to already follow: resource
+naming, HTTP method/status-code usage, error response shape, versioning,
+pagination, filtering, auth, idempotency, and backward compatibility. A
+spec or collection that already follows these renders documentation with
+nothing left to fix.
+
+### Examples
+Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
+1. anyone can look at them to see how your API behaves,
+2. they can be used to generate a mock from your collection in a single command.
+
+## Workflow
+1. Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
+2. Choose the instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.