@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/api-connector-builder/references/auth-flows.md

@@ -0,0 +1,132 @@
+# Auth flows — per-flow walkthroughs
+
+OAuth 2.1 baseline (oauth.net/2.1, accessed 2026-06-02):
+
+- **PKCE is mandatory** for every authorization-code client, public and
+  confidential alike.
+- **Implicit grant and Resource-Owner-Password grant are removed.** If a vendor's
+  docs still show them, do not use them — pick Auth-Code + PKCE or Client
+  Credentials instead.
+- **Bearer tokens must not travel in query strings.** Header only. Query strings
+  leak into access logs, browser history, and `Referer` headers.
+
+## API key in header
+
+Simplest scheme. The vendor issues a static key; you send it on every request.
+Store it in env, never source. There is no refresh — rotate manually when it
+leaks or on a schedule.
+
+```python
+import os, httpx
+KEY = os.environ["VENDOR_API_KEY"]
+client = httpx.Client(base_url="https://api.vendor.com/v1",
+                      headers={"X-API-Key": KEY})  # header name per vendor docs
+```
+
+Some vendors want `Authorization: Bearer <key>` instead of a custom header — read
+the docs; do not guess the header name.
+
+## Bearer static token (personal access token)
+
+Treat exactly like an API key: long-lived, env-stored, no refresh. The only
+difference is the standard `Authorization: Bearer <token>` header.
+
+```typescript
+const TOKEN = process.env.VENDOR_PAT!;
+const headers = { Authorization: `Bearer ${TOKEN}` };
+```
+
+## OAuth2 Client Credentials (machine-to-machine)
+
+No end user is involved — your service authenticates as itself. You hold a
+`client_id` + `client_secret`, exchange them for a short-lived access token at the
+token endpoint, cache it until it expires, and re-mint on expiry or a 401.
+
+```python
+import os, time, httpx
+
+_cache = {"token": None, "exp": 0.0}
+
+def access_token():
+    if _cache["token"] and time.time() < _cache["exp"] - 30:  # 30s safety margin
+        return _cache["token"]
+    r = httpx.post("https://auth.vendor.com/oauth/token", data={
+        "grant_type": "client_credentials",
+        "client_id": os.environ["VENDOR_CLIENT_ID"],
+        "client_secret": os.environ["VENDOR_CLIENT_SECRET"],
+        "scope": "read:items",
+    }, timeout=10.0)
+    r.raise_for_status()
+    body = r.json()
+    _cache.update(token=body["access_token"], exp=time.time() + body["expires_in"])
+    return _cache["token"]
+```
+
+## OAuth2 Authorization Code + PKCE (acting for a user)
+
+The user-facing flow. PKCE prevents an intercepted authorization code from being
+redeemed by an attacker.
+
+1. Generate a `code_verifier` (43–128 chars, random) and its
+   `code_challenge = base64url(sha256(verifier))`.
+2. Redirect the user to the authorize endpoint with
+   `response_type=code`, `code_challenge`, `code_challenge_method=S256`,
+   `redirect_uri`, `scope`, and a random `state`.
+3. On callback, verify `state`, then POST `grant_type=authorization_code` with
+   the `code` **and the original `code_verifier`** to the token endpoint.
+4. Store the resulting refresh token securely; use the access token for calls.
+
+```python
+import base64, hashlib, os
+verifier = base64.urlsafe_b64encode(os.urandom(64)).rstrip(b"=").decode()
+challenge = base64.urlsafe_b64encode(
+    hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+# -> send `challenge` (S256) on /authorize, keep `verifier` for the token exchange
+```
+
+### Refresh-token rotation (RFC 9700 / OAuth 2.0 Security BCP)
+
+Refresh tokens for public clients must be **sender-constrained or one-time-use**:
+every refresh returns a *new* refresh token and invalidates the old one. If the
+old token is ever replayed, the server detects the reuse and revokes the whole
+chain (a sign of theft). Persist the latest refresh token atomically — a crash
+between "got new token" and "saved it" locks you out.
+
+```python
+def refresh(refresh_token: str) -> dict:
+    r = httpx.post("https://auth.vendor.com/oauth/token", data={
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": os.environ["VENDOR_CLIENT_ID"],
+    }, timeout=10.0)
+    r.raise_for_status()
+    body = r.json()
+    save_refresh_token(body["refresh_token"])  # ROTATE: store the new one, drop old
+    return body
+```
+
+Keep access tokens short-lived (minutes). Never log a raw token — log a partial
+(`tok…3f9c`) or a hash if you must correlate across services.
+
+## Device flow (input-constrained devices)
+
+For CLIs, TVs, and devices with no browser. Request a device + user code, show the
+user a URL and code to enter on another device, then **poll** the token endpoint
+until they approve (respect the `interval`; back off on `slow_down`). Once
+granted, you receive access + refresh tokens and rotate them exactly like the
+auth-code flow above.
+
+## DPoP (sender-constraining, brief)
+
+DPoP (Demonstrating Proof-of-Possession) binds a token to a client-held key: each
+request carries a signed `DPoP` header proving you hold the private key, so a
+stolen bearer token alone is useless. If a vendor offers DPoP-bound access tokens,
+prefer them for high-value scopes — it is the practical way to satisfy the
+"sender-constrained" requirement without mTLS infrastructure.
+
+## Storage rules (all flows)
+
+- Secrets in env vars or a secret manager — never in source, never in
+  `localStorage` (XSS-readable) for anything long-lived.
+- One credential set per vendor per environment; never share a prod key into dev.
+- Rotate on any suspected leak; the flows above make rotation cheap by design.

package/skills/shared/api-connector-builder/references/pagination.md

@@ -0,0 +1,144 @@
+# Pagination — full code per style
+
+The universal rule: **loop until the API signals no next page.** Never a fixed
+page count. Expose results as a generator / async-iterator so callers stream
+instead of buffering the whole set in memory.
+
+(graphql.org/learn/pagination + REST pagination pattern guides, accessed
+2026-06-02.)
+
+## Offset / page number
+
+Simple, but it **drifts** when rows are inserted or deleted mid-walk (you skip or
+double-read) and gets **slow at large offsets** (the server scans and discards).
+Prefer cursor/keyset when the API offers it.
+
+```python
+def iter_offset(client, path, page_size=100):
+    offset = 0
+    while True:
+        body = client.get(path, params={"offset": offset, "limit": page_size}).json()
+        rows = body["data"]
+        if not rows:                  # empty page = exhausted
+            return
+        yield from rows
+        offset += len(rows)
+```
+
+```typescript
+export async function* iterOffset(get: (q: Record<string, number>) => Promise<any>, pageSize = 100) {
+  let offset = 0;
+  for (;;) {
+    const body = await get({ offset, limit: pageSize });
+    const rows = body.data as unknown[];
+    if (rows.length === 0) return;     // exhausted
+    yield* rows;
+    offset += rows.length;
+  }
+}
+```
+
+## Cursor / keyset
+
+The server returns an opaque cursor for the next page; you pass it back. **Stable
+under concurrent writes and fixed cost regardless of depth** — the strategy to
+prefer.
+
+```python
+def iter_cursor(client, path, page_size=100):
+    cursor = None
+    while True:
+        body = client.get(path, params={"cursor": cursor, "limit": page_size}).json()
+        yield from body["data"]
+        cursor = body.get("next_cursor")
+        if not cursor:                # cursor exhausted
+            return
+```
+
+## Link header (REST)
+
+The next page lives in the `Link` response header with `rel="next"`. Follow it
+until the header has no `next`.
+
+```python
+import re
+
+def iter_link(client, url):
+    while url:
+        resp = client.get(url)
+        yield from resp.json()
+        link = resp.headers.get("Link", "")
+        m = re.search(r'<([^>]+)>;\s*rel="next"', link)
+        url = m.group(1) if m else None   # no rel="next" = exhausted
+```
+
+```typescript
+function nextLink(header: string | null): string | null {
+  if (!header) return null;
+  const m = header.match(/<([^>]+)>;\s*rel="next"/);
+  return m ? m[1] : null;
+}
+
+export async function* iterLink(start: string, get: (u: string) => Promise<Response>) {
+  let url: string | null = start;
+  while (url) {
+    const res = await get(url);
+    yield* (await res.json()) as unknown[];
+    url = nextLink(res.headers.get("Link"));
+  }
+}
+```
+
+## GraphQL — Relay Cursor Connections
+
+The Relay spec returns `edges` (each with a `node` and `cursor`) and a `pageInfo`
+with `endCursor` and `hasNextPage`. Pass `endCursor` as the `after` argument of
+the next query and stop when `hasNextPage` is false.
+
+```python
+QUERY = """
+query($after: String) {
+  issues(first: 100, after: $after) {
+    edges { node { id title } }
+    pageInfo { endCursor hasNextPage }
+  }
+}
+"""
+
+def iter_relay(client, url):
+    after = None
+    while True:
+        body = client.post(url, json={"query": QUERY, "variables": {"after": after}}).json()
+        conn = body["data"]["issues"]
+        for edge in conn["edges"]:
+            yield edge["node"]
+        info = conn["pageInfo"]
+        if not info["hasNextPage"]:   # exhausted
+            return
+        after = info["endCursor"]
+```
+
+## Dedup on overlap
+
+With offset pagination under concurrent inserts, the same row can appear on two
+pages. If exactness matters, track seen ids and skip duplicates:
+
+```python
+def dedup(records, key="id"):
+    seen = set()
+    for r in records:
+        k = r[key]
+        if k in seen:
+            continue
+        seen.add(k)
+        yield r
+```
+
+Cursor/keyset pagination does not have this problem for stable sort keys — another
+reason to prefer it.
+
+## Combine with retries + rate limits
+
+Each `client.get(...)` above should go through the retry + rate-limit wrapper from
+`SKILL.md` (transient-only retry with jittered backoff, `Retry-After` honored).
+Pagination is the loop; the per-request call inside it is where resilience lives.

package/skills/shared/api-connector-builder/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+#
+# verify.sh — connector-module structure/banlist linter for `api-connector-builder`.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Lints the connector source the skill produces against the four-pillar shape:
+#   secrets, retries, pagination, timeouts. It checks the artifact's STRUCTURE,
+#   not its runtime behavior — appropriate for a connector emitted into an
+#   arbitrary target repo. It never false-fails: a repo with no connector-like
+#   source is simply skipped.
+#
+#   A connector file = a .py / .ts / .js / .mjs / .tsx file that looks like an
+#   HTTP client (mentions a base URL, fetch/httpx/requests/undici/axios, or an
+#   Authorization/Bearer header). Other files are ignored.
+#
+#   Checks per connector file:
+#     1. FAIL  hardcoded secret  — an inline API key / bearer literal / long
+#              token-looking string assigned in source (not read from env).
+#     2. FAIL  no retry wired    — no tenacity import, no backoff loop, and no
+#              undici/axios retry interceptor anywhere in the file.
+#     3. FAIL  no pagination loop — uses pagination-style params (cursor/offset/
+#              page/after/Link) but has no loop (while/for/async generator) to
+#              walk them: a lone "get first page" that ignores the next cursor.
+#     4. FAIL  no request timeout — issues HTTP calls but sets no timeout /
+#              AbortSignal.timeout on them.
+#     5. FAIL  token in localStorage  — long-lived token stored in localStorage.
+#     6. WARN  token logging      — a log/console call that emits the token,
+#              Authorization header, or Bearer value.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for connector source
+#   ./verify.sh --path src      # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict (also: nothing to check)
+#   1  a structural failure, or --strict with a warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2 — no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/apiconn-verify.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+ALL="$TMPDIR_V/all"
+FILES="$TMPDIR_V/files"
+
+# Candidate source files (skip node_modules / vendored / build dirs).
+find "$SCAN_PATH" -type f \
+  \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' \) \
+  2>/dev/null \
+  | grep -Ev '/(node_modules|\.git|dist|build|\.venv|venv|__pycache__)/' \
+  > "$ALL" || true
+
+# Keep only files that look like an HTTP client (a connector).
+: > "$FILES"
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  if grep -Eiq 'https?://|\bfetch\(|\bhttpx\b|\brequests\.|\bundici\b|\baxios\b|Authorization|Bearer ' "$f" 2>/dev/null; then
+    printf '%s\n' "$f" >> "$FILES"
+  fi
+done < "$ALL"
+
+if [ ! -s "$FILES" ]; then
+  skip "no connector-like source (.py/.ts/.js with an HTTP client) under: $SCAN_PATH"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- per-file checks ---------------------------------------------------------
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_ok=1
+
+  # 1. Hardcoded secret: an inline literal assigned to a key/token/secret-looking
+  #    name, OR a Bearer/sk- literal embedded in source. Reading from env is fine.
+  if grep -Eni \
+      '(api[_-]?key|secret|token|bearer|password|client[_-]?secret)[[:space:]]*[:=][[:space:]]*["'\''][A-Za-z0-9_\-]{16,}["'\'']' \
+      "$f" 2>/dev/null | grep -Eiv 'process\.env|os\.environ|getenv|import\.meta\.env|<[^>]*>|YOUR_|EXAMPLE|xxxx|\.\.\.' >/dev/null; then
+    fail "hardcoded secret literal: $f"
+    file_ok=0
+  fi
+  if grep -Eni '["'\''](sk_live_|sk_test_|ghp_|xox[baprs]-|AKIA)[A-Za-z0-9_\-]{8,}' "$f" 2>/dev/null >/dev/null; then
+    fail "hardcoded provider token literal: $f"
+    file_ok=0
+  fi
+
+  # 2. Retry mechanism wired somewhere in the file.
+  if grep -Eiq 'tenacity|@retry|wait_exponential|backoff|retry_if|maxRetries|max_retries|interceptors\.|retry[_-]?interceptor|exponential' "$f" 2>/dev/null; then
+    : # has a retry primitive
+  elif grep -Eiq 'for[[:space:]].*attempt|while[[:space:]].*attempt|range\([[:space:]]*[0-9]|attempt[[:space:]]*[+<]' "$f" 2>/dev/null \
+       && grep -Eiq 'sleep|setTimeout|delay|backoff' "$f" 2>/dev/null; then
+    : # has a hand-rolled retry loop with a delay
+  else
+    fail "no retry mechanism wired (no tenacity/backoff/interceptor or retry loop): $f"
+    file_ok=0
+  fi
+
+  # 3. Pagination loop, only required when the file uses pagination params.
+  if grep -Eiq 'cursor|next[_-]?cursor|endCursor|hasNextPage|pageInfo|offset|\bpage\b|\bafter\b|rel="next"|Link' "$f" 2>/dev/null; then
+    if grep -Eiq 'while[[:space:]]|for[[:space:]]|yield|async[[:space:]]*function\*|def[[:space:]]+iter|->[[:space:]]*Generator|AsyncIterator' "$f" 2>/dev/null; then
+      : # walks the pages
+    else
+      fail "pagination params used but no loop to walk them (first-page-only): $f"
+      file_ok=0
+    fi
+  fi
+
+  # 4. Request timeout set on the HTTP calls.
+  if grep -Eiq 'timeout|AbortSignal\.timeout|AbortController|signal[[:space:]]*[:=]|connect_timeout|read_timeout' "$f" 2>/dev/null; then
+    : # a timeout is configured
+  else
+    fail "no request timeout set (a hung socket will stall the run): $f"
+    file_ok=0
+  fi
+
+  # 5. Token in localStorage (long-lived secret in an XSS-readable store).
+  if grep -Eiq 'localStorage\.(setItem|getItem)?[[:space:]]*\(?[^)]*\b(token|bearer|access[_-]?token|refresh[_-]?token|api[_-]?key)\b' "$f" 2>/dev/null \
+     || grep -Eiq 'localStorage[^;]*\b(token|access_token|refresh_token|apiKey)\b' "$f" 2>/dev/null; then
+    fail "token stored in localStorage (XSS-readable): $f"
+    file_ok=0
+  fi
+
+  # 6. WARN: logging the token / Authorization header.
+  if grep -Eni '(console\.(log|info|debug|warn|error)|logg?(er)?\.|print|logging\.)[^;\n]*\b(token|bearer|authorization)\b' "$f" 2>/dev/null \
+     | grep -Eiv 'x-request-id|status|attempt|request[_-]?id|//|#' >/dev/null; then
+    warn "possible token/Authorization logging: $f"
+  fi
+
+  if [ "$file_ok" -eq 1 ]; then
+    ok "connector shape ok: $f"
+  fi
+done < "$FILES"
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/shared/api-design/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: api-design
+description: "Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency — emitted as OpenAPI 3.1. NOT implementing the endpoints (that is `fastapi`/`nestjs`/`go`/`nodejs`), NOT auth hardening (that is `secure-coding`), NOT consuming a third-party API (that is `api-connector-builder`)."
+tags: [api-design, rest, graphql, openapi, versioning, pagination, http, rfc9457, contract-design]
+recommends: [fastapi, nestjs, go, nodejs, secure-coding, webhooks, api-connector-builder, code-review]
+origin: ai-hub
+---
+
+# API design
+
+## Your one job
+
+You design the **contract** an API exposes. You do not write the handler. The deliverable is a set of decisions a backend skill can implement directly: resource shapes, URLs, methods, the status-code map, one error envelope, pagination params, versioning rules — ideally captured as an **OpenAPI 3.1** document.
+
+When the user names a framework (FastAPI, NestJS, Go, Node), they own the build; you are pulled in for contract questions. Settle the contract first, then hand off (see [Handoff](#handoff)). Keep every decision framework-neutral: nothing here should mention an ORM, a router, or a DI container.
+
+## REST vs GraphQL vs hybrid
+
+Pick on traffic shape, not fashion. Decide once, write it down.
+
+| Situation | Choose | Why |
+|---|---|---|
+| CRUD-ish resources, public API, HTTP caching matters | **REST** | URLs map to resources; CDN/proxy caching works on GET + ETag out of the box |
+| Many client shapes, deep nested graphs, mobile over-fetch is real | **GraphQL** | one round-trip, client picks fields; no N endpoints per screen |
+| Stable resource API + one rich read surface for a client app | **Hybrid** | REST for the system of record, a GraphQL read layer on top |
+
+Operational gotcha that decides monitoring: **GraphQL returns HTTP 200 even when a field errored** — failures live in an `errors[]` array next to partial `data`. Your dashboards cannot alert on 5xx; you must alert on the `errors[]` payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Schema/nullability design, mutation and error-union conventions, and this error model in full: [`references/graphql-design.md`](references/graphql-design.md).
+
+## Resource & URL modeling
+
+Resources are **nouns**; HTTP methods are the verbs. Never put a verb in a path.
+
+Rules, each with its reason:
+- **Plural collections, consistent everywhere** — `/projects`, `/projects/{id}`. Pick plural and never mix singular in; inconsistent naming is the most-cited design smell.
+- **Nest sub-resources one level** — `/projects/{id}/tasks`. Deeper than one level (`/projects/{p}/tasks/{t}/comments/{c}`) gets unreadable; link to the flat resource instead (`/comments/{c}`).
+- **Methods carry intent** — `GET` read, `POST` create, `PUT` full replace, `PATCH` partial update, `DELETE` remove. A path never says what it does.
+- **Filter/sort/select via query string, not new paths** — `?status=open&sort=-created_at&fields=id,title`. One `GET /projects` handles all of it; don't mint `/projects/open` and `/projects/byDate`.
+
+| Bad | Good | Why |
+|---|---|---|
+| `POST /createProject` | `POST /projects` | the method is the verb |
+| `GET /getUserOrders/{id}` | `GET /users/{id}/orders` | noun hierarchy, no verb |
+| `GET /project` and `GET /tasks` | `GET /projects` and `GET /tasks` | one plural convention |
+| `GET /projects/active` | `GET /projects?status=active` | filter is a query param |
+| `POST /projects/{id}/delete` | `DELETE /projects/{id}` | method, not path segment |
+
+Full query grammar (filter operators, sparse fieldsets, sort syntax), content negotiation, rate-limit headers and a HATEOAS note: [`references/rest-conventions.md`](references/rest-conventions.md).
+
+## Status codes that matter
+
+You need a small map, used consistently. Don't overload 200.
+
+```http
+200 OK            # read / update succeeded, body returned
+201 Created       # resource created — include Location: /projects/{id}
+202 Accepted      # async accepted, not done — return a status URL
+204 No Content    # success, nothing to return (e.g. DELETE)
+400 Bad Request   # malformed syntax / unparseable
+401 Unauthorized  # not authenticated — who are you?
+403 Forbidden     # authenticated but not allowed — I know you, no
+404 Not Found     # resource absent (or hidden from this caller)
+409 Conflict      # state collision — duplicate, version mismatch
+422 Unprocessable # syntactically fine, semantically invalid (validation)
+429 Too Many Req  # rate limited — include Retry-After
+5xx               # your fault, never the client's; never leak the stack
+```
+
+Two distinctions agents get wrong:
+- **401 vs 403** — 401 means *unauthenticated* (no/invalid credentials); 403 means *authenticated but unauthorized*. Returning 401 on a permission failure leaks that re-auth might help when it won't.
+- **409 vs 422** — 409 is a *state* conflict (the request fights the current server state: dup key, stale version). 422 is a *content* problem (the body parses but fails business rules). Full status-code table with when-each in [`references/rest-conventions.md`](references/rest-conventions.md).
+
+## Error envelope: RFC 9457
+
+One error shape across **every** endpoint. Adopt **RFC 9457 Problem Details** (the current standard; it obsoletes RFC 7807). Media type `application/problem+json`. Standard members: `type`, `title`, `status`, `detail`, `instance`, plus your own extension members.
+
+```json
+{
+  "type": "https://api.acme.com/problems/validation-error",
+  "title": "Your request parameters didn't validate.",
+  "status": 422,
+  "detail": "due_date must be in the future.",
+  "instance": "/projects/8a3/tasks",
+  "errors": [
+    { "field": "due_date", "message": "must be in the future" }
+  ],
+  "correlation_id": "req_01H..."
+}
+```
+
+Rules:
+- **`type` is a stable, machine-readable URI** — clients branch on it, not on `detail`. Never change a `type` string once published.
+- **`title` is human, generic per type; `detail` is human, specific to this occurrence.** `detail` is for people, not parsers.
+- **Always carry a correlation/request id** (extension member) so a support ticket maps to a log line.
+- **Never leak internals** — no stack traces, SQL, internal hostnames, or raw DB ids in `detail`. That is both an information leak and a coupling leak.
+
+## Pagination
+
+Default to **cursor (keyset)** pagination. Use offset only for small, bounded sets.
+
+| Approach | Use when | Why |
+|---|---|---|
+| **Cursor / keyset** | large or changing datasets, feeds, anything hot | opaque token over an indexed ordered column → constant-time, stable across inserts |
+| **Offset / limit** | small bounded admin lists, fixed reference tables | simple, but the DB scans-and-discards skipped rows (degrades with depth) and **skips or duplicates rows** when data shifts between page loads |
+
+Decision line: if the list can grow unbounded or rows can be inserted between page fetches, use cursor.
+
+REST cursor envelope — same keys on every list endpoint:
+
+```json
+{
+  "data": [ { "id": "...", "title": "..." } ],
+  "next_cursor": "eyJpZCI6MTI4N30",
+  "has_more": true
+}
+```
+
+The next page is `GET /projects?cursor=eyJpZCI6MTI4N30&limit=50`. The cursor is opaque — clients must not parse or construct it.
+
+GraphQL has its own de-facto standard: **Relay Connections** — `edges { node, cursor }`, `pageInfo { hasNextPage, endCursor }`, args `first` / `after`. Use it; don't invent a bespoke GraphQL pagination shape. See [`references/graphql-design.md`](references/graphql-design.md).
+
+## Versioning & evolution
+
+**Prefer additive, non-breaking evolution over a new version.** A new version forks your client base and your maintenance. Most changes don't need one.
+
+- **Non-breaking (no version bump):** adding an optional field, adding a new endpoint, adding a new optional query param, adding a new enum value clients are told to tolerate.
+- **Breaking (needs a version):** removing/renaming a field, changing a type, making an optional field required, changing status-code semantics, changing the error `type` for a case.
+
+When you must version, **use a URL path version (`/v1/...`) for public APIs** — it is visible, cacheable, trivially testable in a browser, and the most common convention clients expect. Header/media-type versioning (`Accept: application/vnd.acme.v2+json`) keeps URLs clean but is harder to test and cache; query-param versioning (`?version=2`) pollutes every URL. Default to path.
+
+Deprecate gracefully with the `Deprecation` and `Sunset` response headers so clients get programmatic warning before removal:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+Full breaking-vs-non-breaking matrix, the three versioning mechanisms and the deprecation/sunset workflow: [`references/versioning-and-evolution.md`](references/versioning-and-evolution.md).
+
+## Idempotency & concurrency
+
+- **Make POST/PATCH retry-safe with an `Idempotency-Key` header.** The client sends a unique key; the server replays the original response on a retry instead of double-creating. This is an IETF httpapi draft (not yet an RFC) but is the proven pattern across Stripe, PayPal, and others — adopt it for any create/charge/payment-like operation where a network retry could duplicate work.
+
+```http
+POST /payments
+Idempotency-Key: 9b1f7c2e-... 
+```
+
+- **Use `ETag` + `If-Match` for optimistic concurrency** on PUT/PATCH. The server returns an `ETag` (a version fingerprint) on read; the client sends it back in `If-Match` on write. If it no longer matches, the server returns **412 Precondition Failed** — no lost update. Use `If-None-Match` for conditional GET caching.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Verbs in paths (`/getUsers`, `/createProject`) | duplicates HTTP semantics, breaks caching/tooling | noun + HTTP method |
+| Mixed plural/singular collections | clients can't predict URLs | one plural convention everywhere |
+| 200 on error (REST) | breaks status-code monitoring and client error handling | real 4xx/5xx + RFC 9457 body |
+| Different error shape per endpoint | every client writes per-endpoint parsing | one `application/problem+json` shape |
+| Leaking stack traces / SQL / DB ids in errors | info leak + couples clients to internals | generic `title`, safe `detail`, correlation id |
+| Offset pagination on a hot/large feed | slow at depth; skips/dups rows on insert | cursor/keyset pagination |
+| Unbounded list endpoint (no limit) | one client can pull the whole table | enforce a default + max `limit` |
+| New version for every change | forks clients, multiplies maintenance | additive non-breaking evolution |
+| Breaking a field in place on a live version | silently breaks existing clients | new field/version + deprecation headers |
+| 401 for a permission failure | misleads client into re-authing | 403 when authenticated-but-forbidden |
+| 200 for a created resource | hides the create, no `Location` | 201 + `Location` header |
+| Ignoring GraphQL partial `errors[]` | failures invisible to monitoring | alert on `errors[]`, not just HTTP 5xx |
+
+## Handoff
+
+The contract is the artifact. Emit it as an **OpenAPI 3.1** document — the checkable deliverable a framework skill generates code from. How to shape it, and what `scripts/verify.sh` checks: [`references/openapi-contract.md`](references/openapi-contract.md).
+
+Hand off to the builder:
+- Python/async → [`../fastapi/SKILL.md`](../fastapi/SKILL.md)
+- NestJS / Node DI → [`../nestjs/SKILL.md`](../nestjs/SKILL.md)
+- Go `net/http` → [`../go/SKILL.md`](../go/SKILL.md)
+- Node generally → [`../nodejs/SKILL.md`](../nodejs/SKILL.md)
+
+Adjacent concerns you do **not** own:
+- Auth hardening, OWASP, CORS/CSP threat-modeling → [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md) (you only place 401/403/scopes in the contract)
+- Receiving inbound webhooks (HMAC verify, replay, dedupe) → [`../webhooks/SKILL.md`](../webhooks/SKILL.md)
+- Building an outbound client to a third-party API → [`../api-connector-builder/SKILL.md`](../api-connector-builder/SKILL.md)
+- Reviewing handler code (not the design) → [`../code-review/SKILL.md`](../code-review/SKILL.md)

package/skills/shared/api-design/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: api-design
+
+These cases are run by the repository's eval harness against the skill router. `should_trigger` asserts that for each prompt the router selects `api-design`; `should_not_trigger` asserts the named sibling wins instead (each `route_to` is a real catalog id); `capability` is a rubric-graded generation check — the model is asked the scenario and its output is scored against the `must_include` list. Run them with the repo's eval runner pointed at `cases.yaml`; no network or live API is needed.