feat: add 8 API lifecycle commands

Replace monolithic postman.md with focused, namespaced commands:
- setup: guided API key config and workspace verification
- sync: create/update collections from OpenAPI specs
- codegen: generate typed client code from collections
- search: discover APIs across private workspaces
- test: run collection tests and diagnose failures
- mock: create mock servers with auto-generated examples
- docs: analyze, improve, and publish API documentation
- security: OWASP API Top 10 security audit

Each command has proper frontmatter, error handling with actionable
next steps, and handles known MCP limitations (async polling, private
search, etc.).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

commands/docs.md

@@ -0,0 +1,88 @@
+---
+description: Generate, improve, and publish API documentation from Postman collections.
+allowed-tools: Read, Glob, Grep, mcp__postman__*
+---
+
+# API Documentation
+
+Analyze, improve, and publish API documentation from OpenAPI specs and Postman collections.
+
+## Prerequisites
+
+The Postman MCP Server must be connected for Postman operations. Local spec analysis works without MCP. If needed, tell the user: "Run `/postman:setup` to configure the Postman MCP Server."
+
+## Workflow
+
+### Step 1: Find the Source
+
+Call `getWorkspaces` to get the user's workspace ID. If multiple workspaces exist, ask which to use.
+
+Check for API definitions in this order:
+
+**Local specs:**
+- Search for `**/openapi.{json,yaml,yml}`, `**/swagger.{json,yaml,yml}`
+
+**Postman specs:**
+- Call `getAllSpecs` with the workspace ID to find specs in Postman
+- Call `getSpecDefinition` to pull the full spec
+
+**Postman collections:**
+- Call `getCollections` with the `workspace` parameter
+- Call `getCollection` for full detail
+
+### Step 2: Analyze Documentation Completeness
+
+Read the spec/collection and assess:
+
+```
+Documentation Coverage: 60%
+  Endpoints with descriptions:     8/15
+  Parameters with descriptions:    22/45
+  Endpoints with examples:         3/15
+  Error responses documented:      2/15
+  Authentication documented:       Yes
+  Rate limits documented:          No
+```
+
+### Step 3: Generate or Improve
+
+**Sparse spec:** Generate documentation for each endpoint:
+- Operation summary and description
+- Parameter table (name, type, required, description)
+- Request body schema with examples
+- Response schemas with examples for each status code
+- Error response documentation
+- Authentication requirements per endpoint
+
+**Partial spec:** Fill the gaps:
+- Add missing descriptions (infer from naming and schemas)
+- Generate realistic examples from schemas
+- Add error responses
+- Document authentication and rate limits
+
+### Step 4: Apply Changes
+
+Ask the user which output they want:
+
+1. **Update the spec file** - Write improved docs back into the OpenAPI spec
+2. **Update in Postman** - Use `updateCollectionRequest` to add descriptions and examples to each request
+3. **Publish public docs** - Call `publishDocumentation` with:
+   - `collectionId`: the collection's unique ID
+   - `customColor` and `customization` for branding
+   - Returns a public URL for the docs
+   - To unpublish later, call `unpublishDocumentation` with the collection ID
+4. **Generate markdown** - Create a `docs/api-reference.md` file for the project
+
+### Step 5: Sync Spec and Collection
+
+If both a spec and collection exist, keep them in sync:
+- Call `syncCollectionWithSpec` to update collection from spec. **Async (HTTP 202).** Poll `getCollectionUpdatesTasks` for completion. Only supports OpenAPI 3.0.
+- Or call `syncSpecWithCollection` to update spec from collection changes.
+
+## Error Handling
+
+- **MCP not configured:** Local markdown docs can be generated without MCP. For Postman publishing: "Run `/postman:setup` to configure the Postman MCP Server."
+- **401 Unauthorized:** "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys and run `/postman:setup`."
+- **Invalid spec:** Report parse errors and offer to fix common YAML/JSON syntax issues.
+- **Plan limitations:** "Publishing documentation may require a paid Postman plan. Check https://www.postman.com/pricing/"
+- **Too many results:** Ask the user to specify a collection by name.