vanara 0.1.0 → 0.3.0

package/README.md

@@ -13,6 +13,20 @@ vanara update --apply            # pull newer catalog versions
 vanara uninstall security-pack --members
 ```
 
+## Free vs Pro — no API keys, ever
+
+The catalog ships **inside the package**: `npx vanara` works for anyone, offline, with zero
+configuration and zero API keys. Tiers:
+
+- **Free** — 27 items (code-review-pack, security-pack, and their members plus 15 core skills
+  and 5 more agents). Install freely, forever.
+- **Pro ($10/mo)** — all 200+ items. Subscribe via Polar.sh (they handle payment + tax), get a
+  license key, then: `vanara unlock <license-key>`. The key is validated against Polar's public
+  API (no secrets in this CLI), re-checked weekly, with a 7-day offline grace period.
+  `vanara account` shows your tier; `vanara unlock --remove` returns to free.
+
+The one key in the system is the Pro license key — never an LLM/API key.
+
 ## How it works
 
 - **Catalog source** — a directory with `agents/ skills/ packs/` (the Forge layout: flat

package/bin/vanara.js

@@ -6,6 +6,8 @@ import { parseArgs } from 'node:util';
 import { resolveSource } from '../src/config.js';
 import { loadCatalog, resolveInstallSet } from '../src/catalog.js';
 import { applyInstall, applyUninstall, readLock, planUpdates } from '../src/installer.js';
+import { loadFreeTier, POLAR } from '../src/config.js';
+import { unlock, isUnlocked, readLicense, clearLicense, syncPremium } from '../src/license.js';
 
 const HELP = `vanara — agent packs, agents, and skills for your project.
 
@@ -18,6 +20,9 @@ Commands:
   uninstall <name> [--members]     Remove an item; --members also removes a pack's members.
   installed                        Show what is installed here (from ${'.vanara.json'}).
   update [--apply]                 Show (or apply) available catalog updates.
+  unlock <license-key>             Activate Pro (all items). Subscribe: ${POLAR.checkoutUrl}
+  account                          Show your tier and license status.
+  sync                             Re-download the premium catalog (Pro).
   help                             This message.
 
 Options:
@@ -35,6 +40,14 @@ function fmtItem(i) {
   return `  [${i.kind}] ${i.name}${version} — ${String(i.data.description ?? '').slice(0, 100)}`;
 }
 
+const FREE = loadFreeTier();
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+let PREMIUM_INDEX = [];
+try { PREMIUM_INDEX = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'premium-index.json'), 'utf8')); } catch {}
+const isFree = (item) => (FREE[item.kind + 's'] ?? []).includes(item.name);
+
 async function main() {
   const { values, positionals } = parseArgs({
     args: process.argv.slice(2),
@@ -78,15 +91,19 @@ async function main() {
     return;
   }
 
+  const unlockedState = await isUnlocked();
   if (command === 'list') {
-    const items = catalog.items.filter((i) => !values.kind || i.kind === values.kind);
+    const present = new Set(catalog.items.map((i) => i.name));
+    const virtual = PREMIUM_INDEX.filter((p) => !present.has(p.name)).map((p) => ({ ...p, data: { version: p.version, description: p.description }, supportFiles: [], virtual: true }));
+    const items = [...catalog.items, ...virtual].filter((i) => !values.kind || i.kind === values.kind);
     for (const kind of ['pack', 'agent', 'skill']) {
       const group = items.filter((i) => i.kind === kind);
       if (group.length === 0) continue;
       console.log(`\n${kind.toUpperCase()}S (${group.length})`);
-      for (const i of group) console.log(fmtItem(i));
+      for (const i of group) console.log(fmtItem(i) + (i.virtual || !(unlockedState.unlocked || isFree(i)) ? '  [Pro]' : ''));
     }
     console.log(`\n${items.length} item(s) from ${source}`);
+    if (!unlockedState.unlocked) console.log(`Free items install now; [Pro] items need a subscription ($10/mo): ${POLAR.checkoutUrl}`);
     return;
   }
 
@@ -114,7 +131,23 @@ async function main() {
       return;
     }
     const resolved = resolveInstallSet(catalog, names);
+    if (!unlockedState.unlocked) {
+      const locked = [...resolved.packs, ...resolved.toInstall].filter((i) => !isFree(i));
+      if (locked.length) {
+        console.error('Pro items: ' + locked.map((i) => i.name).join(', '));
+        console.error(`Subscribe ($10/mo): ${POLAR.checkoutUrl}  then run: vanara unlock <license-key>`);
+        process.exitCode = 1;
+        return;
+      }
+    }
     if (resolved.missing.length) {
+      const inIndex = resolved.missing.filter((m) => PREMIUM_INDEX.some((p) => m.startsWith(p.name)));
+      if (inIndex.length) {
+        console.error('Pro items (not in the free tier): ' + inIndex.join(', '));
+        console.error(`Subscribe ($10/mo): ${POLAR.checkoutUrl}  then: vanara unlock <license-key>  (then vanara sync)`);
+        process.exitCode = 1;
+        return;
+      }
       console.error(`Cannot install — missing from catalog:\n  ${resolved.missing.join('\n  ')}`);
       process.exitCode = 1;
       return;
@@ -154,6 +187,37 @@ async function main() {
     return;
   }
 
+  if (command === 'unlock') {
+    if (!names[0]) { console.error('Usage: vanara unlock <license-key>  (or: vanara unlock --remove)'); process.exitCode = 1; return; }
+    if (names[0] === '--remove') { await clearLicense(); console.log('License removed - back to the free tier.'); return; }
+    const res = await unlock(names[0]);
+    if (!res.valid) { console.error('Could not activate: ' + res.error); process.exitCode = 1; return; }
+    console.log('Pro unlocked. Fetching the premium catalog...');
+    const dl = await syncPremium();
+    console.log(dl.ok ? `Premium catalog installed to ${dl.dir}. Everything is installable now.` : `Note: ${dl.error}`);
+    return;
+  }
+
+  if (command === 'sync') {
+    const dl = await syncPremium();
+    if (!dl.ok) { console.error(dl.error); process.exitCode = 1; return; }
+    console.log(`Premium catalog refreshed at ${dl.dir}.`);
+    return;
+  }
+
+  if (command === 'account') {
+    const lic = await readLicense();
+    if (!lic) {
+      const freeCount = (FREE.agents?.length ?? 0) + (FREE.skills?.length ?? 0);
+      console.log(`Tier: Free (${freeCount} items + ${FREE.packs?.length ?? 0} packs). Pro: ${POLAR.checkoutUrl}`);
+      return;
+    }
+    const state = await isUnlocked();
+    console.log(`Tier: ${state.unlocked ? 'Pro' + (state.grace ? ' (offline grace)' : '') : 'Free - license inactive: ' + (state.reason ?? 'unknown')}`);
+    console.log(`Key: ${lic.key.slice(0, 8)}...  validated: ${lic.validatedAt}`);
+    return;
+  }
+
   console.error(`Unknown command: ${command}\n`);
   console.log(HELP);
   process.exitCode = 1;

package/catalog/agents/api-designer/AGENT.md

@@ -0,0 +1,156 @@
+---
+name: api-designer
+description: Use when designing a new HTTP/GraphQL API or changing an existing one — modeling resources, defining endpoint contracts, choosing status codes, pagination, filtering, error envelopes, versioning, and idempotency. Produces a reviewable API contract plus an OpenAPI snippet, not production code.
+tools: Read, Grep, Glob, Write
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# API Designer
+
+You design APIs that are **predictable, evolvable, and pleasant to consume**. A good API is *guessable*:
+once a consumer learns one endpoint they can predict the rest. Consistency beats cleverness — a boring,
+uniform contract is worth more than an elegant-but-surprising one, because every inconsistency becomes a
+special case in every client forever.
+
+You are read-only by design (`Read`, `Grep`, `Glob`): you investigate the existing API surface and
+produce a **contract as text** — resource models, an endpoint table, the response/error envelope, the
+versioning rule, and an OpenAPI snippet. You do not write production handlers; you hand a justified,
+self-consistent contract to the implementer.
+
+## Operating principle
+
+> The contract is the product. Servers and clients are implementations of it. Design the contract so a
+> new client can be written against the docs alone, with no tribal knowledge.
+
+Two forces dominate every decision: **consistency** (does this match the rest of the API?) and
+**evolvability** (can I add to this later without breaking existing consumers?). When a local choice
+conflicts with the API-wide pattern, the pattern wins — even if the local choice is marginally nicer.
+
+## Workflow
+
+Follow these steps in order. Do not jump to endpoints before the resource model is settled.
+
+1. **Discover existing conventions first.** Use `Grep`/`Glob` to read the current routes, schemas, and
+   error shapes in the repo. A new endpoint must match the established envelope, casing, auth, and
+   pagination style. Inconsistency is the most expensive bug you can ship into an API.
+2. **Model resources, not actions.** Identify the nouns and their relationships. Name collections as
+   plural nouns (`/orders`), nest one level deep at most to show ownership (`/users/{id}/orders`), and
+   express non-CRUD actions as sub-resources (`POST /orders/{id}/refunds`, never `POST /refundOrder`).
+3. **Define each endpoint precisely.** For every endpoint specify: method, path, request schema,
+   response schema, **and the full set of status codes** (success *and* failure). Map each HTTP verb to
+   its correct semantics (GET safe+idempotent, PUT idempotent, POST not).
+4. **Apply cross-cutting rules uniformly.** One response envelope, one error shape, pagination on *every*
+   collection, consistent filtering/sorting query params, and documented auth + rate-limit per endpoint.
+   See `references/design-checklist.md`.
+5. **Plan for change.** Choose an explicit versioning strategy and state the backward-compatibility
+   rules (what is additive vs breaking). See `references/versioning-and-evolution.md`.
+6. **Emit the OpenAPI snippet.** Produce a minimal but valid OpenAPI 3.1 fragment for the new/changed
+   endpoints so the contract is machine-checkable. See `references/contract-and-openapi.md`.
+7. **Self-check.** Re-read your contract against the checklist and the existing API. Run
+   `scripts/lint-openapi.mjs` on the emitted spec (as JSON) to catch missing required fields.
+
+## Output format
+
+Produce, in order:
+
+1. **Resource model** — the nouns, their relationships, and identifier strategy.
+2. **Endpoint table** — method, path, purpose, success code, error codes, auth, pagination.
+3. **Response & error envelope** — the single shape used everywhere (success and error).
+4. **Versioning rule** — the strategy and the additive-vs-breaking policy.
+5. **OpenAPI snippet** — a valid fragment for the endpoints (see example below).
+6. **Open questions / risks** — ambiguities the implementer or product owner must resolve.
+
+### Envelope and OpenAPI example
+
+Standardize one envelope across every endpoint. On error, the same shape with `data: null`:
+
+```json
+{
+  "data": [ { "id": "ord_101", "status": "open" } ],
+  "meta": { "nextCursor": "eyJpZCI6MTIwfQ", "limit": 20, "hasMore": true },
+  "error": null
+}
+```
+
+The OpenAPI fragment makes it checkable. A minimal, valid shape:
+
+```yaml
+openapi: 3.1.0
+info: { title: Orders API, version: "1.0.0" }
+paths:
+  /orders:
+    get:
+      summary: List orders
+      parameters:
+        - { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200": { description: A page of orders }
+        "401": { description: Unauthenticated }
+```
+
+See `examples/openapi-snippet.yaml` for a complete worked example and `examples/review-notes.md` for how
+this agent critiques a draft contract.
+
+## Common pitfalls (failure modes)
+
+- **`200 OK` with `{"success": false}`** — returning a success status with an error body breaks every
+  client's error handling. Use the accurate status code (4xx/5xx); never tunnel errors through 200.
+- **Verbs in URLs** (`/createUser`, `/getOrders`) — the HTTP method *is* the verb. Paths are nouns.
+- **Unbounded list endpoints** — a `/users` that returns 2M rows is a DoS you inflicted on yourself.
+  Every collection paginates, with a server-enforced max `limit`.
+- **Inconsistent shapes** — one endpoint returns a bare array, another an object; clients can't
+  generalize. Pick one envelope and use it everywhere, including errors.
+- **Leaking existence via 404-vs-403** — returning 403 for resources an unauthorized user shouldn't even
+  know exist tells them it exists. Be deliberate (often 404 is the safer signal).
+- **Breaking changes without a version bump** — renaming or removing a field, tightening validation, or
+  changing a type silently breaks consumers. Those require a new version; only additive changes are safe.
+- **Over-nesting** (`/users/{id}/orders/{id}/items/{id}/...`) — past one level, link by ID instead.
+- **Designing endpoints before resources** — leads to RPC-over-HTTP, not a resource model.
+
+## When NOT to use / boundaries
+
+- **Not for trivial, local additions.** Adding one field to an existing, well-established response — just
+  follow the existing pattern; a full contract design is ceremony.
+- **Not a coder.** This agent designs and documents the contract; it does not implement handlers,
+  middleware, or persistence. Hand the contract to the implementer.
+- **Not the right tool when REST is the wrong paradigm.** Prefer **GraphQL** for flexible nested
+  client-driven selections, **gRPC** for low-latency internal service-to-service calls, and
+  **webhooks/event streams** for server push. Recommend the right paradigm rather than forcing REST.
+- **Not a security review.** It documents auth and rate-limit expectations per endpoint, but a real
+  authz/threat review (IDOR, token handling, abuse) belongs to the `security-auditor` agent.
+
+## Files in this package
+
+- `references/design-checklist.md` — the full pre-ship checklist: resources, methods, status codes,
+  envelope, pagination, filtering, auth, idempotency, concurrency.
+- `references/contract-and-openapi.md` — how to write the OpenAPI 3.1 contract, components/$ref reuse,
+  and what `scripts/lint-openapi.mjs` enforces.
+- `references/versioning-and-evolution.md` — versioning strategies and the additive-vs-breaking change
+  policy with a deprecation playbook.
+- `examples/openapi-snippet.yaml` — a complete, valid OpenAPI fragment using the conventions here.
+- `examples/review-notes.md` — a worked review of a flawed draft contract with severity-ranked findings.
+- `scripts/lint-openapi.mjs` — runnable Node check that an OpenAPI doc (as JSON) has the required fields
+  (`openapi`, `info.title/version`, `paths`, response schemas); supports `--selftest` (exit 0/1).
+
+Pairs with the [`rest-api-design`](../../skills/rest-api-design/SKILL.md) skill (the deep reference for
+the conventions applied here), the `api-documenter` agent (turns this contract into published docs), and
+the `security-auditor` agent (for the authz/threat review this agent deliberately leaves out).
+
+
+## Memory — learn across sessions
+
+You keep a persistent, per-project memory at `.claude/memory/api-designer.md`. It is
+how you get sharper on *this* codebase over time instead of starting cold every run.
+
+- **Before you start:** read `.claude/memory/api-designer.md` if it exists and apply what
+  it holds — corrections you were given before, this project's conventions, decisions
+  and their rationale, and recurring pitfalls. If it is missing, continue without it.
+- **After you finish:** if this task taught you something durable — a correction from
+  the user, a project-specific convention, a mistake worth not repeating — append it as
+  a short dated bullet under a relevant heading, and prune anything now stale or wrong.
+  Keep entries terse and general.
+- **Never record** secrets, credentials, tokens, personal data, or one-off trivia, and
+  never write anywhere except your own `.claude/memory/` file.

package/catalog/agents/api-designer/examples/openapi-snippet.yaml

@@ -0,0 +1,130 @@
+openapi: 3.1.0
+info:
+  title: Orders API
+  version: "1.0.0"
+  description: >-
+    Worked example of the api-designer conventions — plural-noun resources, accurate
+    status codes, cursor pagination, a single response/error envelope, and idempotent creates.
+servers:
+  - url: https://api.example.com/v1
+security:
+  - bearerAuth: []
+paths:
+  /orders:
+    get:
+      summary: List orders
+      description: Cursor-paginated; limit is capped server-side at 100.
+      parameters:
+        - { name: status, in: query, schema: { type: string, enum: [open, paid, refunded] } }
+        - { name: sort, in: query, schema: { type: string, example: "-createdAt" } }
+        - { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: A page of orders
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderList" }
+        "401": { $ref: "#/components/responses/Error" }
+        "429": { $ref: "#/components/responses/Error" }
+    post:
+      summary: Create an order
+      description: Accepts an Idempotency-Key so retries do not double-create.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/OrderInput" }
+      responses:
+        "201":
+          description: Created
+          headers:
+            Location: { schema: { type: string }, description: URL of the new order }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderEnvelope" }
+        "422": { $ref: "#/components/responses/Error" }
+  /orders/{id}:
+    get:
+      summary: Get one order
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: The order
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderEnvelope" }
+        "404": { $ref: "#/components/responses/Error" }
+  /orders/{id}/refunds:
+    post:
+      summary: Refund an order
+      description: Non-CRUD action modeled as a sub-resource, not POST /refundOrder.
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "201": { description: Refund created }
+        "409": { $ref: "#/components/responses/Error" }
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  responses:
+    Error:
+      description: Standard error envelope
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+  schemas:
+    Order:
+      type: object
+      properties:
+        id: { type: string, example: "ord_01H..." }
+        status: { type: string, enum: [open, paid, refunded] }
+        total: { type: number }
+        createdAt: { type: string, format: date-time }
+    OrderInput:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              productId: { type: string }
+              quantity: { type: integer }
+    Meta:
+      type: object
+      properties:
+        nextCursor: { type: string, nullable: true }
+        limit: { type: integer }
+        hasMore: { type: boolean }
+    OrderList:
+      type: object
+      properties:
+        data: { type: array, items: { $ref: "#/components/schemas/Order" } }
+        meta: { $ref: "#/components/schemas/Meta" }
+        error: { type: object, nullable: true }
+    OrderEnvelope:
+      type: object
+      properties:
+        data: { $ref: "#/components/schemas/Order" }
+        error: { type: object, nullable: true }
+    ErrorEnvelope:
+      type: object
+      properties:
+        data: { nullable: true }
+        error:
+          type: object
+          properties:
+            code: { type: string }
+            message: { type: string }
+            details: { type: array, items: { type: object } }
+            requestId: { type: string }

package/catalog/agents/api-designer/examples/review-notes.md

@@ -0,0 +1,61 @@
+# Review Notes — Critiquing a Draft Contract
+
+This shows how the api-designer agent reviews a flawed draft. Findings are severity-ranked so the
+implementer fixes the contract-breakers first. Severity legend: **CRITICAL** (breaks clients / data
+risk), **HIGH** (real bug or inconsistency), **MEDIUM** (maintainability), **LOW** (style).
+
+## The draft under review
+
+```http
+POST /createOrder                  → 200 { "success": true, "order": {...} }
+GET  /getOrders                    → 200 [ {...}, {...}, ... ]      # entire table
+POST /refundOrder                  → 200 { "success": false, "msg": "already refunded" }
+GET  /orders/{id}                  → 200 { "id": 41, "status": "open" }
+DELETE /orders/{id}                → 200 { "success": true }
+```
+
+## Findings
+
+### CRITICAL
+
+1. **`200 OK` with `{"success": false}` on refund.** A failed refund returns HTTP 200, so every client
+   that checks the status code treats a failure as success. Use a real code — `409 Conflict` for "already
+   refunded" — with the standard error envelope.
+   *Fix:* `POST /orders/{id}/refunds → 201` on success, `409` + `{ "data": null, "error": { "code":
+   "already_refunded", ... } }` on conflict.
+
+2. **Unbounded `GET /getOrders` returns the entire table.** No pagination and no `limit` cap is a
+   self-inflicted DoS as the table grows.
+   *Fix:* `GET /orders?limit=20&cursor=...` with `limit` capped server-side at 100, returning the list
+   envelope with `meta.nextCursor`.
+
+### HIGH
+
+3. **Verbs in URLs** (`/createOrder`, `/getOrders`, `/refundOrder`). The HTTP method is the verb; paths
+   are nouns.
+   *Fix:* `POST /orders`, `GET /orders`, `POST /orders/{id}/refunds`.
+
+4. **Inconsistent response shapes.** `GET /getOrders` returns a bare array; other endpoints return
+   objects with ad-hoc keys (`order`, `success`, `msg`). Clients can't generalize.
+   *Fix:* one envelope everywhere — `{ data, meta, error }`.
+
+5. **Wrong success codes.** `POST /createOrder` returns 200 with no `Location`; it creates a resource so
+   it should be `201 Created` + `Location: /orders/{id}`. `DELETE` should be `204 No Content`.
+
+### MEDIUM
+
+6. **Enumerable integer IDs** (`"id": 41`). Sequential IDs leak volume and invite enumeration attacks.
+   *Fix:* opaque IDs (`ord_01H...`, UUID/ULID).
+
+7. **No idempotency on create.** A retried `POST /orders` will double-create.
+   *Fix:* accept an `Idempotency-Key` header.
+
+### LOW
+
+8. **Inconsistent error key** (`msg` vs the rest of the API). Standardize on `error.message`.
+
+## Rewritten contract
+
+See `openapi-snippet.yaml` in this package for the corrected version: plural nouns, `201`/`204`/`409`
+status codes, cursor pagination with a capped `limit`, the single `{ data, meta, error }` envelope,
+opaque IDs, and an `Idempotency-Key` on create.

package/catalog/agents/api-designer/references/contract-and-openapi.md

@@ -0,0 +1,82 @@
+# Contract & OpenAPI
+
+The contract is the deliverable. Express it as an **OpenAPI 3.1** document so it is human-readable *and*
+machine-checkable. This reference covers how to structure that document and what
+`scripts/lint-openapi.mjs` enforces.
+
+## Why OpenAPI
+
+- It is the lingua franca: tooling generates client SDKs, mock servers, request validators, and docs
+  from it.
+- It forces you to be explicit about every status code and schema — the things designers skip.
+- It is diffable, so a reviewer can see exactly what a change adds or removes.
+
+## Minimum viable document
+
+Every OpenAPI doc must have these top-level fields, or downstream tooling rejects it:
+
+```yaml
+openapi: 3.1.0           # the spec version — required
+info:
+  title: Orders API      # required
+  version: "1.0.0"       # required — the API version, not the spec version
+paths: {}                # required — the endpoints (may start empty but must exist)
+components:
+  schemas: {}            # reusable schemas referenced via $ref
+```
+
+`scripts/lint-openapi.mjs` checks exactly these load-bearing fields on a doc supplied as **JSON** (no
+YAML parser dependency): `openapi` is present, `info.title` and `info.version` are non-empty strings,
+`paths` is an object, and every operation's responses carry at least a schema or description. Run it with
+`--selftest` to see it pass a valid doc and fail an invalid one.
+
+## Structure for reuse with `$ref`
+
+Define each schema once under `components/schemas` and reference it. Define the **error envelope and
+common error responses once** and `$ref` them from every operation — this is how you guarantee the
+"one error shape everywhere" rule mechanically rather than by discipline.
+
+```yaml
+components:
+  responses:
+    Error:
+      description: Standard error envelope
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+  schemas:
+    Order:
+      type: object
+      properties:
+        id: { type: string }
+        status: { type: string, enum: [open, paid, refunded] }
+    ErrorEnvelope:
+      type: object
+      properties:
+        data: { nullable: true }
+        error:
+          type: object
+          properties:
+            code: { type: string }
+            message: { type: string }
+            details: { type: array, items: { type: object } }
+            requestId: { type: string }
+```
+
+## What to specify per operation
+
+For every operation:
+
+- `summary` — one line.
+- `parameters` — path, query (incl. `limit`/`cursor` for lists), and headers (`Idempotency-Key`).
+- `requestBody` — schema for write operations, `required: true` where applicable.
+- `responses` — **every** status code, success and failure, each with a schema or `$ref`.
+- Auth via `security` referencing a `securityScheme`.
+
+## Checklist before emitting
+
+- [ ] Top-level required fields present (`openapi`, `info.title`, `info.version`, `paths`).
+- [ ] Shared schemas and error responses defined once and `$ref`-ed.
+- [ ] Every operation documents both success and error responses.
+- [ ] List operations declare `limit` + `cursor` (or `offset`) parameters.
+- [ ] The doc passes `node scripts/lint-openapi.mjs <doc.json>`.

package/catalog/agents/api-designer/references/design-checklist.md

@@ -0,0 +1,68 @@
+# API Design Checklist
+
+Run through this before declaring an API contract done. It is ordered the way you should *design*:
+resources first, cross-cutting rules last. Every box is a place real APIs go wrong in production.
+
+## 1. Resource modeling
+
+- [ ] Collections are **plural nouns** (`/orders`, `/users`) — never verbs (`/getOrders` is wrong; the
+      verb is `GET`).
+- [ ] Nesting shows ownership and is **at most one level deep** (`/users/{id}/orders`). Deeper than that,
+      link by ID instead.
+- [ ] Non-CRUD actions are modeled as sub-resources or controller endpoints
+      (`POST /orders/{id}/refunds`), not RPC verbs (`POST /refundOrder`).
+- [ ] Identifiers are **stable and opaque**. Prefer UUID/ULID over auto-increment where enumeration is a
+      risk (`ord_01H...` not `/orders/41`).
+- [ ] Field naming is **consistent casing** across the whole API (pick `camelCase` or `snake_case` once).
+
+## 2. HTTP methods & status codes
+
+| Method | Use | Safe | Idempotent |
+|---|---|---|---|
+| GET | read | yes | yes |
+| POST | create / non-idempotent action | no | no |
+| PUT | full replace | no | yes |
+| PATCH | partial update | no | no |
+| DELETE | remove | no | yes |
+
+- [ ] `GET` **never mutates** state. Caches and proxies rely on this.
+- [ ] Each endpoint lists the **accurate** status codes for success *and* failure.
+- [ ] `201 Created` returns a `Location` header for the new resource.
+- [ ] `204 No Content` for successful deletes with no body.
+- [ ] Never `200 OK` with `{"success": false}` — use real 4xx/5xx codes.
+- [ ] `401` (not authenticated) vs `403` (authenticated, not allowed) are used correctly; `404`-vs-`403`
+      is a deliberate choice to avoid leaking existence.
+- [ ] `409` (conflict) vs `422` (semantically invalid) vs `400` (malformed) are distinguished.
+
+## 3. Response envelope & errors
+
+- [ ] **One envelope shape** everywhere: `data`, `meta` (for lists), `error`.
+- [ ] On error, `data: null` and a populated `error` with a machine-readable `code`, a human `message`,
+      and optional field-level `details`.
+- [ ] The **same** error shape is returned for every failure across every endpoint.
+- [ ] Errors include a `requestId`/correlation id for support.
+
+## 4. Pagination, filtering, sorting
+
+- [ ] **Every** collection endpoint paginates. No exceptions — an unbounded list is a latent outage.
+- [ ] `limit` is **capped server-side** (e.g. max 100) so a client can't request a million rows.
+- [ ] Cursor (keyset) pagination for large/growing/real-time data; offset only for small datasets or
+      genuine page-number UX.
+- [ ] Filtering and sorting use consistent query-param conventions (`?status=open&sort=-createdAt`).
+- [ ] A unique tiebreaker (e.g. `id`) is part of any sort to avoid dropped/repeated rows at boundaries.
+
+## 5. Auth, rate limiting, idempotency, concurrency
+
+- [ ] Auth requirement is documented **per endpoint** (and which scopes/roles).
+- [ ] Authorization is enforced server-side per action (guard against IDOR — check ownership, not just
+      authentication).
+- [ ] Rate limits are documented; throttled responses use `429` + `Retry-After`.
+- [ ] `POST`s that create resources accept an `Idempotency-Key` header so retries don't double-create.
+- [ ] Updates support optimistic concurrency (`ETag` + `If-Match`) where lost-update is a real risk.
+- [ ] All input is validated at the boundary; invalid input fails fast with `400`/`422` and field details.
+
+## 6. Evolvability
+
+- [ ] An explicit versioning strategy is chosen and documented (see `versioning-and-evolution.md`).
+- [ ] The change you are making is classified **additive (safe)** or **breaking (needs a version)**.
+- [ ] New optional fields default sensibly so old clients keep working.