@postman/postman-plugin 0.2.0 → 0.2.1-rc.1

package/README.md

@@ -35,29 +35,35 @@ You can also use the following commands to install individually:
 [View Postman on Claude Plugins](https://claude.com/plugins/postman)
 
 ```bash
-claude plugin install postman@postman
+claude plugin marketplace add anthropics/claude-plugins-official
+claude plugin install postman@claude-plugins-official
 ```
 
-### Cursor
-
-[View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman)
-
-```text
-/add-plugin postman
-```
+The first command registers Anthropic's official marketplace, which a fresh
+Claude Code doesn't have until an interactive session gets past sign-in. It
+does nothing where the marketplace is already registered.
 
 ### Codex
 
 [View Postman on ChatGPT Plugins](https://chatgpt.com/plugins/postman?open_in_app)
 
 ```bash
+codex plugin marketplace add postmanlabs/postman-plugin
 codex plugin add postman@postman
 ```
 
+### Cursor
+
+[View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman)
+
+```text
+/add-plugin postman
+```
+
 ### Factory Droid
 
 ```bash
-droid plugin marketplace add postmanlabs/postman-plugin
+droid plugin marketplace add https://github.com/postmanlabs/postman-plugin.git
 droid plugin install postman@postman-plugin --scope user
 ```
 
@@ -65,6 +71,23 @@ droid plugin install postman@postman-plugin --scope user
 `droid plugin update postman@postman-plugin --scope user`, updates it. Sign in
 to Postman's MCP server with `/mcp` inside a Droid session.
 
+### Kimi Code
+
+Inside a Kimi Code session:
+
+```text
+/plugins install https://github.com/postmanlabs/postman-plugin/tree/main
+```
+
+Then run `/new` to start a session with the plugin. Run the same command again,
+then `/new`, to update; `/plugins remove postman` removes it. Sign in to
+Postman's MCP server with `/mcp-config login plugin-postman:postman`.
+
+### OpenCode
+
+OpenCode loads Postman from a clone of this repository and a one-line loader
+file. [opencode/README.md](https://github.com/postmanlabs/postman-plugin/blob/main/opencode/README.md#install) has the commands.
+
 ### Pi
 
 [View Postman in Pi's package gallery](https://pi.dev/packages/@postman/postman-plugin)

package/dist/hosts/claude-code.js

@@ -1,10 +1,15 @@
-import { redact } from '../source.js';
+import { isSameRepo, redact } from '../source.js';
 import { blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
 import { result } from './types.js';
 // Anthropic's catalog entry is the Claude Code install; our own marketplace
 // would register the same skills a second time under `postman@postman`.
 const MARKETPLACE = { name: 'claude-plugins-official', repo: 'anthropics/claude-plugins-official' }, PLUGIN_ID = `postman@${MARKETPLACE.name}`, SHADOW_IDS = ['postman@postman'], SCOPE = 'user', NEXT = 'Restart Claude Code for the change to take effect.';
 const isOurs = (plugin) => plugin.id === PLUGIN_ID || SHADOW_IDS.includes(plugin.id);
+// A `url` source fetches one marketplace.json instead of cloning, so a URL names the repo only in a `git` source.
+function isOfficialSource(marketplace) {
+    return isSameRepo(marketplace.repo, MARKETPLACE.repo) ||
+        (marketplace.source === 'git' && isSameRepo(marketplace.url, MARKETPLACE.repo));
+}
 function listPlugins(system) {
     return mustProbeJson(system, 'claude', ['plugin', 'list', '--json']);
 }
@@ -21,7 +26,7 @@ async function refreshMarketplace(system) {
         await mustRun(system, 'claude', ['plugin', 'marketplace', 'add', MARKETPLACE.repo, '--scope', SCOPE]);
         return;
     }
-    if (existing.repo !== MARKETPLACE.repo) {
+    if (!isOfficialSource(existing)) {
         const source = existing.repo ?? existing.url ?? existing.path;
         blocked(`marketplace ${MARKETPLACE.name} is registered from ${source ? redact(source) : 'an unknown source'}, not ${MARKETPLACE.repo}`);
     }

package/dist/hosts/cursor.js

@@ -1,18 +1,30 @@
 import path from 'node:path';
 import { guard, removeClone, syncClone } from './shared.js';
 import { result } from './types.js';
-// Cursor has no command to install a plugin, but loads any plugin folder under
-// plugins/local. Its Marketplace keeps its own copy under plugins/cache.
-const localClone = (system) => path.join(system.home, '.cursor', 'plugins', 'local', 'postman'), marketplaceCopy = (system) => path.join(system.home, '.cursor', 'plugins', 'cache', 'cursor-public', 'postman'), NEXT = 'Reload the Cursor window (Developer: Reload Window) for the change to take effect.', 
+// Cursor has no command to install a plugin, but its editor loads any plugin folder under
+// plugins/local; its CLI doesn't. Its Marketplace keeps its own copy under plugins/cache.
+const localClone = (system) => path.join(system.home, '.cursor', 'plugins', 'local', 'postman'), marketplaceCopy = (system) => path.join(system.home, '.cursor', 'plugins', 'cache', 'cursor-public', 'postman'), NEXT = 'Reload the Cursor window (Developer: Reload Window) for the change to take effect.', cliOffPath = (system) => path.join(system.home, '.local', 'bin', 'cursor-agent'), 
 // Cursor keeps a disabled Marketplace copy on disk and records "enabled" only in its
 // private state database, so the copy being there doesn't mean Postman is active.
 CHECK_ENABLED = 'If Postman isn\'t active in Cursor, enable it in Cursor Settings > Plugins.', MAYBE_TWICE = 'The Cursor Marketplace copy is present too; if it\'s enabled, Postman loads twice, so disable one in Cursor Settings > Plugins.';
+// Until https://github.com/postmanlabs/postman-plugin/issues/82 is fixed. Names the CLI by its path when
+// it isn't on PATH, which detect() accepts.
+async function cliNext(system) {
+    const cli = (await system.which('cursor-agent')) === null && await system.exists(cliOffPath(system)) ?
+        `"${cliOffPath(system)}"` :
+        'cursor-agent';
+    return `The Cursor CLI doesn't load plugins from there; start it with \`${cli} --plugin-dir "${localClone(system)}"\`.`;
+}
 export const cursor = {
     id: 'cursor',
     name: 'Cursor',
     route: '.cursor-plugin',
     async detect(system) {
-        return (await system.which('cursor')) !== null ||
+        // The Cursor CLI creates ~/.cursor only on its first run, and its installer can't put
+        // ~/.local/bin on the PATH of the shell that ran it. It also installs `agent`, a name
+        // too generic to mean Cursor.
+        return (await system.which('cursor')) !== null || (await system.which('cursor-agent')) !== null ||
+            await system.exists(cliOffPath(system)) ||
             (system.platform === 'darwin' && await system.exists('/Applications/Cursor.app')) ||
             await system.exists(path.join(system.home, '.cursor'));
     },
@@ -39,7 +51,8 @@ export const cursor = {
             // An existing clone is kept even next to the Marketplace copy, which may be
             // disabled: a duplicate is visible and fixable, deleting the working copy is not.
             const action = await syncClone(system, localClone(system));
-            return result('done', `${action} ${localClone(system)}`, fromMarketplace ? `${NEXT} ${MAYBE_TWICE}` : NEXT);
+            const next = `${NEXT} ${await cliNext(system)}`;
+            return result('done', `${action} ${localClone(system)}`, fromMarketplace ? `${next} ${MAYBE_TWICE}` : next);
         });
     },
     remove(system) {

package/dist/pi-extension.js

@@ -2,7 +2,7 @@ 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';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'), ENTRY_SKILL = 'api-engineer', SECTION = 'postman', MCP_NEEDS_NEWER_PI = 'Postman\'s MCP server needs Pi 0.99.0 or later; run `pi update` to upgrade Pi.';
 /** 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`');
@@ -11,16 +11,31 @@ export function toPiSessionContext(source) {
 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);
+        // An extension that throws while loading stops every Pi session from starting, so an older
+        // Pi still gets the skills and the mandate. Print and JSON modes drop the notice.
+        if (typeof pi.registerMcpServer === 'function') {
+            // 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);
+            }
+        }
+        else {
+            pi.on('session_start', (_event, { ui }) => ui.notify(MCP_NEEDS_NEWER_PI, 'warning'));
         }
         // 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;
+        pi.on('before_agent_start', (event) => {
+            const { sections, skills } = event.systemPromptOptions;
+            if (!skills.some((skill) => skill.name === ENTRY_SKILL)) {
+                return;
+            }
+            if (sections) {
+                sections[SECTION] = mandate;
+                return;
             }
+            // From Pi 0.86.0 a returned prompt replaces the sectioned one whole, so only a Pi
+            // without sections gets one.
+            return { systemPrompt: `${event.systemPrompt}\n\n<${SECTION}>\n${mandate}\n</${SECTION}>` };
         });
     };
 }

package/mcp.pi.json

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

package/package.json

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

package/skills/postman-mcp-server/references/docs.md

@@ -9,7 +9,7 @@ Analyze, improve, and publish API documentation from OpenAPI specs and Postman c
 
 ## Prerequisites
 
-The Postman MCP Server must be connected for Postman operations. Local spec analysis works without MCP. If needed, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+The Postman MCP Server must be connected for Postman operations. Local spec analysis works without MCP. If needed, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -81,8 +81,8 @@ If both a spec and collection exist, keep them in sync:
 
 ## Error Handling
 
-- **MCP not configured:** Local markdown docs can be generated without MCP. For Postman publishing: "Run `/postman:setup` to configure the Postman MCP Server."
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **MCP not configured:** Local markdown docs can be generated without MCP. For Postman publishing, follow `references/setup.md` to connect the Postman MCP Server.
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **Invalid spec:** Report parse errors and offer to fix common YAML/JSON syntax issues.
 - **Plan limitations:** "Publishing documentation may require a paid Postman plan. Check https://www.postman.com/pricing/"
 - **Too many results:** Ask the user to specify a collection by name.

package/skills/postman-mcp-server/references/learn.md

@@ -7,16 +7,16 @@ allowed-tools: Read, mcp__postman__searchLearningCenter, mcp__postman__getEnable
 
 Answer "how do I..." questions about the Postman product by searching the official Postman Learning Center (https://learning.postman.com). Explain features, walk through workflows, and cite authoritative sources.
 
-Use this to learn *about Postman itself* — not to search the user's own collections, workspaces, or specs (that's `/postman:search`).
+Use this to learn *about Postman itself* — not to search the user's own collections, workspaces, or specs (that's `references/search.md`).
 
 ## Prerequisites
 
-This command uses `searchLearningCenter`, which the Postman MCP Server exposes only in **Full mode**.
+This workflow uses `searchLearningCenter`, which the Postman MCP Server exposes only in **Full mode**.
 
 The mode is fixed by the endpoint in each route's MCP config, not by the environment. A route pinned to `https://mcp.postman.com/mcp` has the tool; a route pinned to `https://mcp.postman.com/minimal` does not. Read it off the route's own MCP config rather than inferring it from the agent's name — which endpoint an agent gets is a per-route product decision, and new routes are added. **`POSTMAN_MCP_MODE` is not read on any route** — never tell the user to set or unset it to change the tool set.
 
-- If MCP tools aren't available at all, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
-- If `searchLearningCenter` is missing, call `getEnabledTools` to confirm the active tool set, then split on which endpoint the route is pinned to. On a `/minimal` route it is absent by design and the user cannot change it from the client: say the Learning Center tool isn't part of that route's tool set and point them at https://learning.postman.com to search directly. On a `/mcp` route its absence is not a mode problem — the server isn't connected as configured: "Run `/postman:setup` to configure the Postman MCP Server."
+- If MCP tools aren't available at all, follow `references/setup.md` to connect the Postman MCP Server.
+- If `searchLearningCenter` is missing, call `getEnabledTools` to confirm the active tool set, then split on which endpoint the route is pinned to. On a `/minimal` route it is absent by design and the user cannot change it from the client: say the Learning Center tool isn't part of that route's tool set and point them at https://learning.postman.com to search directly. On a `/mcp` route its absence is not a mode problem — the server isn't connected as configured: follow `references/setup.md` to reconnect it.
 
 Do not answer a "how do I..." question from memory when the tool is unavailable. Cite only URLs the tool returned, or send the user to the Learning Center.
 
@@ -38,16 +38,16 @@ Read the returned passages and compose a direct answer to the user's question. D
 - If the docs reveal a better or officially recommended workflow than what the user asked, surface it.
 - Always cite the source URLs the tool returns so the user can read more.
 
-### Step 3: Connect to the Plugin
+### Step 3: Offer a Matching Workflow
 
-When a workflow maps to a plugin command, point the user there so they can act immediately:
+When the answer maps to one of this skill's workflows, offer to run it so the user can act immediately:
 
-- Creating/updating collections from a spec → `/postman:sync`
-- Finding APIs in their org or the public network → `/postman:search`
-- Running collection tests → `/postman:test`
-- Creating mock servers → `/postman:mock`
-- Generating or publishing docs → `/postman:docs`
-- Security auditing → `/postman:security`
+- Creating/updating collections from a spec → `references/sync.md`
+- Finding APIs in their org or the public network → `references/search.md`
+- Running collection tests → `references/test.md`
+- Creating mock servers → `references/mock.md`
+- Generating or publishing docs → `references/docs.md`
+- Security auditing → `references/security.md`
 
 ## Output
 
@@ -60,14 +60,14 @@ To create a mock server in Postman:
   4. Postman returns a mock URL that serves your examples.
 
   Mock servers read from saved examples, so add examples first if you
-  have none — the plugin can do this for you via /postman:mock.
+  have none — I can create the mock and its examples for you.
 
   Source: https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/
 ```
 
 ## Error Handling
 
-- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
-- **`searchLearningCenter` unavailable:** Confirm with `getEnabledTools`. Expected on any route pinned to the `minimal` endpoint — say the tool isn't in that route's tool set and point the user at https://learning.postman.com. On a `/mcp` route: "Run `/postman:setup` to configure the Postman MCP Server."
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
+- **`searchLearningCenter` unavailable:** Confirm with `getEnabledTools`. Expected on any route pinned to the `minimal` endpoint — say the tool isn't in that route's tool set and point the user at https://learning.postman.com. On a `/mcp` route: follow `references/setup.md` to reconnect it.
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **No results:** "Nothing matched in the Learning Center. Try rephrasing with the Postman feature name, or ask about a more specific step."

package/skills/postman-mcp-server/references/mcp-limitations.md

@@ -1,6 +1,6 @@
 # Known MCP Limitations
 
-These limitations are documented so they are handled correctly in all commands and workflows.
+These limitations are documented so they are handled correctly in all workflows.
 
 ## generateCollection is Async
 

package/skills/postman-mcp-server/references/mock.md

@@ -9,7 +9,7 @@ Spin up a Postman mock server from a collection or spec. Get a working mock URL
 
 ## Prerequisites
 
-The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+The Postman MCP Server must be connected. If MCP tools aren't available, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -94,8 +94,8 @@ If the user wants the mock publicly accessible:
 
 ## Error Handling
 
-- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
 - **No examples in collection:** Auto-generate from schemas (Step 2). If no schemas either, ask the user to provide sample responses.
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **MCP timeout:** Retry once. If it still fails, check https://status.postman.com for outages.
 - **Plan limitations:** "Mock server creation may require a Postman Basic plan or higher for increased usage limits."

package/skills/postman-mcp-server/references/search.md

@@ -9,7 +9,7 @@ Answer natural language questions about available APIs across Postman workspaces
 
 ## Prerequisites
 
-The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+The Postman MCP Server must be connected. If MCP tools aren't available, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -77,7 +77,7 @@ List relevant collections with endpoint counts, then ask which to explore furthe
 
 ## Error Handling
 
-- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
 - **No results:** "Nothing matched your query. Try different keywords, broaden `ownership` to `all`, or browse the user's workspaces with `getWorkspaces` + `getCollections`."
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **Too many results:** Ask the user to be more specific. Suggest filtering by workspace or using tags.

package/skills/postman-mcp-server/references/security.md

@@ -9,7 +9,7 @@ Audit your API for security issues: missing auth, exposed sensitive data, insecu
 
 ## Prerequisites
 
-For collection auditing, the Postman MCP Server must be connected. Local spec auditing works without MCP. If needed, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+For collection auditing, the Postman MCP Server must be connected. Local spec auditing works without MCP. If needed, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -122,8 +122,8 @@ After fixes, re-run the audit to show improvement.
 
 ## Error Handling
 
-- **MCP not configured:** Local spec auditing works without MCP. For Postman-specific checks: "Run `/postman:setup` to configure the Postman MCP Server."
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **MCP not configured:** Local spec auditing works without MCP. For Postman-specific checks, follow `references/setup.md` to connect the Postman MCP Server.
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **No spec found:** Ask the user for the path. Offer to audit a Postman collection directly via MCP.
 - **Spec too large:** For large specs (100+ endpoints), audit in batches by tag or path prefix.
 - **Plan limitations:** "Some audit features may require a paid Postman plan. Check https://www.postman.com/pricing/"

package/skills/postman-mcp-server/references/setup.md

@@ -5,7 +5,7 @@ allowed-tools: mcp__postman__authenticate, mcp__postman__complete_authentication
 
 # First-Run Configuration
 
-Walk the user through Postman setup for Claude Code. Validate everything works before they use other commands.
+Walk the user through Postman MCP setup. Validate everything works before moving on to other Postman tasks.
 
 ## Workflow
 
@@ -48,7 +48,7 @@ I'll generate an authorization URL. Open it in your browser, sign in, and paste
      ```
    - If tools are still unavailable after retries:
      ```
-     The server hasn't reconnected yet. Restart Claude Code and run /postman:setup again.
+     The server hasn't reconnected yet. Restart your agent, then ask me to check the Postman connection again.
      Your OAuth token is already saved — you won't need to re-authorize.
      ```
 6. Once `getAuthenticatedUser` succeeds, proceed to Step 4.
@@ -101,41 +101,41 @@ You're all set.
 
 If workspace is empty:
 ```
-Your workspace is empty. You can:
-  /postman:sync     — Push a local OpenAPI spec to Postman
-  /postman:search   — Search for APIs across your org's resources or the public Postman network
+Your workspace is empty. You can ask me to:
+  - Push a local OpenAPI spec to Postman
+  - Search for APIs across your org's resources or the public Postman network
 ```
 
-### Step 5: Suggest First Command
+### Step 5: Suggest a First Task
 
 Based on what the user has:
 
 **Has collections:**
 ```
-Try one of these:
-  /postman:search   — Find APIs across your workspace
-  /postman:test     — Run collection tests
+Try asking me to:
+  - Find APIs across your workspace
+  - Run collection tests
 ```
 
 **Has specs but no collections:**
 ```
-Try this:
-  /postman:sync — Generate a collection from one of your specs
+Try asking me to:
+  - Generate a collection from one of your specs
 ```
 
 **Empty workspace:**
 ```
-Try this:
-  /postman:sync — Import an OpenAPI spec from your project
+Try asking me to:
+  - Import an OpenAPI spec from your project
 ```
 
 ## Error Handling
 
-- **MCP tools not available:** "The Postman MCP Server isn't loaded. Make sure the plugin is installed and restart Claude Code."
+- **MCP tools not available:** "The Postman MCP Server isn't connected in this agent. If the Postman plugin is installed, sign in to its MCP server from the agent's MCP settings; otherwise install the plugin for this agent and restart it. https://github.com/postmanlabs/postman-plugin#install has the install steps for each agent."
 - **OAuth callback invalid:** "That URL doesn't look right — make sure you copied the full address bar URL including `?code=` and `&state=`."
-- **OAuth flow expired:** "The authorization URL has expired. Run `/postman:setup` again to get a fresh one."
-- **MCP server disconnected after OAuth:** The server restarts after saving credentials. Retry `getAuthenticatedUser` up to 3 times. If still unavailable, tell the user to restart Claude Code — the token is saved, no re-auth needed.
+- **OAuth flow expired:** "The authorization URL has expired. I'll generate a fresh one." Then repeat Step 2.
+- **MCP server disconnected after OAuth:** The server restarts after saving credentials. Retry `getAuthenticatedUser` up to 3 times. If still unavailable, tell the user to restart their agent — the token is saved, no re-auth needed.
 - **API key not set:** Walk through Step 3 above.
-- **401 Unauthorized:** "Authentication failed. Try `/postman:setup` to re-authenticate via OAuth, or generate a new API key at https://go.postman.co/settings/me/api-keys"
+- **401 Unauthorized:** "Authentication failed. I can re-authenticate you via OAuth, or you can generate a new API key at https://go.postman.co/settings/me/api-keys." Then offer Step 2 or Step 3.
 - **Network timeout:** "Can't reach the Postman MCP Server. Check your network and https://status.postman.com for outages."
-- **Plan limitations:** "Some features (team workspaces, monitors) require a paid Postman plan. Core commands work on all plans."
+- **Plan limitations:** "Some features (team workspaces, monitors) require a paid Postman plan. Core workflows work on all plans."

package/skills/postman-mcp-server/references/sync.md

@@ -9,7 +9,7 @@ Keep Postman collections in sync with your API code. Create new collections from
 
 ## Prerequisites
 
-The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+The Postman MCP Server must be connected. If MCP tools aren't available, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -77,9 +77,9 @@ Collection synced: "Pet Store API" (15 requests)
 
 ## Error Handling
 
-- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
+- **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
 - **MCP timeout:** Retry once. If `generateCollection` or `syncCollectionWithSpec` times out, the spec may be too large. Suggest breaking it into smaller specs by domain.
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **Invalid spec:** Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues.
 - **Async operation stuck:** If polling shows no progress after 30 seconds, inform the user and suggest checking the Postman app directly.
 - **Plan limitations:** "Workspace creation may be limited on free plans. Using your default workspace instead."

package/skills/postman-mcp-server/references/test.md

@@ -9,7 +9,7 @@ Execute Postman collection tests directly from Claude Code. Analyze results, dia
 
 ## Prerequisites
 
-The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+The Postman MCP Server must be connected. If MCP tools aren't available, follow `references/setup.md` to connect it.
 
 ## Workflow
 
@@ -77,8 +77,8 @@ If the tests themselves need updating (not the API):
 
 ## Error Handling
 
-- **MCP not configured:** "Run `/postman:setup` to configure the Postman MCP Server."
-- **Collection not found:** "No collection matching that name. Run `/postman:search` to find available collections, or `/postman:sync` to create one."
-- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **MCP not configured:** Follow `references/setup.md` to connect the Postman MCP Server.
+- **Collection not found:** "No collection matching that name. I can search your workspaces for it, or create one from a spec." Search with `references/search.md`; create with `references/sync.md`.
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://go.postman.co/settings/me/api-keys." Then re-authenticate with `references/setup.md`.
 - **MCP timeout:** Retry once. For large collections, suggest running a single folder to narrow the test run.
 - **Plan limitations:** "Collection runs may require a Postman Basic plan or higher for increased limits."