@postman/postman-plugin 0.5.0 → 0.6.0-rc.0

package/skills/api-simulation/reference/context_file.md

@@ -1,159 +1,193 @@
-# `<name>.context.md`
+# `<name>.context.yaml`
 
-The handoff document beside a simulation: `postman/simulations/checkout.sim.yaml`
-gets `checkout.context.md`, and a foldered simulation keeps both in its folder.
-`simulation create` and the Postman app write it from what they already know,
+The handoff record beside a simulation: `postman/simulations/checkout.sim.yaml`
+gets `checkout.context.yaml`, and a foldered simulation keeps both in its folder.
+`simulation create` and the Postman app write it from a fixed template,
 `simulation update` renames it with the simulation, and `simulation delete`
-removes it. An existing one is never overwritten, because it holds what earlier
-sessions learned.
+removes it.
 
-It is prose for whoever works here next, human or agent. Nothing parses it, so
-there is no schema to satisfy — but the generated headings and the
-`<!-- begin:observations -->` markers are what a reader and the next write
-expect to find, so keep them.
+**Update the existing record without discarding prior claims or evidence.**
+Replacing it with a fresh template loses findings and unresolved assumptions
+while looking complete.
 
-Keep it to the generated sections plus `## What didn't work`, in Markdown,
-under about a screenful, so the line that matters is the one a reader lands on
-rather than one they have to search for.
+It carries what is believed about the services this simulation stands in for,
+and what each belief rests on. **api-simulation** is how a simulation is run,
+read and judged — its commands running clean is not yet the work being done.
 
-## What the generated file contains
+## Its shape
 
-A fresh file states the simulation's name, the date, its members and the hosts
-they stand in for, and the run command for this simulation's own path.
-Everything needing someone who has actually run it is left as an `@todo` HTML
-comment, so a half-filled file reads as half-filled instead of as fact.
+The whole file is YAML under a fixed key schema. The key names and the `status`
+vocabulary are fixed; the template carries each key's field schema in the
+comments above it. A `null` is something nobody has established yet.
 
-| Section | Holds |
+| Key | Holds |
 | --- | --- |
-| Header | Generation date and what the mocks came from. |
-| `## Purpose` | What the simulation stands in for and what work it unblocks. Generated as the member list and a pointer to the handlers; needs hindsight, so it is the last thing to rewrite. |
-| `## Execution` | The commands, in order: start the simulation, start the service pointed at it, prove it is up, count what got called, stop. The generated block leaves the service's own command, the proof request, the port and the log path as `@todo`. |
-| `## Assumptions` | Every precondition someone had to discover, what the simulation takes for granted about the dependencies' own behaviour, the seeded data worth reusing, and what the simulation cannot reproduce. Each is a dated claim, the consequence of it not holding, and how it was established. |
-| `## Observations` | One dated line per run, newest first, between the `begin`/`end` markers: which members took traffic and which took none. A summary, not a request log, and a failure goes in `## What didn't work` instead. |
-| `## What didn't work` | Failures this simulation has already hit, a dated line each: what broke, the signature you'd recognize it by, where it surfaced, and the cause. Not generated — add the heading at the end, after `## Observations`, the first time a run gives you one. |
-
-`## Observations` and `## What didn't work` both accrete, so a run is visible
-in the file after the next one; `## Purpose`, `## Execution` and
-`## Assumptions` are rewritten in place, since they describe the simulation as
-it stands rather than a run. Each accreting section is bounded: `## What didn't
-work` keeps the ten most recent, a line staying until a run shows it fixed, and
-`## Observations` the five most recent runs. Past that the oldest go.
-
-A run that keeps its line is how a pattern becomes visible — a member silent
-for three runs running is worth more than the same fact seen once.
-
-Don't restate what the generated file already says: its `## Assumptions` ships
-with the ones that hold for every simulation.
-
-## What earns a line
-
-Write what running it taught you, and only that. Each line passes one test:
-the repo doesn't already state it. That leaves five kinds of thing, and they
-are the file's whole value:
-
-- **A precondition you had to discover** — the setting, the service, the
-  cleanup a run needs before it works at all. In `## Assumptions`.
-- **A failure and its cause**, with where it surfaced, so the next session
-  recognizes it instead of debugging it again. In `## What didn't work`.
-- **What the run takes for granted about a dependency itself** — that an
-  operation is idempotent, that a timeout means nothing committed, what order
-  events arrive in. A mock answers these whether or not anyone checked, so its
-  answer is a belief your code now relies on. In `## Assumptions`.
-- **What the simulation can't reproduce, and what nobody has settled**, so a
-  passing run is read for what it actually proves. In `## Assumptions`.
-- **What the last run served**: which members took traffic, which stayed
-  silent, and why. In `## Observations`.
-
-For anything the repo does state — routes and request shapes, valid actions,
-auth mechanics, each mock's hosts, config flags — name the file that holds it,
-the way the generated `## Purpose` points at the handlers, and let the reader
-go there. One source stays true; a copy here drifts, and this file gets
-committed, so a named file is also how a credential stays out of it.
-
-Write statements that stay true between runs. Counts, timings and coverage
-belong to the run that produced them, so leave them in the log and keep the
-pattern here: "every member served except `workspace`" rather than a tally.
-
-## How a line carries its evidence
-
-The log a claim came from isn't committed, so the line is all the next session
-gets. Date every claim in `## Assumptions` and `## What didn't work`, and say
-where it came from when a run didn't show it: `(observed 2026-10-22)` for what
-a run established, `(reasoned 2026-10-22, src/payments/client.ts)` for what was
-read rather than run.
-
-A failure also carries the signature the next session will recognize it by —
-the error text, the status, the member that sent it — since that is what
-someone matches a new failure against. Quote the error itself, never a
-response body. For the rest, name the committed file that holds it: the
-handler that threw, the mock example captured from the real service, the test
-that reproduces it. Not the run's log, which is wherever that run redirected
-output and which the next run overwrites.
-
-A good `## Assumptions` is a claim, its consequence and its date; a good
-`## Observations` is a few lines; a good `## What didn't work` is one line per
-failure:
-
-```markdown
-## Assumptions
-
-- **`payments` treats a retried charge as idempotent on `Idempotency-Key`.**
-  If it doesn't, the retry path charges twice. Nobody has settled it and the
-  mock answers as though it does. (reasoned 2026-10-22, the mock's handler)
-- **Redis holds no `EVENT_BATCH` key when a run starts.** A leftover one
-  crashes the aggregation flush before any request is sent. (observed
-  2026-10-22)
-
-<!-- begin:observations -->
-2026-10-22: every member served except `workspace`, which the service never
-calls in development, and `god`, which models no endpoints.
-2026-10-18: same, and `payments` served only `POST /charges`.
-<!-- end:observations -->
-
-## What didn't work
-
-- 2026-10-22: the aggregation flush crashed on start —
-  `TypeError: batch.map is not a function` in `src/events/flush.ts`, from a
-  stale Redis `EVENT_BATCH` key an earlier run left behind. Not a simulation
-  error, so the log shows nothing.
-- 2026-09-30: `payments` answered `501` for `POST /refunds` — the mock models
-  no refund path, so a run that reaches it proves nothing about refunds.
+| `purpose` | `stands_in_for` and `unblocks` — what the simulation stands in for and what work it unblocks. Record the intended purpose when known and refine it as you learn, distinguishing intended outcomes from demonstrated results. The members it serves, their route keys and the hosts they answer for are in the `.sim.yaml` beside it. |
+| `assumptions` | What the code relies on about a dependency's behaviour. One claim per entry: `id`, `status`, `claim`, `reason`, `verification`, `source`, `updated_at`. |
+| `fingerprints` | What the claims were written against — `id`, `date`, `commit`, `cli`. |
+
+Everything else about this simulation lives where it already is: the members and
+their origins in the `.sim.yaml`, the handlers in `postman/mocks/`, and how to
+run any of it in **api-simulation**. Use this record to connect those details
+to the assumptions and findings a later session needs.
+
+Keep an entry when it helps a later session make a decision without repeating
+the investigation, even if supporting details already exist in the repo.
+For routes, request shapes, auth or config, link the file that holds them and
+record the conclusion, evidence and uncertainty relevant to the caller.
+Avoid copying details that can drift, and keep credentials out of this
+committed record.
+
+## What an assumption is
+
+A claim about how a dependency behaves, which the code under test relies on:
+what the caller is taken to be, which plan or permission is assumed, the order
+calls go in, what gets retried, the shape of the data. A mock answers these
+whether or not anyone checked, so its answer is a belief your code now carries.
+
+For example, checkout may retry a payment after a timeout without knowing
+whether the first attempt charged the customer. This illustrative entry
+records the provider assumption that makes that retry safe; the paths and
+run reference are examples, not evidence from this repository.
+
+```yaml
+- id: payment-retry-does-not-double-charge
+  status: unknown
+  claim: Retrying a payment for the same unchanged cart with identical payment
+    details and the same idempotency key within 24 hours creates at most one
+    charge at the payment provider, even if the first response times out.
+  reason: Checkout relies on this guarantee to retry without double-charging
+    the customer. The stand-in deduplicates payments by key, but that behavior
+    was configured by us; a passing simulation does not establish the
+    provider's retention window or handling of a retry after a timeout.
+  verification: On 2026-10-28, ran the checkout timeout test. The stand-in
+    recorded a successful charge, then delayed its response past the caller's
+    timeout. Checkout retried with the same payment details and key, and the
+    stand-in returned the original payment ID with one charge in its state.
+    This demonstrates caller key reuse in this scenario. The provider's
+    idempotency contract has not been checked; confirm its scope and retention
+    window, including retries after an ambiguous outcome, before relying on
+    this assumption for real payments.
+  source: src/checkout/submit-payment.ts; postman/mocks/payments/handler.js;
+    tests/checkout/payment-timeout.test.ts; runs/cart-payment-timeout-001
+  updated_at: "2026-10-28"
 ```
 
-## Working with it
-
-Read it before starting. An observed claim holds until your run contradicts
-it; a reasoned one is a hypothesis, so check it, cheaply, when your run depends
-on it. Check the assumptions and anything recorded about what a run doesn't
-prove before concluding that something works. A claim this run contradicts is
-a finding to report, not to quietly route around.
-
-What it already answers, it answers: `## Execution` holds commands that ran,
-and `## Assumptions` holds preconditions someone already established, so both
-are usable as they stand rather than as a starting point to rebuild from. The
-code you are about to change still needs reading; the setup around it is what
-this file is for. A session that reads the document and then repeats the
-search it was meant to replace has paid for it twice.
-
-Then leave it truer than you found it:
-
-- Replace the `@todo`s your run can answer, and delete each one you replace.
-- Correct what you found wrong. Say what it is now, not what it used to be.
-- Add the precondition you had to discover, or the thing the simulation turned
-  out not to reproduce, as another dated claim-and-consequence pair.
-- Add what broke and why to `## What didn't work`, and delete the lines there
-  your run showed fixed.
-- Add this run's summary to the top of the `## Observations` block, read from
-  the simulation's log, and drop the oldest line past five.
-
-A run that only confirms the file still adds its `## Observations` line.
-
-## Rules
-
-- Leave another session's assumptions and limits standing unless your run
-  contradicted one: not exercised is not the same as not true.
-- Keep this file for how the simulation behaves, and let the `.sim.yaml`
-  speak for what it is.
-- Rewrite `## Purpose` when the simulation's scope genuinely changed.
-- Prefer deleting a line to adding one. Everything here is something the next
-  session must either trust or re-check.
+One claim per entry. A sentence holding two claims is two entries, because
+evidence can settle one and leave the other standing.
+
+### `status`
+
+| Value | Means | For example |
+| --- | --- | --- |
+| `supported` | Evidence supports the claim, within a stated scope. | The provider guarantees idempotency for 24 hours. |
+| `contradicted` | Evidence provides a counterexample. | A timed-out request did create an order. |
+| `unknown` | Available evidence cannot establish or reject it. | Key scope across token refresh is unspecified. |
+| `conflicting` | Applicable sources disagree. | Documentation promises immediate revocation; a real probe observes continued access. |
+
+`supported` is the one to be careful with: support comes with a scope, so the
+claim says what that scope is. Name the operation, relevant conditions and
+window the evidence covers. Narrow an overbroad claim before marking it
+`supported`; a check at one point in a window does not establish behavior
+throughout it.
+
+`contradicted` and `conflicting` are findings to report, not states to route
+around. A contradiction says the code relies on something untrue; a conflict
+says two sources disagree and nobody has settled which governs — often a
+contract promising one thing while the running service does another.
+
+### `reason`, `verification` and `source`
+
+Three different jobs, and keeping them apart is what makes a claim checkable.
+
+`reason` is the judgment: why the evidence adds up to this status. It is the
+field that earns its place on a `conflicting` or `unknown` claim, where the
+status alone does not say what is unresolved.
+
+`verification` is what was actually done and what it showed — a contract read,
+a request made and its response, a handler inspected. Include when the
+verification occurred and the revision or environment it covered, using a
+fingerprint entry where applicable. Name what is still
+planned or blocked and what would settle it, and say when a piece of evidence
+has gone stale and why, since stale evidence stays as history but cannot
+establish a current status.
+
+Match the claim to the kind of evidence. A mock handler shows what the
+stand-in models; a simulated run shows how the caller behaved under that
+model. Neither independently establishes the real dependency's behavior.
+Use provider evidence for that: distinguish a published contract's promise
+from behavior observed against the real service, and retain the conditions
+and scope of each. If only the mock supports a provider assumption, that
+assumption remains `unknown` even when the caller test passes.
+
+`source` is where to go and re-check it, so the next session can audit the
+claim rather than take it on trust. Any of:
+
+- a file and line range in this repo, where the code shows what it relies on;
+- a request that was actually made and what came back — the target environment
+  (stand-in or real service), sequence and status codes, with a retrievable
+  test or run reference where available;
+- the dependency's own code, or its published contract, read for the endpoint
+  in question.
+
+A claim is only as good as what it points at, so `source` carries the specific
+thing, not its category: `api/policies/hasAccess.js:12-115` rather than "read
+the code". A claim with nothing to point at is `unknown`.
+
+Where two sources disagree, `verification` says what each one showed and
+`status` is `conflicting` — that is the state a contract promising one thing
+while the running service does another belongs in.
+
+### `updated_at`
+
+The day the entry was last written, `YYYY-MM-DD`. Set it when you add a claim,
+and set it again whenever you change one — a new status, a fresh piece of
+verification, a reworded claim.
+
+This date tracks record maintenance. Rewording a claim does not refresh its
+evidence: judge that from the date, revision and environment in `verification`
+and its referenced fingerprint. Re-check when relevant behavior or conditions
+have changed, or when the evidence's applicability is unclear.
+
+Nothing enforces this. `simulation create` writes an empty list and no command
+edits entries, so the field is only as true as the session that last wrote it.
+
+## Where claims come from
+
+Evidence first, claim second. Make the run or read the code, then write down
+what it establishes — including the parts nobody had written down before, which
+are the valuable half: a call order you did not expect, a dependency answering
+something the code does not handle, a member never called at all.
+
+Going the other way — writing the claim and then looking for something to back
+it — is how a guess ends up marked `supported`. A claim written ahead of any
+evidence is fine; it is `unknown` until something points at it.
+
+## Fingerprints
+
+What the claims were written against: `git rev-parse HEAD` and
+`postman --version`. Append an entry when either differs, and say so when the
+tree is dirty — a sha alone reads as a clean checkout.
+
+Tie each verification to the fingerprint it used. Appending a new fingerprint
+does not revalidate older claims. A changed commit or CLI is a reason to
+assess whether relevant behavior changed; it does not by itself invalidate
+all prior evidence.
+
+## Reading it before you start
+
+Read the claims relevant to the task before repeating dependency research.
+Compare their scope and evidence with the code, configuration and provider
+conditions your work depends on. Reuse findings that still apply, and inspect
+the code you are changing to identify assumptions the change may affect.
+
+Treat `supported` as conditional on that applicability, not as a permanent
+guarantee. Revisit affected claims when relevant conditions change or their
+evidence no longer establishes the current behavior. If current support is
+unresolved, mark the claim `unknown` and preserve the prior evidence with the
+reason it no longer settles the question. An `unknown` or `conflicting` claim
+is worth investigating when the task depends on it; record what would settle
+it if verification remains blocked.
+
+Preserve unrelated claims and their history. A claim not exercised in this
+session is not thereby contradicted or stale.

package/skills/api-simulation/reference/sim_yaml_schema.md

@@ -26,7 +26,7 @@ since the file is what declares the hostnames.
 `simulation create` writes each `path:` relative to the repository root, the
 directory holding `postman/`, and puts the simulation in a folder of its own
 (`postman/simulations/checkout-dev/checkout-dev.sim.yaml`) so its
-`<name>.context.md` sits beside it; the app records that document in a
+`<name>.context.yaml` sits beside it; the app records that document in a
 `context:` ref. Reading is broader than writing — a path relative to
 `postman/simulations/`, to the file, absolute or `~/`, naming the folder or
 the manifest inside it, all resolve — and an unresolvable one names every

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.