@postman/postman-plugin 0.1.1-rc.0 → 0.1.2-rc.0

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: bootstrap
+description: Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.
+---
+
+# Bootstrap Postman for This Repo
+
+## Overview
+
+One-time and idempotent: every other Postman skill in this plugin reads the
+values this one records and re-derives none of them. Finding an existing
+`postman/` tree or an OpenAPI file is a signal to inspect, not to assume this
+repo is already set up.
+
+## Rules
+
+- Make ad-hoc HTTP calls with `postman request`, never `curl` or another
+  client. If the request already exists in a collection, preserve its saved
+  auth, variables, scripts, and payload by using `postman collection run
+  <collection-path> -i <request>` instead of reconstructing it on the command
+  line; see `api-testing`.
+- Never invent a subcommand or a flag. Run `-h` first and believe it.
+- Lint specs with `postman spec lint`, never `postman api …` — the API Builder
+  is deprecated in v12+ and the CLI prints no warning.
+- Local commands need no login; only commands that reach the Postman
+  workspace do. Don't force a login the task doesn't need.
+- A missing `postman` binary means install it. Route to `postman-mcp-server`
+  only after an install has been attempted and actually failed.
+- Never fabricate a workspace id, spec path, or collections directory. Report
+  the gap and stop.
+- Never echo an API key or session token into output, logs, or summaries.
+- "Present" is not "current": check the version and existing links before
+  setting anything up.
+- Wire up an existing repo only. Never scaffold a new API or a starter spec.
+- Write no host-specific paths — the same `skills/` directory loads on every
+  route.
+- Do not use `init` or `workspace create` to share or import a workspace that
+  already exists. Choose the direction of sync from the lifecycle table below.
+
+## Ask the CLI: `-h`
+
+The CLI is self-describing at different levels. Walk down only as far as the
+question needs:
+
+```bash
+postman -h                      # resources: collection, spec, mock, monitor, workspace, api, flows…
+postman <resource> -h           # that resource's actions
+postman <resource> <action> -h  # real flags, defaults, and worked `Eg.` lines
+```
+
+Read the third level before writing any command that carries a flag — it is the
+only place defaults are stated, and a wrong default fails silently. Live output
+is authoritative over any summary, including this file. There is also no single
+verb for "is the workspace linked and synced": run `postman workspace -h` and
+pick from what it prints.
+
+---
+
+# Process
+
+Three steps, in order. Stop at the first that fails and report which one.
+
+## 1. Resolve the CLI
+
+### 1.1 Check what is already there
+
+**Present, and at which version?**
+
+```bash
+command -v postman && postman --version
+```
+
+**Current?** Never blocking — no network is a normal answer. But don't call a
+feature missing without having made this comparison.
+
+```bash
+npm view postman-cli version
+```
+
+### 1.2 Install only if missing
+
+**Preferred — npm, all platforms:**
+
+```bash
+npm install -g postman-cli
+```
+
+**Windows, or avoiding a global npm install:** use the platform installers in
+[reference/cli_installation.md](reference/cli_installation.md). Every route puts
+`postman` on `PATH`.
+
+**Updating a copy that already exists:** use the same route that installed it.
+curl-installed binaries don't take `npm install -g` cleanly.
+
+**If every route fails:** name what blocked you — no Node, no shell, no write
+access, or a hosted session that cannot install — then hand off to the
+`postman-mcp-server` skill. An attempted install that actually failed is the
+only thing that qualifies.
+
+## 2. Establish the filesystem and workspace bindings
+
+### 2.1 Authenticate only if this step needs it
+
+Local commands need no login, and `postman init` is among them — its own help
+says *"No authentication, and safe in CI."* Skip this entirely unless the
+command you're about to run pulls or pushes an existing workspace, or shares
+one with a team.
+
+**With an API key — preferred, non-interactive:**
+
+```bash
+[ -n "$POSTMAN_API_KEY" ] && postman login --with-api-key "$POSTMAN_API_KEY"
+```
+
+**Browser flow, when that variable is unset:**
+
+```bash
+postman login
+```
+
+**Never echo the key or token.** Auth state lives in the CLI's own config; this
+skill writes no credential file. Report that authentication succeeded, nothing
+more.
+
+### 2.2 Inspect both sides before choosing a command
+
+Read `.postman/resources.yaml` for `localResources` and `workspace.id`, and
+inspect the local `postman/` tree. When the user names an existing workspace or
+asks to import, sync, or share one, use `workspace list --json` and `workspace
+get <id> --elements --json` to confirm the workspace side. Never create a
+second workspace merely because this repository is not connected yet.
+
+Prefer filesystem-first work: materialize an existing workspace with
+`workspace pull <id>`, or initialize local files with `postman init --no-cloud`
+when no workspace exists. Then inspect, edit, diff, and validate the
+version-controlled files before any push.
+
+| Existing state and intent | Use | Why |
+| --- | --- | --- |
+| No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |
+| No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |
+| Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |
+| Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |
+| Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |
+| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |
+| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |
+
+If “share” also requires changing a personal workspace's visibility or team
+permissions, inspect its metadata first. `push` synchronizes entities; it does
+not change access control. Do not create a replacement to work around a missing
+metadata-update command.
+
+`workspace diff` is read-only. Match its push strategy to the intended push.
+`--push-strategy force-sync` can delete workspace entities absent locally, so use it
+only when the user explicitly requests mirroring and approves the shown
+deletions. Do not add `-y` merely to bypass a prompt.
+
+### 2.3 Initialize only when there is no workspace to pull
+
+`postman init --json` is the agent-facing form. It writes
+`.postman/resources.yaml` and scaffolds `postman/` for specs, collections and
+environments. Downstream skills read that file and nothing else.
+
+```bash
+postman init --json --no-cloud               # local only, no workspace
+postman init --json --visibility personal    # also create and bind a workspace
+```
+
+Use `--visibility` only when a new workspace is actually wanted. If the
+workspace already exists, use `pull` to enable the filesystem workflow;
+use `push` only when publishing local changes to an already-bound workspace.
+
+**The workspace step is interactive** without `--no-cloud` or `--visibility`.
+
+**Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.
+Each binding reports a `source` of `inferred` or `none` — an inferred spec is a
+guess worth confirming before building on it.
+
+**Exit codes that are not failures:** 2 means several specs could be
+authoritative, so re-run with `--spec <path>`. 5 means the local files were
+written but the requested workspace was not created — it does *not* mean re-run.
+
+## 3. Verify and report
+
+### 3.1 Checkpoints
+
+- `postman --version` returned a real version.
+- Auth is confirmed, or established as not required for this task.
+- `.postman/resources.yaml` names a spec or a collections directory.
+- `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`
+  leaves it empty and still exits 0, which is a pass, not a gap.
+- After `pull`, expected workspace entities exist under `postman/`. After
+  `push`, report created/updated entities and conflicts; do not claim a
+  workspace is shared unless its access level permits the intended teammates.
+
+"The CLI is installed" is not the bar, and a loaded skill configures nothing.
+
+### 3.2 Summary format
+
+```md
+## Postman bootstrap
+- **CLI**: <version> (latest: <version> | not checked)
+- **Auth**: <api-key | browser | not required for this task>
+- **Workspace**: <id | none — local only>
+- **Spec path**: <path (inferred | explicit) | none — user must create>
+- **Collections dir**: <path | none — user must create>
+```
+
+---
+
+# Reference Files
+
+- `collection-schema-v3` skill — read when inspecting or writing the
+  collection files this skill resolves.
+- [CLI Installation](reference/cli_installation.md) — read for install, update
+  and uninstall commands per platform.

package/skills/bootstrap/reference/cli_installation.md

@@ -0,0 +1,58 @@
+# Postman CLI Installation
+
+A global install, on `PATH`, installed by one of three tools depending on
+platform. Whichever one put the binary there is the one to use again when
+updating it — mixing tools leaves two `postman` binaries and a `PATH`
+question.
+
+## Install
+
+**npm (all platforms):**
+
+```bash
+npm install -g postman-cli
+```
+
+**macOS, Linux, and WSL (curl):**
+
+```bash
+curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+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'))"
+```
+
+## Check for drift
+
+```bash
+postman --version              # installed
+npm view postman-cli version   # latest published
+```
+
+## Update
+
+Run the same command that installed it — the npm, curl or PowerShell line
+above, whichever put the binary there. Using a different one leaves two
+`postman` binaries and a `PATH` question. Never `npm install -g` over a copy
+that came from the curl installer or a system package manager.
+
+The CLI has no self-update verb. `postman skills update` is a different
+thing: it refreshes a repository's committed `postman/skills/`, not the
+binary.
+
+## Uninstall
+
+npm installations:
+
+```bash
+npm uninstall -g postman-cli
+```
+
+Other install methods: delete the `postman` binary from its install
+directory (`%USERPROFILE%\AppData\Local\Microsoft\WindowsApps` on Windows,
+`/usr/local/bin` on macOS/Linux/WSL).
+
+Source: https://learning.postman.com/docs/postman-cli/postman-cli-installation/

package/skills/ci-integration/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ci-integration
+description: Common CI integrations that can added as independent pass/fail gates. Use when the user asks to "add Postman to CI," "run this collection on every PR," "fail the build on a governance violation," or "push to the postman cloud workspace after merge to main", "add some api related operation in my Github actions". 
+---
+
+# CI Integration
+
+## Overview
+These are some common workflows that one can add in their CI pipeline leveraging postman cli.
+
+## Run a collection — a gated pipeline step
+
+`postman collection run <path/id>` exits nonzero on a failed `pm.test`
+assertion, which is what makes it a usable gate — see `api-testing` for how
+that exit code actually gets set. What's CI-specific: `-r junit,html` (or
+`--reporter-*-export`) writes a report your CI provider can surface as
+build artifacts or test annotations, instead of leaving the result buried in
+a log. `--bail` stops the run early on the first failure when a fast signal
+matters more than a full report.
+
+## Lint — pick the target that matches the gate you want
+
+Three verbs look interchangeable and aren't — only two of them apply your
+organization's governance rules, and the CLI's own `-h` output is where that
+becomes visible (no assumption below goes further than what it printed):
+
+| Want to check | Command | Applies org governance? |
+| --- | --- | --- |
+| One spec against your rules | `spec lint <spec> --workspace-id <id> -f error` | Yes, via `--workspace-id` |
+| One collection's structure/style | `collection lint <path> -f error` | **No** — this verb takes no `--workspace-id` at all |
+| The whole workspace: every entity plus `.postman/resources.yaml` | `workspace lint --workspace-id <id> -f error` | Yes |
+
+`collection lint` is a schema/style check only — running it and reporting
+"governance passed" overstates what it did. If the ask is "does this
+collection violate our rules," `workspace lint` is the one that actually
+answers it (and covers every collection in the repo in one pass); reach for
+bare `collection lint` only when there's no workspace to fetch rules from
+yet.
+
+## Push to workspace — only after merge
+
+`postman workspace push -y` is the one command in this skill that changes
+shared cloud state, so it belongs behind a merge-to-main trigger, not a PR
+trigger. `-y` skips confirmation prompts a non-interactive job can't answer.
+Leave `--no-prepare` off — the default prepare step is what assigns real IDs
+to entities that are new since the last push; skipping it because a run
+felt slow trades a few seconds for a push that silently fails to create
+anything new.
+
+`--push-strategy force-sync` mirrors the whole workspace, deleting any cloud
+entity with no local counterpart — genuinely destructive, and not the
+default for a reason. See Critical Rules before adding it to a merge job.
+
+## AI readiness threshold
+
+`collection ai-readiness <path> --min-score <n>` and its spec-side
+counterpart `spec ai-readiness <path> --min-score <n>` (see `ai-readiness`
+skill) are a fourth, separate gate — they score AI-agent consumability, not
+test results or governance/structural style. Keep either in its own step:
+folding it into the same step as `run` or one of the `lint` verbs above
+hides which kind of check actually failed when the job goes red. Pick the
+verb that matches what's checked into the repo — `collection ai-readiness`
+for a git-synced collection, `spec ai-readiness` for an OpenAPI spec with no
+collection generated from it yet.
+
+```yaml
+- run: postman collection ai-readiness ./postman/collections/My\ API --min-score 70
+```
+
+## Critical Rules
+
+1. **Never collapse `run`, `lint`, and `ai-readiness` into one step, and
+   never pass `-x`/`--suppress-exit-code` to a CI run.** One combined exit
+   code hides which check broke; a suppressed one hides that anything broke
+   at all.
+2. **Gate `workspace push` to the merge event, never a PR event.** Everything
+   else in this skill is read-only against the cloud; this is the one
+   command that writes to it, so a PR-triggered push ships an unmerged
+   branch's entities to the shared workspace.
+3. **`--push-strategy force-sync` deletes cloud entities absent locally.**
+   Only add it to a job whose explicit job is mirroring the workspace exactly,
+   with that intent confirmed — never as the default merge step, where the
+   default (create/update-only) strategy is the safe choice.
+4. **Authenticate once, non-interactively:**
+   `postman login --with-api-key "$POSTMAN_API_KEY"`, reading the key from
+   the CI provider's secret store. Don't reach for `collection run`'s
+   `--postman-api-key` as the general answer — it's US-region only — and
+   `spec lint`/`workspace push` don't take it at all.
+
+   ```yaml
+   # WRONG — key committed in plain text, and scoped to one command anyway
+   - run: postman collection run api.json --postman-api-key PMAK-abc123...
+
+   # CORRECT — one non-interactive login, key from the provider's secret store
+   - run: postman login --with-api-key "$POSTMAN_API_KEY"
+   - run: postman collection run api.json
+   - run: postman spec lint spec.yaml --workspace-id $WS -f error
+   ```
+5. **Never `newman run` in place of `postman collection run`.** The CLI is
+   the supported runner every other skill here assumes; Newman forks the
+   toolchain and skips whatever reporting/governance depends on the CLI
+   specifically.
+
+## Verification
+
+State each gate that ran and its individual result — not "CI passed," but
+which check ran, what it checked (governance vs. structure per the Lint
+table above, or AI-agent consumability for `ai-readiness`), and its exit
+code. If `workspace push` ran, confirm it was triggered by the merge event
+and not a PR event, state which push strategy was used, and report
+`Created`/`Updated` per entity rather than just "push succeeded." Confirm
+no secret value appears literally in the committed workflow file.
+
+## Reference
+
+- `api-testing` skill — `collection run`'s exit-code semantics and reporter
+  flags in full.
+- `collection-schema-v3` skill — what `workspace push` is actually pushing.
+- `bootstrap` skill — CLI resolution, workspace linking, `.postman/resources.yaml`.
+- `ai-readiness` skill — `collection ai-readiness`, `spec ai-readiness`, and
+  their `--min-score` gate.

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

@@ -0,0 +1,210 @@
+---
+name: collection-schema-v3
+description: The reference for the git-native v3 collection file format — one YAML file per request/folder/example under postman/collections/, plus postman/environments/. Read before writing, editing, or generating any file in either directory by hand, or before debugging a `collection lint` failure. Covers the HTTP request/example/definition schema, environment schema, and the YAML/naming rules that make files parse — GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas are non-HTTP protocols and live in reference/other_protocols.md, read only when a collection actually uses one.
+---
+
+# Collection Schema (v3, Git-Native)
+
+## Overview
+
+A v3 collection is a directory tree under `postman/collections/`, one file
+per entity — every request, every folder's metadata, every saved example is
+its own file. There is no single collection.json to open and edit; the
+directory structure itself *is* the collection.
+
+```text
+postman/collections/
+  bookstore api/
+    .resources/
+      definition.yaml (optional)
+      get all books.resources/
+        examples/
+          200 OK.example.yaml
+          400 Bad Request.example.yaml
+          500 Internal Server Error.example.yaml
+    get all books.request.yaml
+    get-book-by-id.request.yaml
+    add new book.request.yaml
+    authentication/
+      .resources/
+        definition.yaml (optional)
+      signup.request.yaml
+      login.request.yaml
+```
+
+- Every folder under `postman/collections/` is a collection; it can contain
+  subfolders and requests.
+- A folder or collection can have a `.resources/` directory — an optional
+  metadata directory for that scope. `.resources/definition.yaml` holds the
+  collection/folder's own metadata; request examples live under
+  `.resources/<request-name>.resources/examples/`.
+- Never place a request file inside a `.resources/` directory — those are
+  metadata-only.
+
+## Definition file (`.resources/definition.yaml`)
+
+Optional metadata for a collection or folder:
+
+- `$kind: "collection"` — required, even for a folder's definition.
+- `name` — optional, defaults to the filesystem folder name.
+- `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}, ...]}`,
+  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`,
+  `graphql:beforeQuery`, `graphql:afterResponse`, `grpc:beforeInvoke`,
+  `grpc:onIncomingMessage`, `grpc:afterResponse`.
+- `order` — number, used for folder ordering.
+
+## HTTP request (`*.request.yaml`)
+
+- `$kind: "http-request"` — required.
+- `name` — optional (see naming rules below for when to include it).
+- `order` — number; only used for relative comparison, so space values out
+  (e.g. multiples of 1000) rather than packing them tight — a later
+  insertion between two requests shouldn't force renumbering every sibling.
+- `url` — string, with `{{varName}}` variable syntax.
+- `method` — `GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS`.
+- `headers` — array of `{key, value, description?, disabled?}`.
+- `queryParams` — array of `{key, value, description?, disabled?}`.
+- `pathVariables` — array of `{key, value, description?}`.
+- `body` — `{type, content}`; `type` required whenever `body` is present.
+  - Types: `json`, `formdata`, `urlencoded`, `text`, `xml`, `html`,
+    `javascript`, `file`, `none`.
+  - `json`/`text`/`xml`/`html`/`javascript`: `content` is a string.
+  - `formdata`: `content` is an array of
+    `{key, type: "text"|"file", value or src, contentType?, description?}`.
+  - `urlencoded`: `content` is an array of `{key, value, description?}`.
+- `auth` — `{type, credentials}`.
+- `settings` —
+  `{protocolVersion?, strictSSL?, followRedirects?, maxRedirects?, disabledSystemHeaders?}`.
+- `scripts` — array of `{type: "beforeRequest"|"afterResponse", code, language: "text/javascript"}`.
+- `examples` — optional, a relative path to the examples directory, e.g.
+  `./.resources/<request-name>.resources/examples/`.
+
+## HTTP example (`*.example.yaml`)
+
+- `$kind: "http-example"` — required.
+- `name` — optional.
+- `request: {url, method}`.
+- `response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}`.
+- `order` — optional.
+
+Saved examples are what `collection ai-readiness` checks for — a request
+with no examples scores worse for agent consumption even if perfectly
+valid structurally.
+
+## Environments (`postman/environments/*.environment.yaml`)
+
+Environment files are v3 YAML but are not collection entities: they do not use
+`$kind`. Before creating or editing one by hand, read
+[reference/environment.md](reference/environment.md) for the schema, secret
+handling, CLI-first edit commands, and a linted example.
+
+## YAML rules
+
+Invalid YAML breaks parsing silently in confusing ways — when in doubt,
+single-quote it:
+
+1. Single-quote any value containing `{{variables}}`:
+   `url: '{{base_url}}/users'` — never leave it unquoted.
+2. Single-quote values containing `: # & * ! [ ] { } > |`, e.g.
+   `name: 'Health check: v2'`.
+3. Multi-line content (JSON bodies, scripts, queries) uses a `|-` block
+   scalar:
+   ```yaml
+   body:
+     type: json
+     content: |-
+       {
+         "name": "example"
+       }
+   ```
+4. Quote strings that resemble booleans/numbers when a string is intended:
+   `value: "true"`, `value: "123"`.
+5. `order` must be a bare number, never quoted: `order: 1000`.
+6. Single-quote file paths and use forward slashes only:
+   `examples: './.resources/name.resources/examples'`.
+
+## Naming rules
+
+- `<request-name>` (the filename stem before `.request.yaml`) must not
+  contain `/ \ : * ? " < > |` — sanitize to `-`.
+- Include `name` in the file only when it differs from `<request-name>`
+  (e.g. `name: 'Health/check'` inside `Health-check.request.yaml`, since the
+  filename itself can't hold the `/`).
+- Filenames must be unique, case-insensitively, per directory.
+
+## Worked example: "bookstore api"
+
+`postman/collections/bookstore api/get all books.request.yaml`
+```yaml
+$kind: http-request
+method: GET
+url: '{{base_url}}/books'
+order: 1000
+```
+
+`postman/collections/bookstore api/get-book-by-id.request.yaml`
+```yaml
+$kind: http-request
+name: 'get book by :id'
+method: GET
+url: '{{base_url}}/books/:id'
+order: 2000
+pathVariables:
+  - key: id
+    value: '1'
+```
+
+`postman/collections/bookstore api/add new book.request.yaml`
+```yaml
+$kind: http-request
+method: POST
+url: '{{base_url}}/books'
+order: 3000
+headers:
+  - key: Content-Type
+    value: application/json
+body:
+  type: json
+  content: |-
+    {
+      "title": "Example Book",
+      "author": "Jane Doe"
+    }
+```
+
+`postman/collections/bookstore api/.resources/definition.yaml`
+```yaml
+$kind: collection
+name: Bookstore API
+variables:
+  - key: base_url
+    value: 'https://api.bookstore.com/v1'
+```
+
+## Critical Rules
+
+1. **Every entity is its own file — there's no single collection.json to
+   open.** A request, its parent folder's metadata, and its saved examples
+   are three separate files, not sections of one document.
+2. **Unquoted `{{variables}}` or special characters are the most common way
+   a hand-written file fails to parse.** Single-quote per the YAML rules
+   above rather than debugging a cryptic lint error after the fact.
+3. **`order` is relative, not an index.** Don't renumber every sibling file
+   to insert one request — leave headroom (spacing of 1000) from the start.
+4. **This file covers HTTP only.** A collection using GraphQL, gRPC,
+   WebSocket, Socket.IO, MQTT, MCP, or LLM requests needs
+   [reference/other_protocols.md](reference/other_protocols.md) — don't
+   guess those schemas from the HTTP shape above, they diverge in real ways
+   (e.g. gRPC's `methodDescriptor`, LLM's `userPrompts`/`systemPrompts`).
+
+## Reference
+
+- [Other request protocols](reference/other_protocols.md) — GraphQL, gRPC,
+  WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas.
+- [Environment schema](reference/environment.md) — v3 environment filenames,
+  fields, variable types, safe editing commands, and validation.

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

@@ -0,0 +1,63 @@
+# Environment Schema (v3)
+
+Read this reference before creating, editing, or debugging files under
+`postman/environments/`.
+
+## Prefer the CLI for ordinary edits
+
+The CLI preserves the schema and avoids leaking secret values into command
+output:
+
+```bash
+postman environment new "Staging EU"
+postman environment var set baseUrl https://staging.example.com \
+  --environment "postman/environments/Staging EU.environment.yaml"
+postman environment var unset oldToken \
+  --environment "postman/environments/Staging EU.environment.yaml"
+postman environment lint postman/environments --fail-severity warning
+```
+
+Use `environment get --show-secrets` only when the user explicitly needs the
+secret value revealed. Do not print, summarize, or commit credentials returned
+by it.
+
+## File and fields
+
+An environment is one YAML file named `<name>.environment.yaml` under
+`postman/environments/`. It has no `$kind` field.
+
+- `name` — required string.
+- `values` — required array; an empty environment uses `values: []`.
+- Each value has:
+  - `key` — required variable name.
+  - `value` — required string. Quote booleans, numbers, empty values, and
+    values containing YAML punctuation or `{{variables}}` so YAML does not
+    coerce them.
+  - `enabled` — boolean. The CLI writes `true` for a newly set variable.
+  - `type` — optional string. Use `default` for ordinary values and `secret`
+    for sensitive values.
+  - `description` — optional string.
+
+Do not add collection-only fields such as `$kind`, `scripts`, `auth`, or
+`variables`. Do not put secrets into an example merely to make it executable;
+leave the value empty or use the team's supported secret source.
+
+## Linted example
+
+```yaml
+name: Staging EU
+values:
+  - key: baseUrl
+    value: 'https://staging.example.com'
+    enabled: true
+    type: default
+    description: API base URL
+  - key: apiToken
+    value: ''
+    enabled: false
+    type: secret
+```
+
+After any hand edit, run `postman environment lint <file-or-directory>`. Use
+`postman workspace lint` when the task is to validate the entire local
+workspace, not just its environments.