docs(rate-limit): clarify KV-backed persistence vs in-memory fallback

lib/rate-limit.ts

@@ -8,11 +8,17 @@ interface RateLimitResult {
 }
 
 /**
- * In-memory rate limiter to prevent basic DoS/spam (Denial of Wallet).
+ * Rate limiter to prevent basic DoS/spam (Denial of Wallet).
  *
- * Note: In a serverless environment, this resets per cold-start/instance,
- * but it is highly effective at stopping aggressive single-instance spikes.
- * For multi-instance strict syncing, a Redis store (Vercel KV/Upstash) should be used.
+ * When Upstash Redis / Vercel KV is configured (KV_REST_API_URL + KV_REST_API_TOKEN
+ * environment variables), rate limit state is persisted across restarts and shared
+ * across all serverless instances via atomic INCR + EXPIRE operations.
+ *
+ * Falls back to an in-memory TTL cache when KV is not configured. In this mode,
+ * state resets on cold start / server restart, but it is highly effective at
+ * stopping aggressive single-instance spikes during normal operation.
+ *
+ * @see https://upstash.com/docs/rate-limiting/quickstart for KV setup instructions.
  */
 export class RateLimiter {
   private cache: DistributedCache<{ count: number; resetAt: number }>;

services/github/refresh-rate-limiter.ts

@@ -5,6 +5,20 @@ interface RefreshLimitRecord {
   windowStart: number;
 }
 
+/**
+ * In-memory rate limiter for manual cache refresh operations.
+ *
+ * Limits how frequently a single IP can trigger a manual data refresh.
+ * Uses a TTL-based in-memory cache that expires entries automatically.
+ *
+ * ⚠️ Limitation: State is per-process only. In serverless deployments
+ * (Vercel, AWS Lambda), each cold start resets the limiter. This is
+ * acceptable for abuse prevention on a single instance, but not suitable
+ * for strict cross-instance rate limiting.
+ *
+ * For production deployments requiring persistent state, consider using
+ * Upstash Redis or Vercel KV by importing from '@/lib/rate-limit' instead.
+ */
 export class RefreshRateLimiter {
   private static instance: RefreshRateLimiter;