@postman/postman-plugin 0.5.1 → 0.6.0

package/README.md

@@ -235,8 +235,8 @@ exercise failure paths.
 `postman init` is idempotent and safe to run in any project. Run it before API
 engineering work to create the relevant local directories and make Postman
 skills available to guide the task, even if the project is already initialized.
-See [bootstrap](https://github.com/postmanlabs/postman-plugin/blob/main/skills/bootstrap/SKILL.md#start-with-postman-init) for setup
-options and workspace binding.
+See [workspaces](https://github.com/postmanlabs/postman-plugin/blob/main/skills/workspaces/SKILL.md) for init's
+workspace options and binding.
 
 Work done in a Postman folder produces artifacts: collection runs, lint
 results, request history, mock deployments. When that folder is connected to a

package/hooks/session-start-context.md

@@ -3,7 +3,7 @@ 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`, `postman:variables` (where a value or secret belongs and how to reference it).
+When the intent is already specific, you may enter directly into the relevant skill instead: `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`, `postman:variables` (where a value or secret belongs and how to reference it).
 
 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.
 

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.5.1",
-        "User-Agent": "postman-pi-plugin/0.5.1"
+        "X-Plugin-Version": "0.6.0",
+        "User-Agent": "postman-pi-plugin/0.6.0"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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/api-discovery/SKILL.md

@@ -10,6 +10,11 @@ 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.
 
+Postman search, the Context Graph and dependency downloads work only for a
+signed-in CLI. Check `postman status` before the first of them and sign in if
+it reports signed out. If signing in isn't possible, don't run them; say which
+sources were skipped.
+
 1. Choose the source by the question:
 
    | Need | Use |
@@ -47,8 +52,8 @@ still use a changed interface.
    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
+5. Before importing, tell this repository's owning workspace from a
+   dependency. 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

package/skills/api-documentation/SKILL.md

@@ -14,8 +14,7 @@ with changes reviewable alongside code.
    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.
+   competing definitions.
 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:
@@ -34,7 +33,7 @@ with changes reviewable alongside code.
    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
+   access. 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.

package/skills/api-engineer/SKILL.md

@@ -16,10 +16,9 @@ guesswork each time work resumes.
    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**.
+2. A Postman collection records the contract in a form that runs. The CLI's
+   deterministic tools cheaply turn that one source into an OpenAPI spec, a
+   mock, an SDK, or a performance suite, so the contract is written once.
 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
@@ -40,10 +39,8 @@ guesswork each time work resumes.
    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.
+   be diffed, reviewed, and reused in Git and CI. `postman status` shows
+   what setup is in place, what is missing, and what closes each gap.
 7. `postman init` gives API engineering work a ready state. It scaffolds local structure: `postman/`
    directories for API artifacts. It installs skills in `postman/skills` folder with guidance on  designing, implementing, and validating APIs.
    The command is idempotent and safe to rerun in an initialized project.
@@ -73,16 +70,17 @@ 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.
+or usage are exhausted, or the current plan does not permit it, stop
+retrying and tell the user that signing up or upgrading their plan is what
+lifts it.
 
 ## 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.
+state any relevant consumer or upstream interaction still unverified. Run
+`postman status` last to confirm the setup the work relied on is still in place.
 
-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.
+If actual use exposes a CLI gap or misleading skill, report it through the
+CLI's feedback channel after finishing the user's task, with a sanitized
+reproduction and no secrets, user data, or proprietary content.

package/skills/api-mocking/SKILL.md

@@ -21,8 +21,10 @@ Several APIs at once, for a service, a frontend or a test suite? Use
 
 When the API belongs to another team, look for their published mock before
 writing one: theirs encodes their contract and their service's state; yours
-encodes a guess. It needs `postman login`; signed out, build one and say the
-owner search was skipped.
+encodes a guess.
+
+Every step below needs a signed-in CLI. Check `postman status` first; signed
+out, skip to building one and say the owner search was skipped.
 
 1. Find the owner's workspace with `postman search workspaces "<service>" -o json`.
    Name the service plainly, as your code does, not by what it returns: a

package/skills/api-monitoring/SKILL.md

@@ -19,43 +19,53 @@ exercise the guarantees users depend on.
    the linked workspace unless one is supplied. Inspect command-specific
    `-h` and available service options for supported schedules and limits.
    Creation starts an immediate run by default; `--no-run-now` avoids that
-   when only scheduling was requested. A schedule expressed in the host's
-   default timezone can fire at the wrong operational time.
+   when only scheduling was requested. Pass `--timezone` with the zone the
+   user means (for example `America/New_York`); without it the schedule uses
+   the zone of the machine running the CLI. Leave the month field as `*`; to
+   limit a schedule to certain months, write them as three-letter names such
+   as `jan`, not numbers.
 3. Choose a Postman region for a reachable public API. Use a self-hosted
    runner when the target is reachable only inside the user's network;
    running one adds infrastructure to maintain. `postman runner regions`
-   provides valid hosted locations and `runner list` provides registered
-   private runner IDs. `monitor create/update --runner` accepts either;
+   provides valid hosted locations and `runner list --json` the full IDs of
+   registered private runners. `monitor create/update --runner` accepts either;
    multiple locations help distinguish API failures from regional reachability.
-4. Preserve monitor identity when updating schedule or run settings.
-   `monitor update` cannot change its collection or environment and does not
-   pause it; use `pause`/`resume` for that. A different collection/environment
-   requires a replacement, so plan the handoff before deleting the old
-   monitor and its continuity. Permanent deletion needs explicit intent.
+4. Update a monitor in place to keep its run history.
+   `monitor update` cannot change the collection, and cannot pause or resume
+   the monitor: use `monitor pause`/`monitor resume` for that. `update -e`
+   swaps the environment and `--clear-environment` removes it. A different
+   collection requires a replacement, so plan the handoff before deleting the
+   old monitor and its continuity. Permanent deletion needs explicit intent.
 5. Use `postman monitor run <id>` for an immediate verdict, such as after a
    deploy. `--async` returns a job handle when the caller need not wait.
-   The CLI timeout caps waiting, not execution; after a timeout, inspect
-   the submitted job instead of sending duplicate traffic or reporting failure.
-6. Diagnose at the level of the evidence. `monitor jobs list <monitor-id>`
-   finds jobs, `monitor jobs get <job-id>` shows terminal state and regional
-   outcomes, and `monitor runs get <run-id>` shows assertions within an
-   attempt. A failing region, a connection error, and a failed assertion
-   imply different fixes. Preserve normal exit-code failures for CI gates.
+   The CLI timeout caps waiting, not execution: after a timeout, read the job
+   with `monitor jobs get <job-id>`; its state is the verdict.
+6. Answer each failure question at its level. `monitor jobs list
+   <monitor-id>` finds jobs, `monitor jobs get <job-id>` shows terminal state
+   and regional outcomes, and `monitor runs get <run-id>` shows assertions
+   within an attempt. A failing region, a connection error, and a failed
+   assertion imply different fixes. For a trend across runs, such as which
+   request got slow, use `monitor metrics <monitor-id>`. In a CI gate, run
+   `monitor run` without `-x`, so a failed run fails the build.
 
-For discovery, `monitor list` supports workspace and collection filters;
-use its returned cursor for pagination rather than offset. Its runner filter
+For discovery, `monitor list` supports workspace and collection filters; to
+page it, pass `--cursor` with the value from the previous page. Its runner filter
 is for a self-hosted ID and cannot be combined with other filters; a page-local
 name filter does not establish absence across all pages.
 
-For a private runner, use `runner start` with the registered ID and key and
-verify that it connects before assigning runs. Inspect its help for proxy,
-private CA, residency, and health-metric options only when the network requires
-them. Runner activity is reported by default; `--no-report-events` disables
-that reporting when the task requires it. Use **bootstrap** for unresolved
-authentication rather than placing runner keys in repository files.
+For a private runner, use `runner start` with the ID and key from the runner
+created in Postman, and verify it is reporting in before assigning runs: a
+recent `Last ping` in `runner list` (`lastPingAt` under `--json`; `never`
+means it has not connected). Inspect its help for proxy, private CA,
+residency, and health-metric options only when the network requires them.
+Runner activity is reported by default; `--no-report-events` disables that
+reporting when the task requires it. Pass the runner key at runtime, from the
+user or a secret store (for example `--key "$RUNNER_KEY"`), and keep it out of
+files in the repository. If a `monitor` or `runner list` command fails on
+authentication, sign in.
 
 ## Verification
 
 Report the actual monitor configuration or terminal job/run outcome, including
 where it executed and which checks failed. A created monitor, accepted job,
-or connected runner alone does not prove the API passed its health checks.
+or a runner reporting in alone does not prove the API passed its health checks.

package/skills/api-simulation/SKILL.md

@@ -56,7 +56,9 @@ CLI answers `postman simulation -h` with its general help).
   shared code; ask about the repo by its `git remote` name, because a close
   name matches another repo.
 - **Each member needs a mock: see `api-mocking`,** which looks for the owning
-  team's published mock before building one. For a question, one built from
+  team's published mock before building one. Finding and pulling an owner's
+  mock needs a signed-in CLI; check `postman status` first, and signed out,
+  build each mock and record that the owner search was skipped. For a question, one built from
   the contract will do; one that invents responses can send the caller down a
   path the real service never would. In a mock you build, answer `501` for calls this path
   doesn't make: a `404` reads to the caller like a real "not found".

package/skills/api-testing/SKILL.md

@@ -45,9 +45,9 @@ guarantee; a successful HTTP exchange alone does not establish correctness.
    without validating it. Results are recorded in the connected workspace by
    default; `--report-events=false` keeps the run local when required.
 
-Use command-specific `-h` for supported options and **bootstrap** for unresolved
-CLI setup or authentication when using workspace resources. A bare URL or
-local collection does not require a workspace binding.
+Use command-specific `-h` for supported options. Workspace resources need a
+signed-in CLI; a bare URL or local collection does not require a workspace
+binding.
 
 ## Verification
 

package/skills/application-testing/SKILL.md

@@ -44,7 +44,7 @@ If this run does not need to publish results (local debugging, dry run), authent
 
 Publishing to Application Inventory requires a workspace binding. Check `.postman/resources.yaml` for a `workspace.id`. Reason about whether publishing is actually needed for this task before treating a missing workspace as a blocker:
 
-- If publishing is needed and the workspace is missing, load the `bootstrap` skill to set it up. In a non-interactive context this must be done locally first, then `.postman/resources.yaml` committed.
+- If publishing is needed and the workspace is missing, load the `workspaces` skill to set it up. In a non-interactive context this must be done locally first, then `.postman/resources.yaml` committed.
 - If publishing is not needed, pass `--report-events false` and proceed.
 
 ### Capture plugin
@@ -106,7 +106,7 @@ A **target** is a named set of collections + optional environment. The `default`
 ```bash
 postman --version
 ```
-This skill targets the latest CLI release. If the version is outdated, load the `bootstrap` skill for installation and update steps, then re-run. The `--help` output for each command shows the flags actually available in the installed version.
+This skill targets the latest CLI release. If the version is outdated, update the CLI, then re-run. The `--help` output for each command shows the flags actually available in the installed version.
 
 Read the CLI error output first — it names the specific failure and what to fix.
 

package/skills/ci-integration/SKILL.md

@@ -38,10 +38,12 @@ the author's own passing tests do not establish cross-service compatibility.
    not make the command read-only.
 4. Authenticate only jobs that need workspace resources. Use the CI secret
    store to supply `POSTMAN_API_KEY`, then
-   `postman login --with-api-key "$POSTMAN_API_KEY"`. A local-only gate need
-   not log in. Command-specific API-key flags are not a general replacement
-   for login across lint and push operations. Use **bootstrap** for unresolved
-   bindings, and **variables** for request credentials.
+   `postman login --with-api-key "$POSTMAN_API_KEY"`. A local-only gate can
+   run without it, but its run results are then lost: they stay in that job's
+   log instead of reaching the workspace, where teammates and later agent
+   sessions read them as evidence. Command-specific API-key flags are not a general replacement
+   for login across lint and push operations. Use **workspaces** for
+   unresolved bindings, and **variables** for request credentials.
 5. Publish only the reviewed branch after its merge checks pass.
    `postman workspace push -y` changes shared context; a PR-triggered push
    would publish an unmerged contract. The normal prepare phase assigns IDs
@@ -51,7 +53,7 @@ the author's own passing tests do not establish cross-service compatibility.
 6. Use the default create/update strategy unless exact mirroring is the
    explicit requirement. `--push-strategy force-sync` can delete workspace
    entities absent from the checkout, including resources managed elsewhere.
-   Follow **bootstrap**'s diff and consent boundary for that branch.
+   Preview that push's diff and get its deletions approved before enabling it.
 
 ## Verification
 

package/skills/cli-install/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: cli-install
+description: Use when the Postman CLI is missing or can't be installed, or when `postman` is "command not found". Installs the CLI globally so `postman` is on `PATH`, with a fallback to the hosted MCP server when installing is blocked. Use for requests such as "install the Postman CLI".
+---
+
+# Install the Postman CLI
+
+Install it globally so `postman` is on `PATH`. If installing is blocked, use
+**postman-mcp-server** for hosted operations.
+
+```bash
+# npm, any platform with Node
+npm install -g postman-cli
+
+# macOS, Linux, and WSL
+curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
+```
+
+```powershell
+# Windows
+powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"
+```
+
+## Verification
+
+Report the installed version and the route it came from, and confirm `postman`
+on `PATH` resolves to that copy.
+
+Source: https://learning.postman.com/docs/postman-cli/postman-cli-installation/

package/skills/collection-schema-v3/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: collection-schema-v3
-description: Use when writing or debugging local Postman v3 collection and environment YAML, including collection lint failures. Preserves the per-entity files, inherited context, and schema shapes that make API changes reusable and reviewable in Git. Use for requests such as "fix this request YAML".
+description: Use when writing or debugging local Postman v3 collection, environment or globals files, including collection lint failures. Preserves the per-entity files, inherited context, and schema shapes that make API changes reusable and reviewable in Git. Use for requests such as "fix this request YAML".
 ---
 
 # Collection Schema (v3, Git-Native)
@@ -19,12 +19,14 @@ checks, without regenerating a single large collection export.
    Collection/folder definitions supply shared context; copying every inherited
    field into each request creates competing values and noisy future edits.
    See **variables** when deciding the scope of a value or secret reference.
-3. Use [HTTP field shapes and examples](reference/http.md) when authoring
-   request, example, or definition files. For other protocols, read
-   [their schemas](reference/other_protocols.md); HTTP's URL/body/script shape
-   cannot be assumed for gRPC, WebSocket, MCP, or LLM requests.
-   [Environment files](reference/environment.md) have their own schema and
-   do not use the collection entity's `$kind` discriminator.
+3. Consult the reference section for the entity being changed:
+   [HTTP requests, examples, and definitions](reference/http.md),
+   [environment files](reference/environment.md), or
+   [other protocols](reference/other_protocols.md).
+   Protocols have different URL, body, script, and settings shapes; an HTTP
+   field is not necessarily valid on another request kind.
+   For globals files, use the [globals reference](reference/globals.md).
+   Dataset YAML belongs to **datasets**; mocks belong to **api-mocking**.
 4. Preserve types at the YAML boundary. Quote `{{variables}}` and strings that
    resemble booleans or numbers; JSON bodies are string content, best expressed
    with block scalars. A syntactically valid YAML object can still be the wrong
@@ -43,7 +45,15 @@ checks, without regenerating a single large collection export.
 ## Verification
 
 Run `postman collection lint <collection-path>` for collection changes and
-`postman environment lint <path>` for environment changes. Then inspect the
-diff for unintended scope changes; when execution is appropriate, run the
-changed request through its collection to check inherited context. Report
-structural validation separately from behavior verified against a target.
+`postman environment lint <path>` for environment changes. Review warnings as
+well as errors: an ignored field can change behavior even when parsing succeeds.
+Use `postman workspace lint` when checking relationships across entities or
+workspace manifest mappings.
+
+Inspect the diff for unintended scope changes. When execution is appropriate,
+run the changed request through its collection to check inherited context.
+For script changes, check that the changed script executed and produced its
+intended effect; compare assertion counts with the assertions expected for that
+run. A setup script may intentionally have none, and unrelated passing assertions
+do not prove the changed script worked. Report structural validation separately
+from behavior verified against a target.

package/skills/collection-schema-v3/reference/environment.md

@@ -36,6 +36,8 @@ An environment is one YAML file named `<name>.environment.yaml` under
   - `enabled` — boolean. The CLI writes `true` for a newly set variable.
   - `type` — optional string. Use `default` for ordinary values and `secret`
     for sensitive values.
+  - `secret` — optional boolean; `secret: true` alongside `type: default` is
+    also a recognised way to mark a secret.
   - `description` — optional string.
 
 Do not add collection-only fields such as `$kind`, `scripts`, `auth`, or

package/skills/collection-schema-v3/reference/globals.md

@@ -0,0 +1,40 @@
+# Globals
+
+A globals file is named `<name>.globals.yaml` under `postman/globals/`.
+It has no `$kind` discriminator.
+
+## Fields
+
+- `name` — required string, conventionally `Globals`.
+- `values` — required array; `values: []` represents no globals.
+- Each value has:
+  - `key` — required variable name.
+  - `value` — required string. Quote numeric- or boolean-looking strings
+    and `{{variables}}` so YAML preserves their type.
+  - `enabled` — boolean.
+  - `type` — optional string: `default` or `secret`.
+  - `secret` — optional boolean; `secret: true` alongside `type: default`
+    also marks a secret.
+  - `description` — optional string.
+
+## Example
+
+```yaml
+name: Globals
+values:
+  - key: base_url
+    value: 'https://api.example.com'
+    enabled: true
+    type: default
+  - key: api_token
+    value: ''
+    enabled: false
+    type: secret
+```
+
+Marking a value as secret does not make a literal credential safe to commit.
+Keep reusable examples free of credentials; see **variables** for secret sources.
+
+Validate with `postman globals lint <file>`. This checks structure, not whether
+requests resolve the intended values; check scope and overrides when diagnosing
+unexpected runtime values.

package/skills/collection-schema-v3/reference/http.md

@@ -13,7 +13,7 @@ Optional metadata for a collection or folder:
 - `description` — optional.
 - `variables` — array of `{key, value, description?, disabled?}`. `value`
   must be a string; `disabled` a boolean.
-- `auth` — a single auth object `{type, credentials: [{key, value}, ...]}`,
+- `auth` — a single auth object `{type, credentials: [{key, value}, ...]}`
   or an array for multiAuth: `[{id, name, type, credentials, rules?}, ...]`.
 - `scripts` — array of `{type, code, language: "text/javascript"}`. `type`
   is one of `http:beforeRequest`, `http:afterResponse`,
@@ -47,17 +47,59 @@ Optional metadata for a collection or folder:
 - `examples` — optional, a relative path to the examples directory, e.g.
   `./.resources/<request-name>.resources/examples/`.
 
+When editing query parameters, update both places they are recorded: the
+query string in `url` and the entries in `queryParams`. Their names and values
+must match; lint reports a mismatch as `FMT209`. For example, `q=shoes&page=2`
+is represented as:
+
+```yaml
+url: '{{base_url}}/search?q=shoes&page=2'
+queryParams:
+  - key: q
+    value: shoes
+  - key: page
+    value: '2'
+```
+
 ## HTTP example (`*.example.yaml`)
 
-- `$kind: "http-example"` — required.
-- `name` — optional.
-- `request: {url, method}`.
-- `response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}`.
-- `order` — optional.
+`http-example` requires `$kind` and `response`, and `response` requires `body`:
+
+```yaml
+$kind: http-example
+name: 200 OK
+request:
+  method: POST
+  url: https://api.example.com/orders
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    content: '{"sku":"A1"}'
+response:
+  statusCode: 200
+  statusText: OK
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    content: '{"id":"o_1"}'
+order: 1000
+```
+
+For a saved `204 No Content` example, the YAML schema still requires a
+`response.body` object. Represent the absence of response content with
+`body: {type: text, content: ''}`. This describes the saved example file;
+it does not add content to the HTTP response.
 
-Saved examples are what `collection ai-readiness` checks for — a request
-with no examples scores worse for agent consumption even if perfectly
-valid structurally.
+Response `body.type` accepts only `text`, `json`, `xml`, `html`, `javascript`
+and `yaml`. For a form-encoded response, use `type: text` with a
+matching `Content-Type` header. Request bodies do have `urlencoded`.
+
+Saved examples feed **ai-readiness**, documentation, and mocks; a structurally
+valid example still needs to agree with the contract.
 
 ## Environments (`postman/environments/*.environment.yaml`)
 
@@ -66,10 +108,106 @@ Environment files are v3 YAML but are not collection entities: they do not use
 [reference/environment.md](environment.md) for the schema, secret
 handling, CLI-first edit commands, and a linted example.
 
+## Auth
+
+`auth` is available on a collection, a folder, a request and an example. It has two
+shapes. No auth:
+
+```yaml
+auth:
+  type: noauth
+```
+
+Anything else takes `type` plus `credentials`:
+
+```yaml
+auth:
+  type: bearer
+  credentials:
+    - key: token
+      value: '{{TOKEN}}'
+```
+
+`type` is one of `basic`, `bearer`, `apikey`, `digest`, `oauth1`, `oauth2`, `jwt`,
+`awsv4`, `hawk`, `ntlm`, `asap`, `edgegrid`, `azure`, `sasl`, `inherit`. Use `inherit`
+to take the parent folder's or collection's auth explicitly; omitting `auth` entirely
+does the same thing.
+
+`credentials` keys are the same names the Postman app shows for that auth type —
+`username`/`password` for `basic`, `token` for `bearer`, `key`/`value`/`in` for
+`apikey`, `accessKey`/`secretKey`/`region`/`service` for `awsv4`. A structurally
+valid credential entry does not establish that the server will authenticate it.
+`credentials` is an array of `{key, value}` entries.
+
+## Request body
+
+`body` is one shape chosen by `type` — write that branch's keys and nothing else.
+
+```yaml
+body: {type: none}
+```
+```yaml
+body:
+  type: json          # or text, xml, html, javascript
+  content: |-
+    {"id": 1}
+```
+```yaml
+body:
+  type: urlencoded
+  content:
+    - key: grant_type
+      value: client_credentials
+```
+```yaml
+body:
+  type: formdata
+  content:
+    - key: file
+      type: file
+      src: ./payload.bin
+    - key: note
+      type: text
+      value: hello
+      contentType: text/plain
+```
+```yaml
+body:
+  type: file
+  content:
+    src: ./upload.bin       # an object with src, not a bare path
+```
+
+Choose `body.type` to match the payload and contract. JSON `content` is a string;
+a block scalar keeps it readable without turning it into a YAML object.
+A *response* body inside an example has a narrower type list:
+see [HTTP examples](#http-example-exampleyaml).
+
+## Scripts
+
+```yaml
+scripts:
+  - type: afterResponse
+    code: |-
+      pm.test('ok', () => pm.response.to.have.status(200));
+```
+
+`type` is `beforeRequest` or `afterResponse` on a request, and protocol-prefixed on a
+collection or folder (`http:beforeRequest`, `http:afterResponse`,
+`graphql:beforeQuery`, `grpc:beforeInvoke`, …). A script entry may also carry
+`language`, `packages`, and `requests`. `language` takes exactly one value,
+**`text/javascript`** — `language: javascript` is a hard error,
+`Invalid input: expected "text/javascript"`. Omitting it is fine.
+
+The v2.1 `event:` field is not the v3 `scripts:` field. A script's `type` also
+depends on its scope; moving it between a request and a definition requires checking
+the type as well as the code. See the main skill's verification guidance for
+checking that the intended script behavior survives the edit.
+
 ## YAML rules
 
-Invalid YAML breaks parsing silently in confusing ways — when in doubt,
-single-quote it:
+YAML parsing and scalar coercion can change a field's meaning before schema
+validation. Preserve the type the field expects:
 
 1. Single-quote any value containing `{{variables}}`:
    `url: '{{base_url}}/users'` — never leave it unquoted.