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

package/skills/ci-integration/SKILL.md

@@ -1,122 +1,62 @@
 ---
 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". 
+description: Use when adding API tests, structural or governance lint, or AI-readiness gates to CI, or publishing reviewed API artifacts to a Postman workspace after merge. Makes contract checks repeatable and separates validation from shared workspace changes. Use for requests such as "run this collection on every PR".
 ---
 
 # 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.
-
-## Persist and share context — only after merge
-
-`postman workspace push -y` persists the merged repository's API context in
-the workspace for future work and enables sharing it with others. It is the one
-command in this skill that changes shared workspace 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.
+Versioned collections and specs let a PR carry its API checks beside the code
+change. CI reruns those checks independently of the author's session, while
+publishing after merge makes the reviewed contract available to teammates and
+future work. **api-discovery** helps identify consumers the gate should cover;
+the author's own passing tests do not establish cross-service compatibility.
+
+1. Select checks by the guarantee they establish:
+
+   | Guarantee | Gate |
+   | --- | --- |
+   | Saved behavioral assertions pass | `postman collection run <path-or-id>` |
+   | A collection's structure/style is valid | `postman collection lint <path> -f error` |
+   | A spec meets workspace governance rules | `postman spec lint <spec> --workspace-id <id> -f error` |
+   | Workspace entities and bindings pass lint/governance | `postman workspace lint --workspace-id <id> -f error` |
+   | Agent consumability meets an agreed threshold | `postman collection ai-readiness <path> --min-score <n>` or the spec equivalent |
+
+   Collection lint does not apply organization governance. Workspace-aware
+   lint evaluates the rules available to that workspace; it does not author
+   the policy. Confirm the intended rules are configured before claiming
+   compliance. Read command-specific `-h` for installed options.
+2. Keep gate results distinguishable so a failed build identifies behavior,
+   structure, governance, or readiness. Preserve nonzero exits; suppressing
+   them with `-x`/`--suppress-exit-code` removes the gate. For collection runs,
+   `-r junit,html` produces reviewable reports; `--bail` trades a complete
+   failure inventory for an earlier signal. See **api-testing** for assertion
+   semantics and **ai-readiness** for score limitations.
+3. Restore declared dependencies with `postman dependency install` when tests
+   use them. Choose the target deliberately: a mock checks behavior under a
+   model, while a live run sends real requests and can write data. PR gates
+   should use a suitable isolated target and credentials; being a test does
+   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.
+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
+   to new entities, so `--no-prepare` can leave additions unpublished.
+   Inspect the intended diff and binding when configuring this job; `-y`
+   supplies noninteractive execution, not authorization for a different scope.
+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.
 
 ## 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.
+Validate the workflow's event conditions and secret references, then report
+which gates actually ran, their targets and individual results. Distinguish a
+locally checked workflow from an observed CI run. For publication, establish
+the merge trigger, push strategy, created/updated entities, and conflicts;
+a green job alone does not prove the intended artifacts became available.

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

@@ -1,210 +1,49 @@
 ---
 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.
+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".
 ---
 
 # 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.
+A v3 collection is a directory of independently editable entities. A change to
+one request, example, or assertion can be reviewed in a PR beside the code it
+checks, without regenerating a single large collection export.
+
+1. Edit the entity that owns the change. Top-level directories under
+   `postman/collections/` are collections; nested folders organize requests.
+   Requests live in `*.request.yaml`, scope metadata in
+   `.resources/definition.yaml`, and saved responses in
+   `.resources/<request-name>.resources/examples/*.example.yaml`.
+   `.resources/` holds metadata and examples, not runnable request files.
+2. Preserve inherited auth, variables, and scripts when changing a request.
+   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.
+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
+   request body shape. The HTTP reference gives the exact fields.
+5. Keep edits local to the intended entity. `order` is a numeric relative
+   ordering, so spaced values allow insertion without renumbering siblings.
+   Keep filenames portable and unique case-insensitively; a display `name`
+   can preserve characters that cannot appear in a filename. Renaming a request
+   also requires checking its examples path.
+6. Save examples for behavior consumers need to understand or simulate.
+   Their schemas feed **api-documentation**, **api-mocking**, and
+   **ai-readiness**; structural validity alone does not make an example
+   accurate or useful. Assertions derived from the contract belong with the
+   request through **api-testing**.
+
+## 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.

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

@@ -0,0 +1,150 @@
+# HTTP collection files
+
+Read when authoring HTTP request, example, or definition YAML. These field
+shapes distinguish v3 files from exported collection JSON; validate edits with
+collection lint before relying on the result.
+
+## 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](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'
+```