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

package/skills/shared/react-native/references/native-modules.md

@@ -0,0 +1,123 @@
+# Native modules — full walkthrough
+
+When a maintained npm package already bridges the native API, use it and stop. Author a module only when there is no maintained wrapper, you need an API the wrapper doesn't expose, or you're shipping the SDK yourself.
+
+## Decision recap
+
+- **Expo Modules API** — Swift/Kotlin, no codegen, ergonomic DSL. Requires the app to use Expo. Lowest boilerplate; the default for Expo apps.
+- **Turbo Module** — codegen from TypeScript/Flow spec files. The RN-default path; works in bare RN. More boilerplate, fully typed across the boundary.
+- **Nitro Modules** — emerging high-performance option for hot paths. Weigh maturity before betting a shipping feature on it.
+
+## Expo Modules API — full example
+
+A module that exposes a function, a constant, an event, and a native view.
+
+```swift
+// ios/HealthModule.swift
+import ExpoModulesCore
+
+public class HealthModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("HealthModule")
+
+    Constants(["isAvailable": HKHealthStore.isHealthDataAvailable()])
+
+    Events("onStepsUpdate")
+
+    AsyncFunction("readSteps") { (start: Double, end: Double) -> Int in
+      // query HealthKit, return a step count
+      return 0
+    }
+
+    View(HealthChartView.self) {
+      Prop("range") { (view: HealthChartView, range: String) in
+        view.setRange(range)
+      }
+    }
+  }
+}
+```
+
+```kotlin
+// android/src/main/java/com/app/HealthModule.kt
+package com.app
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class HealthModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("HealthModule")
+    Constants("isAvailable" to HealthConnectClient.isAvailable())
+    Events("onStepsUpdate")
+    AsyncFunction("readSteps") { start: Double, end: Double ->
+      // query Health Connect, return a step count
+      0
+    }
+    View(HealthChartView::class) {
+      Prop("range") { view: HealthChartView, range: String -> view.setRange(range) }
+    }
+  }
+}
+```
+
+```ts
+// src/HealthModule.ts — the typed JS surface
+import { requireNativeModule, requireNativeViewManager } from 'expo-modules-core';
+
+type HealthNative = {
+  isAvailable: boolean;
+  readSteps(start: number, end: number): Promise<number>;
+  addListener(event: 'onStepsUpdate', cb: (e: { steps: number }) => void): { remove(): void };
+};
+
+const Native = requireNativeModule<HealthNative>('HealthModule');
+
+export const isHealthAvailable = Native.isAvailable;
+export const readSteps = (start: Date, end: Date) =>
+  Native.readSteps(start.getTime(), end.getTime());
+export const HealthChartView = requireNativeViewManager('HealthModule');
+```
+
+Notes:
+- `AsyncFunction` returns a Promise to JS without blocking the UI thread; use `Function` only for cheap synchronous calls.
+- `Constants` are read once at module init — don't use them for values that change.
+- Events: emit from native with `sendEvent("onStepsUpdate", ...)`; JS subscribes via `addListener`.
+
+## Turbo Module — codegen spec walkthrough
+
+Turbo Modules generate native interfaces from a TS spec. The spec file name must start with `Native`.
+
+```ts
+// specs/NativeHealth.ts
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  readonly isAvailable: () => boolean;
+  readSteps(start: number, end: number): Promise<number>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Health');
+```
+
+Configure codegen in `package.json`, then `pod install` (iOS) / build (Android) runs codegen and emits the C++/ObjC++/Java interfaces you implement:
+
+```json
+{
+  "codegenConfig": {
+    "name": "RNHealthSpec",
+    "type": "modules",
+    "jsSrcsDir": "specs"
+  }
+}
+```
+
+You then implement the generated protocol in Objective-C++/Swift and the generated abstract class in Java/Kotlin. The contract is enforced at build time — a signature mismatch fails codegen rather than crashing at runtime.
+
+## Packaging & autolinking
+
+- Expo Modules in a library: ship an `expo-module.config.json` so autolinking discovers it; the host app needs no manual linking.
+- Turbo Module in a library: a `react-native.config.js` / podspec drives autolinking.
+- Test on a **real device** for anything touching sensors, permissions, or background work — simulators lie about HealthKit, Bluetooth, and camera.
+- Version-gate native APIs (HealthKit availability, Health Connect install state) before calling; expose the gate as a JS-readable constant so the UI can degrade gracefully.

package/skills/shared/react-native/references/performance-debugging.md

@@ -0,0 +1,46 @@
+# Performance & debugging deep dive
+
+## Re-render profiling
+
+Before optimizing, measure. Don't guess which component re-renders.
+
+1. Open React DevTools Profiler, record, do the slow interaction (scroll, type), stop. Components that flash on every commit are your targets.
+2. Highlight updates / the Profiler's "why did this render" tells you whether props, state, or context changed.
+3. `why-did-you-render` (dev-only) logs the exact prop that changed reference. Useful for the classic "new object/array literal every render" leak.
+
+With React Compiler on (SDK 54+), most manual `useMemo`/`useCallback` are redundant — but the compiler can't memoize across a virtualized list boundary, so list-row discipline still matters.
+
+The keystroke re-render storm: a search box whose `onChangeText` calls `setState` at the screen root re-renders the whole list on each character. Fix by either (a) keeping the input state local to a memoized search component and debouncing the query, or (b) deriving filtered data with a stable selector so only the list body recommits.
+
+## FlashList tuning knobs
+
+- `getItemType` — return a discriminator (`'header' | 'product' | 'ad'`). Recycling happens within a type; mixing types without it forces remeasures.
+- `keyExtractor` — stable domain id, never index.
+- Disable entry/layout animations on the **initial** mount — rows can flash into the wrong position for a split second when mounted while animations run.
+- Keep `renderItem` pure: no inline closures, no inline style objects, memoized row component.
+- For images, use a caching image component and fixed dimensions so layout doesn't thrash during scroll.
+
+## Reanimated thread model
+
+- Worklets run on the **UI thread**; shared values mutate there without a JS round-trip, so motion survives a busy JS thread.
+- A worklet calling a plain JS function crashes — cross back only via `runOnJS(fn)(...args)`, and only at the boundary (gesture end, completion callback).
+- Build gesture objects in `useMemo`; a fresh object each render reattaches the recognizer and drops in-flight touches.
+- Reanimated 4 needs the New Architecture / RN 0.76+. Reanimated 4 CSS animations cover simple declarative motion; reserve worklets for gesture-driven or physics-based animation.
+
+## Hermes crash triage
+
+- Read Hermes stack traces bottom-up; the meaningful JS frame usually sits just above the native bridge frames.
+- Symbolicate release crashes against the matching source map — an un-symbolicated trace is just addresses.
+- A red screen citing the interop layer under Fabric almost always means an old-architecture dependency. Update it or replace it with a New-Arch-ready package. Do not set `newArchEnabled: false` — it is a no-op on RN 0.82+/SDK 55 and only hides the cause.
+
+## Platform-divergence checklist
+
+When something works on one platform and breaks on the other, walk this before guessing:
+
+1. Is there a `.ios.tsx`/`.android.tsx` fork or a `Platform.select` branch diverging behavior?
+2. `KeyboardAvoidingView` behavior prop — `padding` (iOS) vs `height`/none (Android)?
+3. Safe-area insets — hardcoded padding that only fits one device family?
+4. Permissions — declared in `Info.plist` (iOS) and `AndroidManifest.xml` (Android), requested at runtime on both?
+5. A native dependency that ships only one platform's implementation, or differs in New-Arch readiness?
+6. Shadow/elevation — `shadow*` (iOS) vs `elevation` (Android) styled separately?
+7. Default font, line height, and ripple/highlight feedback differ — is the divergence cosmetic and expected, or a real bug?

package/skills/shared/react-native/scripts/verify.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static hygiene/currency check for the react-native skill content.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]    # defaults to the skill dir (this script's parent's parent)
+#
+# Greps SKILL.md + references/ for currency and brand-hygiene violations and prints each hit
+# with a fix hint. Read-only: never edits a file. On a clean tree — or a target with no
+# SKILL.md at all — it prints an ok line and exits 0 (no false failure). Exits 1 only when a
+# violation is present, so it doubles as a non-blocking lint signal.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TARGET="${1:-$(dirname "$SCRIPT_DIR")}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf '%serror:%s target path %s does not exist.\n' "$RED" "$RESET" "$TARGET" >&2
+  exit 2
+fi
+
+SKILL="$TARGET/SKILL.md"
+
+# Empty/clean target with no skill content: nothing to check, succeed.
+if [ ! -f "$SKILL" ]; then
+  printf '%s[ ok ]%s no SKILL.md under %s — nothing to check.\n' "$GREEN" "$RESET" "$TARGET"
+  exit 0
+fi
+
+findings=0
+
+flag() { # message + matching lines
+  findings=1
+  printf '%s[finding]%s %s\n' "$YELLOW" "$RESET" "$1"
+  [ -n "${2:-}" ] && printf '%s\n' "$2" | sed 's/^/    /'
+  return 0 # never let a message-only finding trip set -e and skip the remaining checks
+}
+
+md_files() { # SKILL.md + every references/*.md
+  printf '%s\n' "$SKILL"
+  [ -d "$TARGET/references" ] && find "$TARGET/references" -name '*.md' 2>/dev/null || true
+}
+
+# 1) No currency regression: never recommend disabling the New Architecture.
+hits="$(grep -REn -- 'newArchEnabled:[[:space:]]*false' $(md_files) 2>/dev/null \
+        | grep -Eiv 'no-op|never|do not|don.t|dodge|hides' || true)"
+[ -n "$hits" ] && flag "newArchEnabled:false recommended -> New Arch is mandatory (RN 0.82+/SDK 55); fix the bug instead" "$hits"
+
+# 2) The performance section must not push FlatList without the FlashList threshold.
+if grep -qiE 'FlatList' "$SKILL" 2>/dev/null; then
+  if ! grep -qiE 'FlashList' "$SKILL" 2>/dev/null; then
+    flag "SKILL.md mentions FlatList but never FlashList -> add the FlashList migration threshold"
+  fi
+fi
+
+# 3) Every fenced code block must be language-tagged (no bare ``` opener).
+#    Count fence lines; opener lines (odd occurrences) must carry a language token.
+bare="$(grep -nE '^```[[:space:]]*$' "$SKILL" 2>/dev/null || true)"
+if [ -n "$bare" ]; then
+  # A bare ``` is a violation only if it is an opener. Heuristic: flag any bare fence that
+  # is immediately followed (within the file) by indented/code-looking content is hard in
+  # sh; simplest correct rule for catalog skills: openers must be tagged, closers are bare. So a
+  # bare fence is fine as a CLOSER. We detect unbalanced/untagged openers by checking that
+  # the number of tagged openers + bare closers is consistent. Practical check: ensure no
+  # two consecutive bare fences (which would mean an untagged opener+closer pair).
+  prev_bare=""
+  while IFS= read -r line; do
+    case "$line" in
+      '```'|'``` ') cur_bare="yes" ;;
+      '```'*) cur_bare="no" ;;
+      *) continue ;;
+    esac
+    if [ "$cur_bare" = "yes" ] && [ "$prev_bare" = "yes" ]; then
+      flag "two consecutive bare \`\`\` fences -> the opener is untagged; tag it (e.g. \`\`\`tsx)"
+      break
+    fi
+    prev_bare="$cur_bare"
+  done < "$SKILL"
+fi
+
+# 4) Description shape: a "Use when/to" lead, a NOT-boundary, and no keyword trigger list
+#    (the model matches by meaning; a phrase list is per-turn cost for every install).
+desc="$(grep -m1 -E '^description:' "$SKILL" 2>/dev/null || true)"
+if [ -n "$desc" ]; then
+  printf '%s' "$desc" | grep -qE 'Use (when|to) ' || flag "description does not open with 'Use when/to'"
+  printf '%s' "$desc" | grep -qE 'NOT ' || flag "description missing a 'NOT <x> (that is <sibling>)' boundary"
+  printf '%s' "$desc" | grep -q 'Triggers:' && flag "description carries a 'Triggers:' keyword list -> delete it, the model matches by meaning" ""
+fi
+
+# 5) No cross-ref to a sibling that does not exist on disk next to this skill.
+SKILLS_ROOT="$(dirname "$TARGET")"
+refs="$(grep -hoE '\.\./[a-z0-9-]+/SKILL\.md' $(md_files) 2>/dev/null | sort -u || true)"
+if [ -n "$refs" ]; then
+  OLDIFS="$IFS"; IFS='
+'
+  for r in $refs; do
+    sib="$(printf '%s' "$r" | sed -E 's#\.\./([a-z0-9-]+)/SKILL\.md#\1#')"
+    if [ ! -f "$SKILLS_ROOT/$sib/SKILL.md" ]; then
+      flag "cross-ref to ../$sib/SKILL.md but no such sibling on disk -> remove or fix the link"
+    fi
+  done
+  IFS="$OLDIFS"
+fi
+
+if [ "$findings" -eq 0 ]; then
+  printf '%s[ ok ]%s react-native skill content passes hygiene/currency checks.\n' "$GREEN" "$RESET"
+  exit 0
+fi
+
+printf '%s[note]%s findings above are advisory; fix before shipping the skill.\n' "$RED" "$RESET"
+exit 1

package/skills/shared/redis/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: redis
+description: "Use when using Redis or any Redis-protocol store (Valkey, ElastiCache, Upstash, Dragonfly, Memorystore) as a cache, queue, rate limiter or distributed lock and it has to be CORRECT rather than merely connected — stampede-proof caching, locks that cannot release someone else's hold, race-free rate limits, and jobs that survive a worker crash. NOT durable SQL queues with SELECT FOR UPDATE SKIP LOCKED (that is `postgresdb`), NOT vector similarity search over embeddings (that is `vector-db`)."
+tags: [redis, valkey, cache, rate-limiting, distributed-locks, queues, bullmq, streams, lua, data-infra]
+recommends: [postgresdb, vector-db, clickhouse-analytics, scaling, nodejs, fly-io]
+profiles: []
+origin: ai-hub
+---
+
+# Redis — cache, lock, rate limiter, queue done correctly
+
+Redis is four primitives wearing one server: a **cache**, a **distributed lock**, a **rate
+limiter**, and a **job queue**. Each has a correctness contract that has nothing to do with
+whether `SET` returns `OK`. You almost certainly already "have Redis working" — a value goes
+in, a value comes out. What you do not yet have is a cache that won't stampede your database, a
+lock that won't release someone else's hold, a rate limiter that survives concurrent requests,
+and a queue whose jobs aren't silently lost when a worker dies. This skill is engine- and
+pattern-level, **client-SDK-agnostic**: examples are `redis-cli` and Lua, so they hold across
+node-redis, ioredis, redis-py, go-redis, and Lettuce. Every pattern applies unchanged to Valkey
+and any Redis-protocol store, since Valkey is a BSD fork of Redis 7.2 and stays protocol-compatible.
+
+## When to use / When NOT
+
+**Use when you are:**
+
+- Adding or reviewing a **cache**: TTL strategy, cache-aside vs write-through, key naming,
+  stampede/thundering-herd prevention, negative caching, invalidation.
+- Building a **distributed lock**: "only one worker does X", cron de-duplication, leader-ish
+  mutual exclusion — the `SET NX PX` + Lua-release + fencing-token contract, and the Redlock call.
+- Building a **rate limiter**: per-user/IP/API-key throttling (fixed window, sliding-window log,
+  sliding-window counter, token bucket) and why naive `INCR`+`EXPIRE` is a race.
+- Running a **queue / background jobs on Redis**: Lists vs Streams vs a library (BullMQ, Sidekiq,
+  RQ, Celery), at-least-once delivery, acks, stalled-job recovery, idempotency.
+- Deciding **eviction & persistence**: `maxmemory-policy`, RDB vs AOF, cache mode vs database mode.
+- Reviewing Redis code for foot-guns: `KEYS *`, unbounded keys, non-atomic read-modify-write,
+  missing TTL, a lock released by the wrong owner.
+
+**NOT for (route instead):**
+
+- Durable SQL queue (`SELECT … FOR UPDATE SKIP LOCKED`), engine-level SQL caching →
+  [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md). Boundary: if the *durable store* is the
+  queue, that's postgresdb; if *Redis* is the queue, you're here.
+- Vector similarity / semantic search as the primary job →
+  [`../vector-db/SKILL.md`](../vector-db/SKILL.md). Redis 8 vector sets are only *noted* here.
+- Analytical / clickstream event store → [`../clickhouse-analytics/SKILL.md`](../clickhouse-analytics/SKILL.md).
+- System-level capacity / load strategy, and app/CDN/HTTP-layer caching (Cache-Control, ISR, edge) →
+  [`../scaling/SKILL.md`](../scaling/SKILL.md). This skill owns the Redis-specific data contract underneath.
+- Provisioning a managed Redis (cluster sizing, dashboards) →
+  [`../fly-io/SKILL.md`](../fly-io/SKILL.md) / [`../aws-essentials/SKILL.md`](../aws-essentials/SKILL.md).
+  This skill gives the client-side contract, not console clicks.
+- Language-runtime async/job concepts unrelated to Redis → [`../nodejs/SKILL.md`](../nodejs/SKILL.md)
+  or your language skill.
+
+## Non-negotiables
+
+1. **Every cache key has a TTL.** No TTL in a cache = a memory leak that eventually evicts or 500s.
+2. **Never `KEYS *` in production — use `SCAN`.** `KEYS` is O(N) and blocks the single thread;
+   one bad pattern freezes every client.
+3. **Read-modify-write must be atomic.** App-side `GET` then `SET`/`INCR` races under concurrency.
+   Use one Lua `EVAL`, a single atomic command, or `WATCH`/`MULTI`.
+4. **A lock = random token + `PX` + Lua compare-and-delete.** Plain `DEL` releases whoever holds it
+   now (maybe not you); a lock with no `PX` is held forever if the owner crashes.
+5. **Pick `maxmemory-policy` deliberately.** The default `noeviction` makes a full cache fail every
+   write — correct for a database, fatal for a cache.
+6. **A queue must ack and recover.** `RPOP` straight into a worker loses the job if the worker dies
+   mid-task; use a processing list or Streams consumer groups.
+7. **Cap unbounded structures.** Lists grow forever without `LTRIM`; streams without `MAXLEN ~`.
+8. **One Lua = one short atomic step.** Redis is single-threaded; a long script or huge `MULTI/EXEC`
+   blocks *all* clients, not just yours.
+9. **Namespace keys** as `svc:entity:id` (e.g. `cart:user:42`) so scans, eviction, and humans can reason.
+10. **Know cache vs database durability before choosing persistence.** Cache = lose-it-and-rebuild;
+    database = RDB/AOF and `noeviction`. Decide which Redis is *before* you tune it.
+
+## Decision table — which primitive, which structure
+
+| Need | Structure | Canonical commands | The one gotcha |
+| --- | --- | --- | --- |
+| Cache | string / hash + TTL | `SET k v EX 300` / `GETEX` / `HSET`+`EXPIRE` | stampede on expiry |
+| Lock | string + random token | `SET k tok NX PX 30000` + Lua compare-and-`DEL` | wrong-owner release |
+| Rate limit | string / zset / hash | one atomic `EVAL` (window/log/bucket) | lost `EXPIRE` → immortal counter |
+| Queue (simple) | list | `LMOVE src proc LEFT RIGHT` / `BRPOPLPUSH` | job loss on crash without a processing copy |
+| Queue (reliable) | stream | `XADD` / `XREADGROUP` / `XACK` / `XAUTOCLAIM` | unacked PEL grows unbounded |
+
+## Caching
+
+**Namespace + TTL with jitter.** A fixed TTL on a batch of keys written together synchronizes their
+expiry — they all die in the same second and stampede the origin at once. Add jitter.
+
+```bash
+# Bad: 1000 keys warmed in a loop with the same TTL all expire together
+SET product:42 "$json" EX 300
+# Good: spread expiry with per-key jitter (300s ± up to 60s)
+SET product:42 "$json" EX $(( 300 + RANDOM % 60 ))
+```
+
+**Cache-aside (read path).** *Why:* it is the default for read-heavy data; the trap is forgetting
+the TTL and forgetting to cache the miss.
+
+```text
+# Bad: cache only hits, never the miss → every request for an absent id hits the DB
+val = GET product:42
+if val == nil: val = db.fetch(42); SET product:42 val EX 300   # absent rows still hammer the DB
+
+# Good: cache-aside with negative caching
+val = GET product:42
+if val == "__MISS__": return null                              # cached miss, no DB call
+if val == nil:
+    val = db.fetch(42)
+    if val == null: SET product:42 "__MISS__" EX 30            # short negative TTL
+    else:           SET product:42 val EX 300
+```
+
+**Stampede prevention.** When a hot key expires, N concurrent requests all miss and hammer the
+origin. Two mitigations:
+
+- **Recompute lock** — one request rebuilds, the rest briefly serve stale or wait. *The lock TTL
+  must exceed worst-case origin latency*, or two requests rebuild anyway.
+
+  ```bash
+  # On miss, try to claim the rebuild; only the winner recomputes
+  SET product:42:lock 1 NX PX 5000   # 5s > slowest DB rebuild
+  # winner: rebuild, SET product:42, then DEL product:42:lock
+  # losers: serve last-known value or retry after a short sleep
+  ```
+
+- **Probabilistic early expiration (XFetch)** — refresh *before* TTL with rising probability so one
+  request renews early while others still hit a warm key. Math + write-through/read-through/
+  write-behind in [`references/caching.md`](references/caching.md).
+
+**Invalidation:** on write, either delete the key (next read rebuilds) or write-through. Never rely on
+manual invalidation *instead of* a TTL — you will miss a path and serve stale forever.
+
+## Distributed locks
+
+```bash
+# Bad: GET-then-DEL races — between your GET and DEL the lock can expire and a NEW owner takes it,
+#      and your DEL frees THEIR lock.
+GET resource:lock        # == my token?
+DEL resource:lock        # ← may delete someone else's lock
+
+# Good: claim with a random token + PX, release only if the token is still mine (atomic Lua).
+SET resource:lock "$TOKEN" NX PX 30000     # NX = only if absent; PX = auto-expire so a crash frees it
+```
+
+Release **must** be a compare-and-delete in one Lua step:
+
+```lua
+-- KEYS[1] = lock key, ARGV[1] = my token. Returns 1 if I held and released it, else 0.
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+else
+  return 0
+end
+```
+
+**TTL vs work duration.** If the protected work can outlast `PX`, the lock expires mid-task and a
+second worker starts. Either size `PX` above the worst case, or run a watchdog that renews the TTL
+(again via a token-checked Lua `PEXPIRE`) while work continues — never blindly `PEXPIRE`.
+
+**Fencing tokens.** A GC pause or a long syscall can freeze the lock holder *past* expiry; another
+worker acquires, then the paused one wakes and writes — both think they hold the lock. The only fix
+is a **fencing token**: a monotonically increasing number issued with the lock and checked by the
+protected resource, which rejects any write carrying a stale token. No Redis lock alone provides this.
+
+> **Redlock decision.** Single-instance `SET NX PX` is fine when occasional double-execution is
+> *tolerable* (idempotent work, best-effort cron de-dup). For *hard* mutual exclusion, a single
+> Redis lock is not enough and multi-instance Redlock is contested (it assumes bounded clock drift
+> and no long pauses) — **fence the resource or use a lease/consensus system**. Full Redlock
+> walk-through and critique in [`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md).
+
+## Rate limiting
+
+```text
+# Bad: GET/INCR then EXPIRE as two steps. If the process dies (or loses the race) between INCR and
+#      EXPIRE, the key has NO TTL and counts forever — the user is throttled permanently.
+n = INCR rl:user:42
+if n == 1: EXPIRE rl:user:42 60     # ← may never run
+```
+
+Fixed window, done atomically in one `EVAL`:
+
+```lua
+-- KEYS[1] = counter, ARGV[1] = limit, ARGV[2] = window seconds. Returns 1 = allow, 0 = deny.
+local n = redis.call('INCR', KEYS[1])
+if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[2]) end   -- TTL set atomically with the first hit
+if n > tonumber(ARGV[1]) then return 0 end
+return 1
+```
+
+Fixed window allows up to 2× the limit across a boundary. For smoother limits:
+
+- **Sliding-window log** — a sorted set scored by timestamp, pruned and counted in one Lua:
+  `ZREMRANGEBYSCORE` (drop entries older than the window) → `ZCARD` (count) → `ZADD` (record now) →
+  `EXPIRE`. Exact, but O(requests) memory per key.
+- **Token bucket** — a hash holding `{tokens, last_refill}`; refill by elapsed time and decrement,
+  all in one Lua. Allows bursts up to bucket size, then a steady rate. Smallest memory.
+
+Choose by accuracy-vs-memory; full Lua for all four in
+[`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md).
+
+## Queues
+
+| Option | When | Acks / recovery |
+| --- | --- | --- |
+| **List** | simplest at-least-once, low volume | manual: processing list + requeue stalled |
+| **Stream** | reliable jobs, consumer groups, native acks | `XACK` + `XAUTOCLAIM` for stalled/pending |
+| **Library** (BullMQ/Sidekiq/RQ/Celery) | you want retries, scheduling, a dashboard | built-in; don't hand-roll |
+
+**Reliable list:** never `RPOP` straight into the worker — a crash mid-task loses the job. Move it to
+a per-worker processing list atomically, then ack by removing it.
+
+```bash
+job=$(redis-cli LMOVE jobs jobs:proc:w1 LEFT RIGHT)   # atomic: pop from jobs, push to processing
+# ... do work (idempotently) ...
+redis-cli LREM jobs:proc:w1 1 "$job"                  # ack: remove from processing
+# a reaper requeues anything left in jobs:proc:* after a worker dies
+```
+
+**Streams (preferred for reliable jobs):** consumer groups give per-message acks and a Pending
+Entries List for recovery.
+
+```bash
+redis-cli XGROUP CREATE jobs g1 '$' MKSTREAM
+redis-cli XREADGROUP GROUP g1 worker1 COUNT 10 BLOCK 5000 STREAMS jobs '>'
+# ... process ...
+redis-cli XACK jobs g1 "$id"                          # ack a done message
+redis-cli XAUTOCLAIM jobs g1 worker2 60000 0          # reclaim messages idle > 60s (stalled worker)
+```
+
+Delivery is **at-least-once**: a message can be reprocessed after a crash, so make handlers
+idempotent (dedupe on a job id / idempotency key). Reach for **BullMQ** (TypeScript; stalled-job lock
+renewal via `lockDuration`/`lockRenewTime`), **Sidekiq** (Ruby), or **RQ**/**Celery** (Python) when
+you want retries, delays, and a dashboard — don't reinvent them. Full implementations, DLQ, and the
+library comparison in [`references/queues.md`](references/queues.md).
+
+## Eviction & persistence
+
+| `maxmemory-policy` | Behavior | Use for |
+| --- | --- | --- |
+| `noeviction` (default) | writes fail when full | Redis-as-database (durable data you can't drop) |
+| `allkeys-lru` / `allkeys-lfu` | evict any key by recency / frequency | a pure cache (every key is disposable) |
+| `volatile-lru` / `volatile-ttl` / `volatile-lfu` | evict **only keys that have a TTL** | mixed: durable keys without TTL stay |
+
+A "cache" running `noeviction` with no TTLs is a memory leak that starts 500ing writes when full —
+the single most common Redis incident. Set `maxmemory` *and* an `allkeys-*` policy for a cache.
+
+**Persistence:** RDB = periodic point-in-time snapshots (fast restart, can lose the last interval);
+AOF = append every write (durable, slower, larger). A pure cache often needs *neither* — losing it
+just rebuilds from the origin. Decide cache-mode vs database-mode first, then persistence follows.
+
+## Anti-patterns → STOP
+
+| Rationalization | What actually happens | Do instead |
+| --- | --- | --- |
+| "`INCR` then `EXPIRE` is fine" | a lost `EXPIRE` leaves a TTL-less counter → immortal throttle | one atomic `EVAL` (set TTL when `n == 1`) |
+| "I'll `GET` then `DEL` the lock" | races; frees a *different* owner's lock | random token + Lua compare-and-delete |
+| "`KEYS user:*` to find my keys" | O(N), blocks the single thread, freezes all clients | `SCAN MATCH user:* COUNT 100` |
+| "No TTL, I'll invalidate manually" | you miss a path → stale forever + unbounded memory | TTL on every cache key, always |
+| "Redlock means the lock is safe" | a GC pause double-acquires; clock-drift assumptions | fence the resource, or accept double-run on idempotent work |
+| "`RPOP` the job into the worker" | worker dies mid-task → job vanishes | `LMOVE` to a processing list, or Streams + `XACK` |
+| "Big `MULTI` / long Lua = throughput" | single thread blocks every client for the duration | keep each atomic step short; chunk the work |
+| "Fixed-window limiter is exact" | allows ~2× the limit across the window boundary | sliding-window log or token bucket if exactness matters |
+
+## Quick reference
+
+```bash
+# Cache:      SET k v EX 300 | GETEX k EX 300 | DEL k | SCAN 0 MATCH 'product:*' COUNT 100
+# Lock:       SET k tok NX PX 30000  (release via the Lua compare-and-delete above)
+# Rate limit: EVAL "<lua>" 1 rl:user:42 100 60   (limit 100 / 60s)
+# Queue:      LMOVE jobs jobs:proc LEFT RIGHT | LREM jobs:proc 1 "$job"
+#             XADD jobs '*' field v | XREADGROUP ... | XACK | XAUTOCLAIM
+
+# Diagnostics (read-only):
+redis-cli INFO memory          # used_memory, maxmemory, evicted_keys
+redis-cli --bigkeys            # find the keys eating your memory
+redis-cli SLOWLOG GET 10       # slowest recent commands
+redis-cli OBJECT FREQ mykey    # access frequency (needs allkeys-lfu)
+redis-cli MEMORY USAGE mykey   # bytes for one key
+redis-cli SCAN 0 MATCH 'sess:*' COUNT 100   # never KEYS in prod
+```
+
+`scripts/verify.sh` scans your project for the high-confidence foot-guns (`KEYS *` in source,
+lock release without a token compare, `INCR` with no `EXPIRE`, `maxmemory` with no policy). It is
+read-only, never connects to a server, and exits 0 when no Redis usage is found.
+
+## Project grounding
+
+Record this project's Redis decisions in `02-DOCS/wiki/stack/redis.md` (recorded, not gated — same
+convention `postgresdb` uses): which primitive(s) you run, the `maxmemory-policy`, persistence
+(RDB/AOF/none), the client library, and any lock/rate-limit Lua you depend on. Future agents read
+this before touching the cache.
+
+## See Also
+
+- [`references/caching.md`](references/caching.md) — read/write-through, write-behind, XFetch math, negative caching, hot/big keys.
+- [`references/locks-and-rate-limiting.md`](references/locks-and-rate-limiting.md) — full Redlock + critique + fencing, watchdog renewal, all four rate-limit algorithms with Lua.
+- [`references/queues.md`](references/queues.md) — full reliable-list + Streams implementations, `XAUTOCLAIM` recovery, DLQ, BullMQ/Sidekiq/RQ/Celery detail, idempotency.
+- Siblings: [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md) · [`../vector-db/SKILL.md`](../vector-db/SKILL.md) · [`../scaling/SKILL.md`](../scaling/SKILL.md) · [`../clickhouse-analytics/SKILL.md`](../clickhouse-analytics/SKILL.md).

package/skills/shared/redis/evals/README.md

@@ -0,0 +1,10 @@
+# redis — evals
+
+`cases.yaml` holds the routing and capability checks for this skill. `should_trigger` are prompts
+that must select `redis` (including the non-obvious lost-EXPIRE race and the `KEYS *` review trigger);
+`should_not_trigger` are near-neighbours that must route to a named sibling (`postgresdb`, `vector-db`,
+`fly-io`, `nextjs`, `clickhouse-analytics`) so the boundary is exercised, not just the centre. The
+`capability` case is a three-bug scenario (stampede + lock + rate limiter) graded against the
+`must_include` rubric. There is no automated runner here — feed each prompt to the skill-router under
+test and confirm the selection, then judge the capability answer against its rubric by hand (or with an
+LLM judge). Keep prompts phrased like a real developer would ask, not as keyword bait.

package/skills/shared/redis/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: redis
+
+should_trigger:
+  - prompt: "Our product cache key expires and the database gets hammered by a flood of concurrent requests until it's rebuilt."
+    why: Cache stampede / thundering herd — the core caching correctness contract this skill owns.
+  - prompt: "Two cron workers across our instances sometimes run the same nightly job. I need only one to actually do it."
+    why: Distributed lock / mutual exclusion — SET NX PX + Lua release + the de-dup decision.
+  - prompt: "My rate limiter occasionally lets bursts through and some users get throttled forever. I do INCR then EXPIRE in the app."
+    why: Non-obvious — the lost-EXPIRE race that leaves a TTL-less immortal counter, the canonical rate-limit foot-gun.
+  - prompt: "BullMQ jobs keep getting marked stalled and reprocessed. How do the job locks and lockRenewTime work?"
+    why: Redis queue reliability and stalled-job lock renewal — at-least-once + idempotency territory.
+  - prompt: "A reviewer flagged `KEYS user:*` in our request hot path. Is that actually a problem?"
+    why: Non-obvious ops foot-gun — KEYS is O(N) and blocks the single thread; route to SCAN. Review trigger.
+  - prompt: "Should we use Redlock or is a single SET NX PX enough for our locks? Do we need fencing tokens?"
+    why: Lock correctness decision — single-instance vs Redlock vs fencing for hard mutual exclusion.
+  - prompt: "Our Redis cache started returning OOM errors and refusing writes when memory filled up."
+    why: Eviction policy — a cache left on the default noeviction with no TTLs; route to allkeys-lru + TTL.
+
+should_not_trigger:
+  - prompt: "Build a durable background job queue in Postgres using SELECT ... FOR UPDATE SKIP LOCKED."
+    route_to: postgresdb
+    why: The durable relational store IS the queue — that's the postgresdb boundary, not a Redis queue.
+  - prompt: "Add semantic similarity search over our document embeddings with ANN indexing."
+    route_to: vector-db
+    why: Vector similarity as the primary job; Redis vector sets are only noted here, not owned.
+  - prompt: "Provision and size an ElastiCache / fly.io Redis cluster, set the node type and replicas."
+    route_to: fly-io
+    why: Provisioning and console/cluster sizing, not the client-side correctness contract.
+  - prompt: "Tune Cache-Control headers and ISR revalidation for our Next.js pages."
+    route_to: nextjs
+    why: HTTP/CDN/edge caching, not the Redis data-layer contract.
+  - prompt: "We need a high-throughput analytical store for clickstream events with columnar aggregation."
+    route_to: clickhouse-analytics
+    why: Analytical/event store, not a hot-path cache, lock, rate limiter, or queue.
+
+capability:
+  - scenario: "We have a hot product-detail cache that stampedes the DB on expiry, a cron that must run exactly once across 3 instances, and a per-API-key rate limiter built on INCR then EXPIRE. Fix all three correctly."
+    must_include:
+      - "Stampede: TTL with jitter plus a recompute-lock (SET NX) or probabilistic early expiry (XFetch); lock TTL must exceed worst-case rebuild."
+      - "Lock: SET <random-token> NX PX <ttl> released only via a Lua compare-and-delete (GET == my token then DEL); mentions TTL-vs-work-duration and fencing tokens for hard mutual exclusion."
+      - "Rate limiter: collapse INCR + EXPIRE into one atomic EVAL (or set EXPIRE only when n == 1); names the lost-EXPIRE race that creates an immortal counter."
+      - "Notes at-least-once / idempotency wherever double-execution is possible (the cron, the rate-limit edge)."
+      - "Examples stay client-agnostic (Lua / redis-cli), not tied to a single SDK."