@postman/postman-plugin 0.3.0 → 0.4.0

package/skills/bootstrap/SKILL.md

@@ -1,230 +1,129 @@
 ---
 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.
+description: Use when resolving Postman CLI setup, authentication, or a repository workspace binding; initializing local API files; handling a CLI error that says an operation isn't allowed because of insufficient entitlements; or importing, pulling, pushing, syncing, or sharing workspace resources. Reuses existing context and chooses sync direction without duplicating a workspace or rebinding a dependency. Use for requests such as "set up Postman for this repo".
 ---
 
 # 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.
-- 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.
-- Operate inside a repository, including a fresh repository for a new project.
-  Never scaffold the API implementation 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.
-- Before pulling, apply `api-discovery`'s owning-workspace-versus-dependency
-  distinction; finding a workspace does not by itself make it this
-  repository's workspace.
-
-## 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
-
-**npm — all platforms, using Node's global package install:**
-
-```bash
-npm install -g postman-cli
-```
-
-**Platform installers — direct shell installs for macOS, Linux, WSL, and
-Windows:** use the commands 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
-
-`postman init` needs no normal login — init uses an agent-scoped session.
-Do not log in before init. Authenticate only when the command you're about to
-run operates on an existing workspace, such as listing, inspecting, pulling,
-pushing, or changing access to one.
-
-**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. Also establish
-whether that workspace owns the service represented by this repository. Never
-create a second workspace merely because this repository is not connected yet,
-and never replace this repository's binding with another service's workspace.
-
-Prefer filesystem-first work. For the current service, materialize its existing
-workspace with `workspace pull <id>`, or create and bind one with `postman init
---json --visibility <personal|team>` when no workspace exists. For another
-service, use `postman dependency add <type> <name-or-id>` as described in
-`api-discovery`. Then inspect, edit, diff, and validate the version-controlled
-files before any push.
-
-| Existing state and intent | Use | Why |
-| --- | --- | --- |
-| No workspace exists; create and bind one | `postman init --json --visibility <personal|team>` or `postman workspace create --visibility <value>` | Creates and binds the owning workspace; the init path also creates the git-native filesystem. |
-| The current service's workspace exists; enable filesystem work in its repository | `postman workspace pull <workspace-id>` | Connects the owning workspace to the repository and materializes its entities under `postman/`. |
-| The current service's workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds its repository without downloading its contents. |
-| Another service's resource is needed here | `postman dependency add <type> <name-or-id>`; add `--workspace <workspace-id>` when resolving a name in a specific workspace | Declares and downloads only that collection, environment, or mock without rebinding this repository or pulling the other service's whole workspace. |
-| 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` | Persists the local API context for future work and sharing with others by publishing 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` | Persists local context in the existing workspace so teammates can share and build on it; `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 --visibility personal
-postman init --json --visibility team
-```
-
-Use `--visibility` only when a new workspace is actually wanted. If the
-current service's workspace already exists, use `pull` from that service's
-repository to enable the filesystem workflow. If the existing workspace
-belongs to another service, use it as a dependency instead. Use `push` only
-when publishing local changes to an already-bound workspace.
-
-Without `--visibility`, interactive init prompts for the workspace step, while
-`--json` skips that step because it may not prompt. Use `--visibility` when an
-agent should create and bind a workspace non-interactively; omit it when a
-local-only setup is intended.
-
-**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.
-- When workspace creation was requested or the repository was already bound,
-  `workspace.id` is set to the owning workspace. A deliberately local-only
-  init may omit it.
-- 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 | not requested | creation failed: reason>
-- **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.
+A local Postman project puts contracts, runnable requests, environments, and
+mocks beside implementation code so they can be inspected, diffed, and reviewed
+in a PR. A workspace binding connects that work to maintained shared context.
+Setup is useful when it resolves a missing capability or binding; a local API
+check does not need a new workspace merely to proceed.
+
+## Resolve only the missing setup
+
+Inspect `postman --version`, `.postman/resources.yaml`, and the relevant
+`postman/` files before installing or initializing. Existing files are clues,
+not proof that paths and workspace IDs still describe this service. Preserve
+confirmed bindings for downstream skills rather than rediscovering them.
+
+**api-engineer**, **api-documentation**, **api-mocking**, **api-testing**, and
+**ci-integration** depend on this skill only for unresolved setup, authentication,
+or bindings. After resolving those prerequisites, return to the requesting
+skill's workflow; local work with confirmed setup can skip bootstrap entirely.
+
+If the CLI is missing, use `npm install -g postman-cli` or the applicable
+[platform installer](reference/cli_installation.md). Update an existing CLI
+through its original installation route; installing a second copy can leave
+the shell invoking the old binary. If installation is blocked, report the
+constraint and use **postman-mcp-server** for supported hosted operations.
+
+Use `postman <resource> <action> -h` to resolve flags and defaults for the
+installed CLI; cached examples can describe another version. Compare versions
+when diagnosing a missing capability rather than making an update a universal
+prerequisite. Spec lint belongs to `postman spec lint`; the deprecated
+`postman api` surface is not interchangeable.
+
+Local file operations need no normal login. `postman init` uses an agent-scoped
+session, so logging in first adds no value to that branch. Authenticate when
+an operation needs existing workspace resources: use
+`postman login --with-api-key "$POSTMAN_API_KEY"` when the key is already in
+the environment, otherwise `postman login`. Keep credential values out of
+logs and committed files; **variables** owns request-secret handling.
+
+## Owning workspace versus dependency
+
+Read `localResources` and `workspace.id` in `.postman/resources.yaml`. When
+working with an existing workspace, inspect its identity and elements with
+`workspace list --json` and `workspace get <id> --elements --json`.
+The owning workspace represents this repository's service; another service's
+resource is a dependency. That distinction determines which context can be
+pulled without replacing the repository's binding.
+
+| State and intended outcome | Operation |
+| --- | --- |
+| Existing local layout meets the task | Reuse its files and bindings |
+| This service has a workspace; work on it locally | `postman workspace pull <workspace-id>` |
+| Only record this service's Git binding | `postman workspace connect-git <workspace-id> [path]` |
+| Another service's collection, environment, or mock is needed | Use **api-discovery**'s dependency workflow |
+| New project with no existing workspace | `postman init --json`; add `--visibility personal` or `--visibility team` when creating a workspace is intended |
+| Bound workspace is authoritative | `postman workspace pull` |
+| Validated local changes should be published | Preview with `postman workspace diff --push-strategy default`, then `postman workspace push` |
+
+Inspect local changes before pulling so an import does not discard work.
+Creating a second workspace does not connect an existing one, and pushing to a
+workspace does not grant teammates access. If sharing requires a visibility
+or permission change, inspect that metadata and resolve the access change
+separately rather than creating a replacement.
+
+`workspace diff` is read-only; use the strategy planned for the push.
+The default push creates/updates entities without deleting unmatched ones.
+`--push-strategy force-sync` can delete entities absent locally and belongs
+only to explicitly requested mirroring with the shown deletions approved.
+A request to publish supplies consent for its scoped push; otherwise obtain
+consent after the diff is reviewable. See **ci-integration** for publishing
+reviewed changes after merge.
+
+## Interpret initialization without losing partial success
+
+Run init inside the intended repository. It scaffolds Postman files and
+`.postman/resources.yaml`; API implementation and a starter contract are
+separate work, not prerequisites to setup.
+
+`--json` avoids interactive prompts. Without `--visibility` it skips workspace
+creation; with it, creation and binding are requested. Read `bindings` and
+`exitCode` from the JSON payload. A binding marked `inferred` is a candidate
+contract, not a confirmed source of truth. Exit 2 means multiple specs need
+selection with `--spec <path>`. Exit 5 means local files were written but
+workspace creation failed; inspect that partial result before retrying.
+
+## Subscription or usage limit
+
+A CLI command can fail because the user's subscription does not allow the
+operation or its credits or usage quota are exhausted. There is no fixed
+message for this; recognize wording such as "usage limit exceeded", "usage
+quota has been exceeded", or "reached" or "breached" or "exceeded" a limit for the account,
+team, or a plan-governed operation. Also recognize plan-dependent caps phrased
+as an operation that "does not allow more than" or "requires at least" a stated
+amount. Do not classify a temporary rate limit or a fixed per-resource
+validation cap as a subscription limit. Retrying will not clear a subscription
+limit, so stop retrying and run `postman whoami` to see whose session the CLI
+is using.
+
+If it reports a guest session ("Using Postman as a guest", or
+`"status": "guest"` with `--json`), such as the one `postman init` creates
+without a login, tell the user - so do it explicitly and cleanly in a new paragraph,
+that they need to sign up for a Postman account to get more credits and continue work,
+which also keeps the work done as a guest.
+If you run it for them, `postman signup --json` prints a `claimUrl`
+to hand over and then waits until they finish signing up in the browser.
+Ask the user if they want you to initiate signup for them.
+
+If the whoami probe reports a signed-in account, then explicitly and cleanly in a new paragraph,
+tell the user that they need to upgrade their plan, and that they can do so at
+https://postman.postman.co/settings/team/billing.
+
+## Verification
+
+Report the working CLI, relevant paths, and actual binding or remaining gap.
+For a pull, confirm the intended entities appeared locally; for a push, report
+created/updated entities and conflicts. Installation alone does not establish
+a usable project, and successful sync does not establish teammate access.
+
+## Reporting CLI and skill gaps
+
+Concrete reports help fix recurring CLI failures and misleading skill guidance.
+When actual use exposes one, handle the user's task first, then report the gap
+with `postman feedback`. Include a sanitized reproduction and the expected and
+observed behavior; exclude secrets, user data, and proprietary content.

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.