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

package/skills/shared/angular/references/migration.md

@@ -0,0 +1,81 @@
+# Incremental migration — legacy Angular → standalone, signals, zoneless
+
+Migrate a working app in small reversible steps. Each step has an official schematic; run them
+one at a time, commit, and verify the app still builds and tests pass before the next.
+
+## Order of operations
+
+1. Update Angular first, then migrate. `ng update @angular/core @angular/cli` runs the
+   bundled migrations for the version you land on. Do not migrate APIs on an old major.
+2. Standalone components/directives/pipes.
+3. Built-in control flow (`*ngIf`/`*ngFor` → `@if`/`@for`).
+4. Signal inputs/outputs.
+5. Zoneless (last — it has the widest blast radius).
+6. Test runner (Karma/Jasmine → Vitest), independently of the above.
+
+## 1. NgModule → standalone
+
+```bash
+ng generate @angular/core:standalone
+```
+
+Run it three times, choosing each mode in turn:
+- *Convert all components, directives and pipes to standalone*
+- *Remove unnecessary NgModule classes*
+- *Bootstrap the application using standalone APIs* (rewrites `main.ts` to `bootstrapApplication`)
+
+After the last pass you should have an `app.config.ts` with `provideRouter`,
+`provideHttpClient`, etc. Delete the now-empty `AppModule`.
+
+## 2. Control flow: *ngIf / *ngFor → @if / @for
+
+```bash
+ng generate @angular/core:control-flow
+```
+
+This rewrites templates automatically. Review every converted `@for`: the schematic inserts a
+`track` expression (often `track $index` as a safe default). Replace `$index` with a stable key
+(`track item.id`) wherever items have identity, so the DOM reuses nodes on reorder. Once
+converted you can drop `CommonModule` imports that only existed for the directives.
+
+## 3. Decorator inputs/outputs → signals
+
+```bash
+ng generate @angular/core:signal-input-migration
+ng generate @angular/core:output-migration
+ng generate @angular/core:signal-queries-migration   # @ViewChild/@ContentChild -> viewChild()/contentChild()
+```
+
+What changes for callers inside the class:
+- `this.userId` (a value) becomes `this.userId()` (a signal read). The migration updates
+  template and class reads, but check any code that assigned to the field — signal inputs are
+  read-only; lift writable state into a separate `signal()` or use `model()` for two-way.
+- `@Output() saved = new EventEmitter()` → `saved = output()`, emit with `saved.emit(x)`.
+
+## 4. Zone.js → zoneless go-live checklist
+
+Flip this last, after signals and control flow are in place.
+
+- [ ] Add `provideZonelessChangeDetection()` to the app providers (and to test providers).
+- [ ] Remove `provideZoneChangeDetection()` if present.
+- [ ] Delete the `zone.js` import from `polyfills`/`main.ts`; remove `zone.js` from
+      `package.json` and the `polyfills` entry in `angular.json`.
+- [ ] Audit every component for state read in the template that is **not** a signal — under
+      zoneless, a plain field mutated outside an event handler will not repaint. Convert it to a
+      `signal()`, or ensure the change originates from a tracked source (signal, async pipe,
+      template event, router).
+- [ ] Replace any `setTimeout`/`Promise`/3rd-party-callback that mutates view state with a
+      signal write, or call `ChangeDetectorRef.markForCheck()` from inside it.
+- [ ] Search for `ChangeDetectorRef.detectChanges()` "fix-it" calls and the `NgZone.run()`
+      escape hatch — both are smells that some state isn't a signal yet.
+- [ ] Run the app and click through; watch for views that update only on the *next* unrelated
+      interaction (the classic zoneless-miss symptom).
+
+## 5. Karma/Jasmine → Vitest
+
+New Angular 21 projects use Vitest by default. For an existing project, switch the test builder
+to the Vitest-based runner in `angular.json` and migrate specs: Jasmine's `spyOn`/`jasmine.
+createSpy` map to Vitest's `vi.fn`/`vi.spyOn`, and `expect().toHaveBeenCalled()` etc. are
+compatible. Keep `TestBed`; only the runner and the mocking API change. Add
+`provideZonelessChangeDetection()` to test module providers and prefer `await
+fixture.whenStable()` over manual `detectChanges()` loops.

package/skills/shared/angular/references/signals-rxjs.md

@@ -0,0 +1,92 @@
+# Signals vs RxJS — when to use which, and how to bridge
+
+Signals and RxJS coexist in modern Angular. Signals are the default for UI state and
+synchronous derivation; RxJS still owns asynchronous *streams* of events over time.
+
+## Decision matrix
+
+| You have… | Use | Why |
+|-----------|-----|-----|
+| A piece of UI state read in a template | `signal()` | Pull-based, glitch-free, drives zoneless CD directly |
+| A value derived from other state | `computed()` | Memoized, lazy, no manual subscription |
+| One async fetch tied to inputs | `httpResource()` / `resource()` | Gives `value/isLoading/error/reload`, auto-refetch, no leak |
+| A stream over time (websocket, key events, intervals) | RxJS `Observable` | Signals are values-now, not events-over-time |
+| Debounce / throttle / retry / cancel-in-flight | RxJS (`debounceTime`, `switchMap`, `retry`) | These are stream operators; signals have no time dimension |
+| A writable copy that resets when a source changes | `linkedSignal()` | Purpose-built; avoids an effect-to-sync anti-pattern |
+
+Rule of thumb: **state → signals, events → observables.** When in doubt, start with a signal;
+escalate to RxJS only when you need an operator that models time.
+
+## Interop
+
+`toSignal()` and `toObservable()` are the two bridges (`@angular/core/rxjs-interop`).
+
+```typescript
+import { toSignal, toObservable, takeUntilDestroyed } from '@angular/core/rxjs-interop';
+
+// Observable -> Signal: subscribe is managed for you; unsubscribes on destroy.
+private search = signal('');
+results = toSignal(
+  toObservable(this.search).pipe(
+    debounceTime(300),
+    switchMap(q => this.api.search(q)),  // switchMap cancels the prior request
+  ),
+  { initialValue: [] as Result[] },
+);
+```
+
+- `toSignal(obs$, { initialValue })` — read `results()` in the template; the subscription is
+  cleaned up automatically when the injection context is destroyed.
+- `toObservable(sig)` — turn a signal into a stream so you can apply operators. It emits on the
+  microtask queue, not synchronously.
+- `takeUntilDestroyed()` — for the rare hand-rolled subscription, this completes it when the
+  component/service is destroyed. Use it instead of a manual `Subscription` + `ngOnDestroy`.
+
+## effect() pitfalls
+
+`effect()` is for side effects, not derivation. Common ways it goes wrong:
+
+```typescript
+// Pitfall 1 — infinite loop: an effect that writes a signal it also reads.
+effect(() => this.count.set(this.count() + 1)); // re-runs forever
+
+// Pitfall 2 — using an effect to derive state. Use computed() instead.
+effect(() => this.total.set(this.qty() * this.price())); // double-fires, hidden graph
+// Fix:
+total = computed(() => this.qty() * this.price());
+
+// Pitfall 3 — wanting to write without creating a dependency: wrap in untracked().
+effect(() => {
+  const id = this.userId();           // tracked dependency
+  untracked(() => this.log.push(id)); // read/write here is NOT a dependency
+});
+```
+
+- An effect runs once on creation and again whenever any signal it *reads* changes.
+- Reading a signal inside `untracked(() => …)` does not register it as a dependency.
+- If you find yourself calling `.set()` from inside an effect to feed the template, you almost
+  certainly want `computed()` or `linkedSignal()`.
+
+## resource() / httpResource() patterns
+
+```typescript
+// Dependent fetch: the resource re-runs when team() changes.
+team = signal('eng');
+users = httpResource<User[]>(() => `/api/users?team=${this.team()}`);
+
+// Mutate then refresh:
+async addUser(u: User) {
+  await firstValueFrom(this.http.post('/api/users', u));
+  this.users.reload();
+}
+
+// Loading / error in the template:
+// @if (users.isLoading()) { <app-spinner/> }
+// @else if (users.error()) { <p>Failed</p> }
+// @else { @for (u of users.value(); track u.id) { … } }
+```
+
+- A `resource()` cancels the previous load when its `params` change (it passes an `AbortSignal`
+  to the loader) — use it for `fetch` cancellation without writing RxJS.
+- `httpResource()` is GET-oriented and reactive. For POST/PUT/DELETE keep `HttpClient` and call
+  `reload()` after the mutation.

package/skills/shared/angular/scripts/verify.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# verify.sh — Angular modern-baseline copy-banlist (heuristic lint, NOT a compiler).
+#
+# USAGE
+#   bash scripts/verify.sh [PATH ...]
+#   Run from your Angular project root. With no args it scans ./src (falling back
+#   to the current dir). Pass explicit paths to scope it to just-edited files:
+#     bash scripts/verify.sh src/app/users
+#
+# WHAT IT DOES
+#   Greps Angular .ts/.html sources for legacy patterns this skill bans, so the
+#   agent can self-correct toward standalone + signals + built-in control flow:
+#     - @NgModule in new code
+#     - legacy structural directives  *ngIf / *ngFor / *ngSwitch
+#     - decorator I/O  @Input() / @Output()
+#     - @for blocks missing a `track` expression
+#     - constructor-based DI (constructor(private x: X)) where inject() is the rule
+#   Each hit prints file:line. It is a best-effort heuristic, not a parser, so it
+#   may have false positives/negatives — treat it as a hint.
+#
+# GUARANTEES
+#   - Read-only: never writes, fixes, installs, or hits the network.
+#   - Exits 0 on an empty/clean target (no sources, or no hits) — no false failure.
+#   - Exits 1 only when at least one banned pattern is found, so it can gate a loop.
+#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+hits=0
+ok() { printf '%s\n' "${GREEN}ok${RESET}  $1"; }
+
+# --- resolve scan roots -----------------------------------------------------
+roots=""
+if [ "$#" -gt 0 ]; then
+  roots="$*"
+elif [ -d ./src ]; then
+  roots="./src"
+else
+  roots="."
+fi
+
+# Collect candidate Angular source files (.ts/.html), skipping vendor/build dirs
+# and *.spec.ts / *.d.ts. Newline-delimited list; empty if nothing matches.
+files="$(
+  find $roots \
+    \( -name node_modules -o -name dist -o -name .angular -o -name .git -o -name coverage \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.html' \) \
+    ! -name '*.spec.ts' ! -name '*.d.ts' -print 2>/dev/null
+)"
+
+if [ -z "$files" ]; then
+  printf '%s\n' "${YELLOW}skip${RESET} no Angular .ts/.html sources under: $roots"
+  exit 0
+fi
+
+# Grep a pattern across all files, reporting each match as "file:line: text".
+# $1 = ERE pattern, $2 = human label. Counts hits into the global $hits.
+scan() {
+  pattern="$1"; label="$2"
+  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE "$pattern" "$f" 2>/dev/null | sed "s|^|$f:|"
+  done)"
+  if [ -n "$out" ]; then
+    printf '%s\n' "$out" | while IFS= read -r m; do
+      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} $label  $m"
+    done
+    n="$(printf '%s\n' "$out" | grep -c . )"
+    hits=$((hits + n))
+  else
+    ok "no $label"
+  fi
+}
+
+# @for openers that do NOT contain `track` on the same line — track is required.
+scan_for_track() {
+  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE '@for[[:space:]]*\(' "$f" 2>/dev/null | grep -v 'track' | sed "s|^|$f:|"
+  done)"
+  if [ -n "$out" ]; then
+    printf '%s\n' "$out" | while IFS= read -r m; do
+      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} @for without track (track is required)  $m"
+    done
+    n="$(printf '%s\n' "$out" | grep -c . )"
+    hits=$((hits + n))
+  else
+    ok "no @for without track"
+  fi
+}
+
+printf '=== Angular banlist (%s files under %s) ===\n' "$(printf '%s\n' "$files" | grep -c .)" "$roots"
+
+# 1. NgModule in new code.
+scan '@NgModule' '@NgModule (use standalone components)'
+
+# 2. Legacy structural directives.
+scan '\*ng(If|For|Switch)\b' 'legacy *ngIf/*ngFor/*ngSwitch (use @if/@for/@switch)'
+
+# 3. Decorator I/O.
+scan '@(Input|Output)\(' '@Input()/@Output() decorator (use input()/output())'
+
+# 4. @for blocks missing the required `track` expression.
+scan_for_track
+
+# 5. Constructor-based DI.
+scan 'constructor[[:space:]]*\([^)]*(private|public|protected|readonly)[[:space:]]+[A-Za-z_]+[[:space:]]*:' 'constructor DI (use inject())'
+
+printf '\n'
+if [ "$hits" -gt 0 ]; then
+  printf '%sFAIL%s %d banned-pattern hit(s) — migrate toward standalone + signals.\n' "$RED" "$RESET" "$hits"
+  exit 1
+fi
+printf '%sPASS%s clean — no banned legacy Angular patterns found.\n' "$GREEN" "$RESET"
+exit 0

package/skills/shared/api-connector-builder/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: api-connector-builder
+description: "Use when writing a client for someone else's REST or GraphQL API: auth flow choice and token refresh, pagination to exhaustion, retry-with-jitter on transient failures only, rate-limit-aware throttling. NOT inbound callbacks (that is `webhooks`), NOT chaining services (that is `automation-flows`), NOT designing your own API (that is `api-design`)."
+tags: [api, rest, graphql, oauth, pagination, retries, rate-limiting, http-client, connector]
+recommends: [webhooks, automation-flows, api-design, data-scraper, secure-coding, error-handling, structured-extraction]
+origin: ai-hub
+---
+
+# API connector builder — auth, pagination, retries, rate limits
+
+You are writing a client for **someone else's** HTTP API. You do not own the
+contract; you obey it. The deliverable is one typed connector module per vendor
+that authenticates, walks the whole result set, retries only transient failures
+with backoff, and stays under the rate limit without getting the key banned.
+One connector = one vendor: mixed clients tangle two auth schemes and two
+rate-limit budgets into something no one can reason about.
+
+Four pillars, every time: **auth, pagination, retries, rate limits.** If your
+connector skips any one of them it works in the demo and breaks in production —
+on page 2, on token expiry, on the first 429, or on a flaky network.
+
+## Step 0 — read the contract
+
+Read the vendor docs before writing a line — invented endpoints and guessed
+field names 404 in prod. Extract these first; each one changes what you write,
+so missing one means a rewrite.
+
+| Find in their docs        | Why it changes your code                                  |
+| ------------------------- | --------------------------------------------------------- |
+| Auth scheme + token TTL   | Picks the flow below; TTL decides if you need refresh     |
+| Base URL **and version**  | Wrong version = silent 404s or deprecated field shapes    |
+| Rate-limit header names   | You cannot throttle to a budget you cannot read           |
+| Pagination style          | Cursor vs offset vs Link vs Relay = different loop         |
+| Error envelope shape      | Where the real error code lives (body, not always status) |
+| Idempotency support       | Decides whether POST is safe to retry (key header?)       |
+
+If a fact is not in the docs, probe one real call and read the response headers
+and body — do not assume.
+
+## Auth — pick the flow, then store the secret right
+
+OAuth 2.1 is the current baseline. Three deltas you must honor: **PKCE is
+mandatory for every authorization-code client**, the **Implicit** and
+**Resource-Owner-Password** grants are **removed**, and **bearer tokens may not
+travel in query strings** (header only) — query strings end up in logs and
+referrers. (oauth.net/2.1, accessed 2026-06-02.)
+
+| Flow                          | Pick it when                                | Secret lives        | Refresh strategy                       |
+| ----------------------------- | ------------------------------------------- | ------------------- | -------------------------------------- |
+| **API key in header**         | Simple server-to-server, vendor issues key  | env / secret store  | none; rotate manually                  |
+| **Bearer static token**       | Personal access token, long-lived           | env / secret store  | none; treat as a key                   |
+| **OAuth2 Client Credentials** | Machine-to-machine, no end user             | client_id + secret  | re-mint on 401; cache until expiry     |
+| **OAuth2 Auth-Code + PKCE**   | Acting on behalf of a user                  | refresh token       | rotate on every refresh (see below)    |
+| **Device flow**               | CLI / TV / input-constrained device         | refresh token       | poll then rotate as auth-code          |
+
+**Refresh-token rule (public clients):** refresh tokens must be **sender-
+constrained or one-time-use** — rotated on every refresh, with the old one
+invalidated. Keep access tokens short-lived. Never log a raw token; log a partial
+or hash if you must correlate. (OAuth 2.0 Security BCP / RFC 9700, accessed
+2026-06-02.) Full per-flow walkthroughs, token storage, and a DPoP note are in
+`references/auth-flows.md`.
+
+## Retries + backoff
+
+Retry **only transient failures**, and only when the operation is safe to repeat.
+
+| Status / error                       | Retry? | Note                                          |
+| ------------------------------------ | ------ | --------------------------------------------- |
+| 429 Too Many Requests                | yes    | honor `Retry-After` (see rate limits)         |
+| 502 / 503 / 504                      | yes    | server-side transient                         |
+| Connection reset / timeout / DNS     | yes    | network transient                             |
+| 400 / 401 / 403 / 404 / 409 / 422    | **no** | replay returns the same error — fix the call  |
+| 2xx                                  | n/a    | success                                       |
+
+**Idempotency gate.** GET/PUT/DELETE are idempotent by semantics and safe to
+retry. **POST is not** — only retry it if you send a stable **idempotency key**
+so the server dedupes the duplicate. (AWS Builders' Library, accessed 2026-06-02.)
+
+**Backoff with jitter.** Use `delay = min(cap, base * 2^attempt) + random_jitter`.
+The jitter is not optional: without it, every client that failed at the same
+instant retries at the same instant — a synchronized thundering herd that DDoSes
+the recovering server. Full or decorrelated jitter is preferred. Always set stop
+conditions: **max attempts 3–5, a total deadline, and a per-attempt timeout.**
+(AWS Builders' Library, accessed 2026-06-02.)
+
+```python
+# Bad: retries everything, flat sleep, no jitter, no cap, no deadline.
+for _ in range(10):
+    r = httpx.get(url)
+    if r.status_code == 200:
+        return r.json()
+    time.sleep(1)  # 4xx will never recover; herds synchronize on flat 1s
+```
+
+```python
+# Good: transient-only, exponential backoff WITH jitter, bounded.
+import random, time, httpx
+
+RETRYABLE = {429, 502, 503, 504}
+
+def get(url, *, attempts=5, base=0.5, cap=20.0, deadline=60.0):
+    started = time.monotonic()
+    for attempt in range(attempts):
+        try:
+            r = httpx.get(url, timeout=10.0)  # per-attempt timeout
+        except (httpx.ConnectError, httpx.ReadTimeout):
+            pass  # network transient -> fall through to backoff
+        else:
+            if r.status_code == 200:
+                return r.json()
+            if r.status_code not in RETRYABLE:
+                r.raise_for_status()  # 4xx: do not retry, surface it
+        if time.monotonic() - started > deadline:
+            raise TimeoutError("retry deadline exceeded")
+        delay = min(cap, base * 2 ** attempt) + random.uniform(0, base)
+        time.sleep(delay)
+    raise RuntimeError("max attempts exhausted")
+```
+
+In Python prefer `tenacity` 9.1.4 (`@retry` with `wait_exponential_jitter`,
+`stop_after_attempt`, `retry_if_exception_type`) over a hand loop; in Node/TS use
+`undici` (the engine behind global `fetch()` since Node 18) with its retry
+interceptor. (PyPI/tenacity, nodejs/undici, accessed 2026-06-02.)
+
+## Rate limits
+
+Do not guess the wait — the server tells you. **Precedence:**
+
+1. **`Retry-After` present** (on a 429 or 503) → wait exactly that. It is either
+   a number of seconds or an HTTP-date; handle both.
+2. **No `Retry-After`** → compute the wait from `X-RateLimit-Reset` (a Unix epoch
+   or a delta-seconds, per vendor docs).
+3. **Proactively throttle** on `X-RateLimit-Remaining` — slow down *before* you
+   hit zero rather than absorbing a wall of 429s. (iotools.cloud rate-limiting
+   guidance, accessed 2026-06-02.)
+
+```python
+# Bad: ignore the headers, hammer, eat 429s, get the key throttled or banned.
+while more:
+    resp = client.get(next_url)   # no remaining check, no Retry-After
+    process(resp)
+```
+
+```python
+# Good: header-aware. Honor Retry-After, else reset; brake near the limit.
+def wait_for_rate_limit(resp):
+    ra = resp.headers.get("Retry-After")
+    if ra is not None:
+        return float(ra) if ra.isdigit() else _seconds_until_httpdate(ra)
+    remaining = int(resp.headers.get("X-RateLimit-Remaining", "1"))
+    if remaining <= 1:
+        reset = float(resp.headers.get("X-RateLimit-Reset", "0"))
+        return max(0.0, reset - time.time())  # or reset directly if delta-seconds
+    return 0.0
+```
+
+For sustained pulls, gate every request through a **token-bucket** sized to the
+documented budget (e.g. 60 req/min → refill 1 token/sec, capacity 60) so bursts
+smooth out instead of slamming the wall.
+
+## Pagination — loop to exhaustion
+
+There is no single best strategy; the vendor chose one and you follow it. The
+universal rule: **loop until the API says there is no next page — never a fixed
+page count.** A hardcoded `for page in range(10)` silently drops everything after
+page 10.
+
+| Style                      | Signal of "next"                          | Trade-off                                   |
+| -------------------------- | ----------------------------------------- | ------------------------------------------- |
+| **Offset / page number**   | `?offset=` / `?page=` until empty page    | simple; drifts on inserts, slow at depth    |
+| **Cursor / keyset**        | opaque `next_cursor` in body              | stable under writes, fixed cost — prefer it |
+| **Link header (REST)**     | `Link: <...>; rel="next"`                 | parse the header, follow until no `next`    |
+| **Relay (GraphQL)**        | `pageInfo.hasNextPage` + `endCursor`      | pass `endCursor` as `after` next query      |
+
+(graphql.org/learn/pagination + pagination pattern guides, accessed 2026-06-02.)
+
+Expose results as a generator / async-iterator so callers stream instead of
+buffering everything:
+
+```python
+def iter_records(client):
+    cursor = None
+    while True:
+        page = client.get("/items", params={"cursor": cursor, "limit": 100})
+        body = page.json()
+        yield from body["data"]
+        cursor = body.get("next_cursor")
+        if not cursor:           # exhaustion signal, not a counter
+            return
+```
+
+Full code for every style — offset, keyset, `Link`-header parsing, GraphQL Relay
+connection walking, in Python and TS, plus dedup-on-overlap notes — is in
+`references/pagination.md`.
+
+## Putting it together
+
+A minimal connector wires all four pillars plus env config and structured logging.
+
+```python
+# connector.py — Python: httpx + tenacity
+import os, logging, httpx
+from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception_type
+
+log = logging.getLogger("connector")
+TOKEN = os.environ["VENDOR_API_TOKEN"]          # from env, never hardcoded
+
+class Transient(Exception): ...
+
+@retry(stop=stop_after_attempt(5),
+       wait=wait_exponential_jitter(initial=0.5, max=20),
+       retry=retry_if_exception_type(Transient))
+def _request(client, method, path, **kw):
+    r = client.request(method, path, timeout=10.0, **kw)   # per-request timeout
+    log.info("req id=%s %s status=%s", r.headers.get("x-request-id"), path, r.status_code)
+    if r.status_code in (429, 502, 503, 504):
+        raise Transient(r.status_code)
+    r.raise_for_status()
+    return r
+
+def client():
+    return httpx.Client(base_url="https://api.vendor.com/v2",
+                        headers={"Authorization": f"Bearer {TOKEN}"})  # header, not query
+```
+
+```typescript
+// connector.ts — Node/TS: global fetch (undici) + bounded retry
+const TOKEN = process.env.VENDOR_API_TOKEN!;          // from env, never hardcoded
+const RETRYABLE = new Set([429, 502, 503, 504]);
+
+export async function request(path: string, init: RequestInit = {}, attempt = 0): Promise<Response> {
+  const res = await fetch(`https://api.vendor.com/v2${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${TOKEN}`, ...init.headers },
+    signal: AbortSignal.timeout(10_000),              // per-request timeout
+  });
+  console.info(JSON.stringify({ id: res.headers.get("x-request-id"), path, status: res.status, attempt }));
+  if (RETRYABLE.has(res.status) && attempt < 4) {
+    const ra = Number(res.headers.get("retry-after"));
+    const wait = Number.isFinite(ra) && ra > 0 ? ra * 1000 : Math.min(20_000, 500 * 2 ** attempt) + Math.random() * 500;
+    await new Promise((r) => setTimeout(r, wait));
+    return request(path, init, attempt + 1);
+  }
+  return res;                                          // caller checks res.ok / paginates
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern                          | Consequence                              | Fix                                          |
+| ------------------------------------- | ---------------------------------------- | -------------------------------------------- |
+| Retry 4xx (401/403/404/422)           | Burns attempts; same error every time    | Retry only 429 + 5xx + network errors        |
+| `for page in range(N)` fixed loop     | Silently drops records past page N       | Loop on cursor / Link / hasNextPage          |
+| Flat `sleep(1)` between retries        | Synchronized herd hammers recovering API | Exponential backoff **with** jitter + cap    |
+| Log the token / Authorization header  | Leaked credential in shipped logs        | Log request id + status + attempt only       |
+| Hardcode the API key in source        | Leaks via git; cannot rotate cleanly     | Read from env / secret store                 |
+| No request timeout                    | One hung socket stalls the whole run     | Set a per-request timeout always             |
+| Ignore `Retry-After`                  | Keep 429-ing; key gets throttled/banned  | Honor `Retry-After`, else `X-RateLimit-Reset`|
+| Re-POST on retry with no idempotency  | Duplicate charges / records              | Send an idempotency key, or do not retry POST|
+| Token in query string                 | Token ends up in logs / referrers        | Bearer in the `Authorization` header         |
+| Implicit / password OAuth grant       | Removed in OAuth 2.1; insecure           | Auth-Code + PKCE, or Client Credentials      |
+
+## Verify
+
+Run `scripts/verify.sh` over the connector you write: it greps for hardcoded
+secrets, asserts a retry mechanism and a pagination loop and a request timeout
+exist, and flags `localStorage` token storage or plaintext token logging. It is a
+structure linter (read-only), not a behavior test — exit 0 on a clean target.

package/skills/shared/api-connector-builder/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — api-connector-builder
+
+These cases are a hand-run rubric, not an automated test harness; no scoring
+script ships. To run them: paste a `should_trigger` prompt into a fresh agent
+session and confirm `api-connector-builder` is the skill that fires (and not a
+sibling). Paste a `should_not_trigger` prompt and confirm the agent routes to the
+named sibling instead. For the `capability` scenario, have the agent build the
+connector, then grade the result against the `must_include` list — every bullet
+should be satisfied by the code it produces. A connector that hardcodes the token,
+retries all 4xx, or stops after one page fails the rubric regardless of how clean
+it looks.

package/skills/shared/api-connector-builder/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: api-connector-builder
+
+should_trigger:
+  - prompt: "Write a connector for the Linear GraphQL API that pulls every issue, not just the first page."
+    why: "Core task: a typed client against a third-party GraphQL API with Relay cursor connections, walked to exhaustion. The skill's flagship deliverable."
+  - prompt: "This vendor API keeps returning 429. Add backoff and respect their rate limit so we stop getting throttled."
+    why: "Rate-limit + retry symptom. Honor Retry-After / X-RateLimit-* with jittered backoff is squarely this skill."
+  - prompt: "We only ever get the first 100 results back from this API. Paginate through everything."
+    why: "Pagination-to-exhaustion. The fixed-first-page bug is the canonical thing this skill fixes."
+  - prompt: "Our access token expires halfway through a long run and the whole job dies. Add refresh."
+    why: "Non-obvious phrasing — never says 'OAuth' or 'connector', but mid-run token expiry is the auth/refresh concern the skill owns (refresh rotation)."
+  - prompt: "Conector para una API de terceros que nos banea la key cuando vamos demasiado rápido."
+    why: "Spanish trigger combining rate-limit + auth (banned key from hammering). Vendor-agnostic outbound client = this skill."
+  - prompt: "Wrap this vendor REST API as a typed SDK with retries and per-request timeouts."
+    why: "Typed-client framing. 'Wrap a REST API as an SDK' with resilience is the connector-module deliverable."
+  - prompt: "Build me a client for the Shopify Admin API that reads the cursor-based pages and handles the leaky-bucket rate limit."
+    why: "Vendor with no dedicated skill, cursor pagination + bucket rate limit — the generic connector case this skill covers."
+
+should_not_trigger:
+  - prompt: "Verify the incoming webhook signature from Stripe on our /hooks endpoint and reject replays."
+    route_to: webhooks
+    why: "Inbound callback — receiving and verifying events the vendor POSTs to us, the inverse of calling their API."
+  - prompt: "Design the versioning, resource model, and error envelope for OUR new public API."
+    route_to: api-design
+    why: "Authoring a contract others will consume, not consuming someone else's. Opposite side of the boundary."
+  - prompt: "Chain Gmail to Sheets to Slack into one automated if-this-then-that workflow."
+    route_to: automation-flows
+    why: "Multi-service orchestration across many tools, not building one connector for one vendor."
+  - prompt: "Scrape the product prices off this storefront — it has no public API at all."
+    route_to: data-scraper
+    why: "HTML/DOM scraping with no documented API; this skill requires a real API contract to obey."
+  - prompt: "Pull the structured fields out of this LLM's free-text answer into JSON."
+    route_to: structured-extraction
+    why: "Extracting structure from a model response, not making HTTP calls to a third-party API."
+
+capability:
+  - scenario: "Build a Python connector for a paginated REST API (cursor-based) that requires a Bearer token and rate-limits at 60 req/min with X-RateLimit-* headers. It must fetch all records."
+    must_include:
+      - "Reads the Bearer token from an environment variable / secret store — never hardcoded in source."
+      - "Sets a per-request timeout on every call (no unbounded socket wait)."
+      - "Retries only transient statuses (429, 502, 503, 504) and network errors; never retries other 4xx."
+      - "Uses exponential backoff WITH jitter and explicit stop conditions (max attempts 3–5 and/or a total deadline)."
+      - "Honors Retry-After when present, otherwise computes the wait from X-RateLimit-Reset; throttles proactively on X-RateLimit-Remaining."
+      - "Paginates by following the cursor until exhausted (no fixed page-count loop); ideally exposes a generator/iterator."
+      - "Logs request id / status / attempt but never the raw token or Authorization header."
+      - "Sends the token in the Authorization header, not a query string."
+      - "Returns or streams the FULL record set across all pages, not just the first page."