Update to Postman

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,29 +1,84 @@
 ---
 name: api-engineer
-description: Default entry point for API engineering work — 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
-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 -> pushing to cloud -> sharing with others.
-5. Don't jump straight into implementation. Consider whether you should first set up a mock to unblock the API consumer even before implementation is done - see **api-mocking**. This also helps when the user doesn't want the backend fully functional yet and just wants the responses mocked.
-6. Don't push to the cloud workspace (`postman workspace push`) without user consent. The recommended way to push to the cloud 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. For an existing cloud workspace,
-   `postman workspace pull <id>` connects it and materializes its collections,
-   environments, and specs locally. When no cloud workspace exists, `postman
-   init --no-cloud` initializes the local structure. Work against those files,
-   validate them, and push only with user consent; sharing an already-bound
-   workspace means `workspace push`, not creating a duplicate. See
-   **bootstrap** for the lifecycle decision table.
-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
-
-## 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.