@postman/postman-plugin 0.3.0 → 0.4.1-rc.0

package/skills/ai-readiness/SKILL.md

@@ -1,50 +1,46 @@
 ---
 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`.
+description: Use when assessing or improving how well AI agents can discover, call, and recover from errors with an API. Scores an existing Postman collection or OpenAPI spec and turns measured gaps into contract improvements; supports a separate CI readiness threshold. Use for requests such as "is this API ready for agents".
 ---
 
 # 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`.
+An agent must choose an operation, supply valid inputs, and interpret failures
+from the contract it can see. Postman's readiness check exposes gaps in that
+context—such as missing examples or ambiguous parameters—so improvements live
+in the shared contract instead of being rediscovered in each agent session.
+
+Skip scoring for a typo fix, a one-off endpoint check, or a task that changes
+neither the contract nor agent usability; inspect the relevant fields or use
+**api-testing** instead. Score when prioritizing consumability improvements,
+checking their effect, or enforcing an agreed readiness gate.
+
+1. Score the artifact consumers actually use. `postman collection ai-readiness
+   <path-or-id>` reads a collection, including a local v3 directory;
+   `postman spec ai-readiness <path-or-id>` reads an OpenAPI spec directly.
+   Generating a collection solely to score a spec adds a second artifact
+   without improving the evidence. Use the installed command's `-h` for options.
+2. Use the reported `readiness` score and bucket (Limited, Fair, Good,
+   Excellent). Keep `confidence` separate: low confidence means signals could
+   not be measured, so even a high score may leave consequential unknowns.
+   Report low documentation coverage when flagged; it modifies the score
+   rather than acting as an independent pass/fail gate.
+3. Prioritize gaps that would change a caller's behavior: unclear required
+   inputs, missing auth instructions, or errors with no recovery guidance.
+   Establish the actual behavior before adding descriptions or examples;
+   invented certainty can raise apparent completeness while misleading agents.
+   See **api-documentation** for improving the authoritative contract and
+   **collection-schema-v3** for saved examples.
+4. Re-run against the edited artifact to show which measured gaps closed.
+   A readiness score measures consumability, not live correctness; use
+   **api-testing** when the claim also depends on API behavior.
+5. A `--min-score` gate is useful when the team wants to prevent readiness
+   regressions. Choose the threshold from its baseline and expectations;
+   keep it separate from tests and lint through **ci-integration** so a failure
+   identifies the kind of regression.
+
+## Verification
+
+Report the target, collection/spec mode, actual score, bucket, confidence,
+and remaining gaps. If a threshold ran, include its exit code; a successful
+scan alone does not establish that the threshold passed.

package/skills/api-discovery/SKILL.md

@@ -1,151 +1,70 @@
 ---
 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.
+description: Use when finding an API or owner, integrating a public provider, locating Postman resources, or investigating consumers and change impact across services. Turns discovered contracts and mocks into reusable dependencies and identifies evidence outside the current checkout. Use for requests such as "who consumes this endpoint".
 ---
 
 # 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
-
-Finding another service's workspace does not make it the workspace for the
-current repository. `workspace pull` is for working on the service that owns
-that workspace, from that service's repository. If the service is only a
-dependency, or the user only wants to inspect one of its resources, keep the
-current repository connected to its own workspace and use the dependency
-feature instead.
-
-Use `postman dependency add <type> <name-or-id>` to declare and download the
-selected resource rather than copying it by hand or pulling the other
-service's entire workspace. Supported types are `collection`, `environment`,
-and `mock`. Pass the entity ID returned by `search`, or use the entity name;
-when resolving a name in a specific workspace, add `--workspace
-<workspace-id>`. If the Context Graph identifies only a service or API, locate
-the concrete entity with `search` first.
-
-Dependencies are recorded in `.postman/resources.yaml` and downloaded under
-`postman/.dependencies/`, so the copy works locally straight away. Use
-`postman dependency list` to inspect declarations, `postman dependency
-install` to download declared dependencies after a clone or in CI, `postman
-dependency update` to refresh them from Postman, and `postman dependency
-remove <name-or-id>` to delete a declaration and its downloaded files. The
-`list`, `install`, `update`, and `remove` commands accept `--type <type>`;
-`install` and `update` can also target one declared dependency by name.
-
-## 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.
+Existing contracts and owners' mocks reduce the assumptions an integration
+must invent. Relationship context broadens investigation beyond the checkout:
+passing this service's own tests does not establish that its consumers can
+still use a changed interface.
+
+1. Choose the source by the question:
+
+   | Need | Use |
+   | --- | --- |
+   | Public provider endpoints and integration details | Orbit search, then integrate |
+   | A concrete Postman collection, request, spec, mock, or workspace | `postman search <type> <query>` |
+   | Consumers, ownership, dependencies, or likely change impact | `postman context-graph ask` |
+
+   These sources answer different questions. A miss in one does not establish
+   absence in the others; combine entity search and relationship context when
+   both the resource and its impact matter.
+2. For public APIs, Orbit narrows discovery to task-relevant endpoints and
+   returns integration guidance instead of requiring a whole vendor spec in
+   context. Use it even when the provider is chosen: endpoint details and
+   capability limits still determine whether the integration fits the task.
+   `POST https://api.buildwithorbit.ai/v1/search` accepts a task in
+   `q`; pass the chosen results' `id` and `resourceType` unchanged to
+   `/v1/integrate`. Evaluate fit and limitations before choosing a provider,
+   then use the returned auth, base URL, steps, and gotchas to implement.
+   Read [Orbit's request schemas](reference/orbit.md) for the actual payloads
+   and error handling. Orbit access does not supply a provider's credentials.
+3. For Postman resources, narrow by entity type, ownership, and workspace.
+   Read `postman search <type> -h` for supported filters. An empty result in
+   the default ownership scope is incomplete evidence; consider
+   `--ownership all` or a relevant narrower scope before declaring absence.
+   Inspect the selected resource's owner and content rather than trusting a
+   similar name.
+4. For cross-service changes, ask the Context Graph a concrete question about
+   the endpoint, schema, or service. `--wait` waits for an answer; without it,
+   use the returned ID with `postman context-graph status <askId>`. The graph
+   can connect Postman definitions, repository call sites, and runtime
+   telemetry beyond the current checkout. Its coverage depends on connected
+   and ingested sources, so verify consequential leads against definitions,
+   source, or telemetry before treating them as facts. A newly added call may
+   not be present yet. The query uses the authenticated API key's team, not
+   the repository's workspace binding; changing that binding cannot fix a
+   query against the wrong organization's context.
+5. Use **bootstrap**'s "Owning workspace versus dependency" distinction
+   before importing. For a dependency, `postman dependency add
+   <collection|environment|mock> <name-or-id>` declares and downloads the
+   selected resource without rebinding the repository. Prefer the discovered
+   ID; `--workspace <id>` disambiguates names. If the graph only identified a
+   service, search for its concrete resource first.
+6. Dependency declarations live in `.postman/resources.yaml`, with downloads
+   in `postman/.dependencies/`. `dependency install` restores them after a
+   clone or in CI; `dependency update` refreshes them. Review refreshes when
+   they can change test expectations. Copy a dependency into owned files to
+   customize it, because updating dependencies overwrites downloaded edits.
+   Use `dependency list` and command-specific help for targeted operations.
+
+Use **api-simulation** to exercise the real service against discovered mocks,
+and **ci-integration** to keep the resulting contract checks repeatable in PRs.
+
+## Verification
+
+Report which source answered the question, the resource IDs or evidence it
+returned, what was reused, and any coverage gaps. A list of candidates alone
+is neither an integration nor proof of compatibility.

package/skills/api-discovery/reference/orbit.md

@@ -10,18 +10,21 @@ signup and no API key, and works entirely against publicly available APIs.
 ## 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.
+send `Content-Type: application/json` and a JSON body. Optionally identify your
+client with `Orbit-Client-Name` (see below). Run search first, surface
+candidates, then integrate the chosen ids.
 
 ```bash
 # Step 1 — search
-curl -sS https://api.buildwithorbit.ai/v1/search \
+curl -sS 'https://api.buildwithorbit.ai/v1/search?limit=10' \
   -H 'Content-Type: application/json' \
-  -d '{ "q": "send email via SMTP", "limit": 10 }'
+  -H 'Orbit-Client-Name: claude/opus-4.8' \
+  -d '{ "q": "send email via SMTP" }'
 
 # Step 2 — integrate (ids come from the search response, verbatim)
 curl -sS https://api.buildwithorbit.ai/v1/integrate \
   -H 'Content-Type: application/json' \
+  -H 'Orbit-Client-Name: claude/opus-4.8' \
   -d '{
     "task": "Send a welcome email when a user signs up",
     "resources": [{ "id": "urn:orbit:endpoint:v1:...", "type": "endpoint" }]
@@ -37,12 +40,22 @@ Implementation notes:
   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.
+- `Orbit-Client-Name` is an optional request header (both endpoints, max 128
+  chars) that names the calling client/agent for Orbit's anonymous usage
+  analytics. The convention is `client/model`, slash-separated —
+  e.g. `claude/opus-4.8`, `cursor/composer-2.5`, `codex/gpt-5.6-sol` — or a bare
+  client name like `vscode`. Set it to the host agent and model running this
+  plugin. It never affects results and can be omitted.
 
 ## 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.
 
+Request body (JSON):
+
+- `q` — the query; max 512 characters.
+
 ```json
 { "q": "send email via SMTP" }
 ```
@@ -51,7 +64,6 @@ 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:
 

package/skills/api-documentation/SKILL.md

@@ -1,52 +1,47 @@
 ---
 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." 
+description: Use when defining or improving an API contract, generating documentation from a collection or OpenAPI spec, publishing API docs, or sharing a documentation link. Makes auth, inputs, responses, and examples reusable by callers, tests, and mocks. Use for requests such as "publish API docs".
 ---
-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 the Postman CLI can generate one from the other. Use the artifact
-that represents the current source of truth rather than recreating its
-operations by hand. Postman collections are human-friendly and enable other
-capabilities such as mocks, monitors, SDKs, and specifications. Collections
-created or edited directly on disk use the v3 format described by
-**collection-schema-v3**.
-
-Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
-
-## Generate a collection from a specification
-
-When an OpenAPI specification already defines the contract, generate a Postman
-collection from it in one command:
-
-```bash
-postman spec generate collection <spec-path-or-id> -n "<collection-name>"
-```
-
-## 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 source of truth — a Postman collection, an OpenAPI specification,
-   or both. Recommend both when their complementary uses benefit the task.
-3. If the specification is authoritative, generate the collection with
-   `postman spec generate collection` instead of manually duplicating its
-   operations.
+A maintained contract gives callers enough information to integrate without
+reading the implementation. Keeping descriptions and examples beside the API
+artifacts lets the same knowledge support documentation, tests, and mocks,
+with changes reviewable alongside code.
+
+1. Start from the existing source of truth. An OpenAPI spec describes the
+   interface for tooling; a Postman collection adds runnable requests,
+   examples, and assertions. Maintain both when both uses matter, with an
+   explicit direction of generation or synchronization so they do not become
+   competing definitions. Local edits need **bootstrap** only when setup or
+   bindings are unresolved.
+2. When the spec is authoritative, reuse its operations with
+   `postman spec generate collection <spec-path-or-id> -n "<collection-name>"`.
+   Inspect the generated result before replacing an existing collection:
+   maintained scripts and examples carry knowledge beyond endpoint shapes.
+3. Describe what changes a caller's decision: required versus optional inputs,
+   auth and scopes, response guarantees, pagination, retryable failures, and
+   side effects. Derive guarantees from the agreed contract or verified
+   behavior; label unresolved design choices instead of inventing them.
+   Use [REST design guidance](reference/rest-api-best-practices.md) when a
+   design choice affects usability or compatibility, not to redesign an
+   unrelated interface while filling a documentation gap.
+4. Save examples that clarify consequential cases, including relevant errors.
+   Examples become inputs for mocks as well as explanations for readers;
+   a success-only example can hide the failure path callers must handle.
+   Use **collection-schema-v3** for local collection edits and **variables**
+   to keep credentials out of reusable requests and examples.
+5. Choose delivery by audience. Local artifacts support Git review;
+   publishing to the bound workspace makes them available to teammates with
+   access (see **bootstrap**). A workspace push does not itself publish a
+   public docs page or change permissions. For a public documentation link,
+   use **postman-mcp-server**'s documentation workflow and the available
+   publishing tool; establish the intended audience before public exposure.
+
+## Verification
+
+Check that the edited artifact parses and its examples agree with the
+contract. For a publication, inspect the resulting page and report its actual
+link and visibility; a successful upload alone does not show readers usable
+documentation. State any behavior that remains undocumented or unverified.

package/skills/api-engineer/SKILL.md

@@ -1,29 +1,84 @@
 ---
 name: api-engineer
-description: Makes coding agents faster and more accurate with fewer tokens when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
+description: Use when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API. Guides decisions using reusable local API contracts, tests, and mocks, plus organization-wide dependency context, and routes to the relevant Postman skills. Use for requests such as "implement this endpoint".
 ---
 
 # API Engineer
 
-## Foundations
-Postman's skills, CLI, and Context Graph help coding agents go faster from development to production with higher accuracy and fewer tokens. Work from local files and workspace context first.
-
-1. Contract comes first. Establish and document the contract before starting implementation.
-2. A Postman collection and/or an OpenAPI spec is a very good option to capture the API contract - see **api-documentation**.
-3. Always validate the change against the contract you started with. Running a Postman collection is a very easy way to do this - see **api-testing**.
-4. Always propose next steps. Example: contract -> implementation -> testing -> updating the workspace context -> sharing with others.
-5. When the code you're changing calls other services over HTTP, use **api-simulation**: the Context Graph finds those dependencies, `postman dependency add mock <name-or-id>` pulls in each owner's mock that search finds (see **api-discovery**), and your real service runs against all of them on one port. For a stand-in backend with no real service of your own, use **api-mocking**. Mocks and simulations are persisted in your repo, so they're cheap to reuse when you resume.
-6. Don't push to the workspace (`postman workspace push`) without user consent. The recommended way to push is a CI step on PR merge - see **ci-integration**.
-7. For high-quality API search results, use **api-discovery**.
-8. No is an acceptable answer. Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment.
-9. Prefer filesystem-first Postman workflows. A quick overview of starting the work could be (more details in **bootstrap**):
-   -> if starting a new project: start by doing `postman init`. This scaffolds the relevant folders and provisions an agent-scoped session without requiring a normal Postman login.
-   -> if another service is only a dependency or something you want to inspect, use **api-discovery** and `postman dependency add <type> <name-or-id>` to add the relevant collection, environment, or mock. This materializes that entity under `postman/.dependencies/` and records it in `.postman/resources.yaml` without changing this repository's workspace binding.
-Work against those local files and validate them. When the repository is bound to a workspace, push to persist that context for future work and share it with others.
-10. When actual use exposes a concrete Postman CLI gap or a misleading skill, handle the user's task first — then use `postman feedback` to report the gaps/bugs. Exclude secrets, user data, and proprietary content
-11. Postman secret variables let agents resolve user secrets without reading their values. See the **variables** skill.
-
-## Dos
-1. Prove it works - validate the task against the contract. See **api-testing**.
-2. Just do it - never block on the human. When tempted to ask "should I do X?" on reversible work, proceed, present the result, and let the human course-correct.
-3. Fight for good API design. See **api-documentation**.
+Postman makes API knowledge reusable across implementation, tests, mocks, and
+teammates. Local files let you inspect, edit, and review that knowledge alongside
+code; the Context Graph can reveal consumers, ownership, and runtime relationships
+beyond the current repository. Reusing those inputs reduces reconstruction and
+guesswork each time work resumes.
+
+1. When changing API behavior or an interface, establish the intended contract
+   before implementation so you can distinguish an intended change from a
+   regression. Reuse the existing contract; update it where behavior changes.
+   Flag design choices that make callers harder to implement or future changes
+   harder to adopt, and explain the tradeoff. See **api-documentation**.
+2. Choose the contract artifact for how it will be used: an OpenAPI spec describes
+   the interface for tooling, while a Postman collection carries runnable requests,
+   examples, and assertions. Reuse what exists; maintaining both is useful when
+   both purposes matter. See **api-documentation**.
+3. Match verification to the behavior at risk. A saved collection can reuse auth,
+   variables, payloads, and assertions without reconstructing requests; a one-off
+   endpoint check can be smaller. Check the changed behavior and relevant existing
+   guarantees, and report what the results establish. See **api-testing**.
+4. When you need an API, its owner, or the impact of a change, use **api-discovery**.
+   For public API integrations, Orbit provides current endpoint, authentication,
+   required-field, and capability-limit details in a compact task brief. Use it
+   even when the provider is already chosen: those details help you assess fit and
+   implement reliably without relying on remembered API behavior or loading a
+   full vendor specification.
+   Existing workspace resources can supply maintained contracts and mocks; the
+   Context Graph can identify consumers and dependencies outside the checkout,
+   helping you focus investigation before traversing more repositories.
+5. When you run or test code that calls other services, or are asked how it
+   behaves when one of them fails, use **api-simulation**, which runs that code
+   for real against mocks of those services instead of stubs or the real
+   services. Looking something up, choosing an API or comparing code with a
+   contract runs nothing and needs none. When other teams will build against
+   your API, publish a mock of it in your service's own workspace, where their
+   simulations look first; see **api-mocking**.
+6. Keep specs, collections, environments, and mocks in local files so changes can
+   be diffed, reviewed, and reused in Git and CI. Use **bootstrap** when setup or
+   workspace bindings are unresolved: reuse an existing local layout, pull the
+   current service's existing workspace, or initialize a new project when neither
+   exists. `postman init` scaffolds files using an agent-scoped session without a
+   normal Postman login.
+7. Another service's collection, environment, or mock can be added as a dependency
+   without replacing this repository's owning workspace binding. Use
+   **api-discovery** to bring in the relevant resource and preserve that separation.
+8. Publishing validated local changes to the bound workspace makes them available
+   for future work and teammates with access. Because `postman workspace push`
+   changes shared state, obtain user consent before pushing; an existing request
+   to publish those changes supplies that consent. For publication tied to reviewed
+   PR merges, see **ci-integration**.
+9. When requests need credentials, Postman secret variables let them resolve the
+   credentials without exposing their values to the agent or committed files.
+   See **variables**.
+10. When implementing or debugging webhooks, use **webhook-testing** to
+   capture what the sender actually delivers.
+   Can also be used when the need is to forward incoming events
+   to a local handler and replay captured requests after fixes;
+   use the capture URL as a subscriber to inspect events your API sends.
+
+Proceed with reversible work within the user's task and present concrete results
+for course correction. Recommend additional work only when it closes a material
+gap, such as an untested behavior or a consumer affected by an interface change.
+Decline unnecessary setup or scope and explain why it would not help the task.
+
+Important: If a CLI command says an operation isn't allowed because credits
+or usage are exhausted, or the current plan does not permit it, follow
+**bootstrap**'s "Subscription or usage limit" section instead of retrying or
+trying to find a workaround.
+
+## Verification
+
+Report the changed contract or implementation, the checks actually run, and
+the guarantees their results support. Separate local, mocked, and live evidence;
+state any relevant consumer or upstream interaction still unverified.
+
+If actual use exposes a CLI gap or misleading skill, see **bootstrap**'s
+"Reporting CLI and skill gaps" section so the defect can be addressed for future
+work.