+ ...
+
+```
+
+**How to detect active stories for a pet:** In `stories.ts`, add a query:
+```typescript
+hasActiveStory: protectedProcedure
+ .input(z.object({ petId: z.string() }))
+ .query(async ({ ctx, input }) => {
+ const count = await ctx.prisma.story.count({
+ where: {
+ petId: input.petId,
+ expiresAt: { gt: new Date() }, // lazy-delete filter (D-07)
+ },
+ });
+ return { hasActiveStory: count > 0 };
+ }),
+```
+
+### Pattern 6: Optimistic Follow/Unfollow
+
+**What:** TanStack Query v5 optimistic update pattern. Immediate UI toggle; revert on server error.
+
+```typescript
+// Source: TanStack Query v5 optimistic updates pattern
+const utils = trpc.useUtils();
+
+const followMutation = trpc.follows.create.useMutation({
+ onMutate: async ({ followerPetId, followeePetId }) => {
+ await utils.follows.isFollowing.cancel({ followerPetId, followeePetId });
+ const prev = utils.follows.isFollowing.getData({ followerPetId, followeePetId });
+ utils.follows.isFollowing.setData({ followerPetId, followeePetId }, true);
+ return { prev };
+ },
+ onError: (_err, _vars, context) => {
+ utils.follows.isFollowing.setData(
+ { followerPetId: context!.prev, followeePetId: context!.prev },
+ context?.prev
+ );
+ toast.error("Something went wrong. Try again.");
+ },
+ onSettled: () => {
+ utils.follows.isFollowing.invalidate();
+ },
+});
+```
+
+### Anti-Patterns to Avoid
+
+- **SQL fan-out feed query:** Never do `SELECT posts.* FROM posts JOIN follows ON ... WHERE follows.followerPetId = ?`. This is O(following count) per feed load and blows up under load. Redis sorted set is the correct pattern for Phase 2 forward.
+- **Blocking in Redis:** Don't track blocks in Redis. Blocks are infrequent and safety-critical — they must be authoritative in PostgreSQL. Apply block filter at Prisma hydration time.
+- **Stories as posts with TTL:** The Phase 1 architecture research explicitly warns against this. Stories live in their own `stories` table — not as `Post` records with `type: 'STORY'`.
+- **Synchronous fan-out in request cycle for large follow graphs:** Phase 2's fan-out is synchronous (acceptable at v1 scale). The CONTEXT.md notes this is a Claude's Discretion area — if the project grows past ~10k follower pets, move fan-out to a background queue.
+- **Owner ID in the social graph:** Follow, Block, Report all reference `petId` — never `ownerId`. The social graph is pet-to-pet exclusively.
+- **OFFSET pagination:** Never use SQL OFFSET for feed pagination. Use cursor (timestamp from Redis score).
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Photo carousel with swipe | Custom scroll component | shadcn Carousel (Embla) | Embla handles touch events, keyboard nav, momentum scrolling, accessibility; 6 kB gzipped |
+| Intersection Observer boilerplate | Manual ref + observer lifecycle | `react-intersection-observer` `useInView` | Handles observer lifecycle, cleanup, threshold config correctly |
+| Redis client for serverless | Node.js `ioredis` | `@upstash/redis` (already installed) | ioredis uses TCP; Upstash uses HTTP — TCP connections don't survive Vercel serverless cold starts |
+| Story expiry daemon | Cron job in Next.js | Supabase `pg_cron` (D-07) | Next.js serverless functions cannot maintain persistent timers; pg_cron runs in Postgres |
+| Image aspect ratio enforcement | CSS calc + padding tricks | Tailwind `aspect-video`, `aspect-square`, `max-h-[560px] object-cover` | Native CSS aspect-ratio is universally supported; no JS needed |
+| Unique follow constraint | Application-level check | Prisma `@@id([followerPetId, followeePetId])` | Composite primary key is the correct layer for deduplication |
+| Story view deduplication | Application-level check | Prisma `@@id([storyId, viewerPetId])` + upsert | Same principle — constraint at DB layer |
+
+**Key insight:** The Phase 1 upload pipeline (`createSignedUploadUrl` → client XHR PUT → `confirmUpload`) is the complete, security-reviewed solution for all media uploads in Phase 2. Do not build a new upload path for posts or stories — extend the existing one with a different storage key prefix and path validation.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Redis ZRANGE `withScores` Returns Interleaved Array
+
+**What goes wrong:** `redis.zrange(..., { withScores: true })` returns a flat interleaved array: `[member1, score1, member2, score2, ...]` in older Redis clients. With `@upstash/redis` 1.38.0, the result is an array of `{ member, score }` objects.
+
+**Why it happens:** Confusion between raw Redis protocol (interleaved) and the `@upstash/redis` typed wrapper behavior.
+
+**How to avoid:** Cast the result as `Array<{ member: string; score: number }>` and use `.member` / `.score`. Verify by running `typeof results[0]` in a test.
+
+**Warning signs:** TypeScript type errors on `results[0]` when trying to access `.member`.
+
+### Pitfall 2: Redis ZRANGE `byScore` with `rev: true` requires `max` before `min`
+
+**What goes wrong:** `zrange(key, minScore, maxScore, { byScore: true, rev: true })` returns empty — argument order is reversed.
+
+**Why it happens:** Standard `ZRANGE` with `REV` expects (max, min) not (min, max). When `rev: true`, the upper bound (higher score = newer timestamp) must be the first positional argument.
+
+**How to avoid:** Always use `zrange(key, maxScore, minScore, { byScore: true, rev: true, ... })` — first arg is the higher value when reversing.
+
+**Warning signs:** Feed returns zero results despite Redis containing data.
+
+### Pitfall 3: Prisma Self-Referential Relation Naming
+
+**What goes wrong:** Prisma throws `Error: The relation "Follow" is ambiguous` when two relations point to the same model without disambiguation.
+
+**Why it happens:** Prisma requires unique relation names when a model has more than one relation to the same target model.
+
+**How to avoid:** Use explicit named relations: `@relation("Follower")` and `@relation("Followee")` on the `Follow` join model. Match the names on both sides of the relation.
+
+**Warning signs:** `npx prisma validate` error about ambiguous relation names.
+
+### Pitfall 4: Supabase Storage `confirmUpload` key validation must match new prefix
+
+**What goes wrong:** Posting images fails because `confirmUpload` in Phase 1 validates `z.string().startsWith('avatars/')`. Post uploads use `posts/` prefix — the existing validation rejects them.
+
+**Why it happens:** The `posts.create` mutation must implement its own `confirmUpload` or the `media.confirmUpload` must be extended to accept `posts/` keys.
+
+**How to avoid:** Create a dedicated `posts.confirmUpload` with `z.string().startsWith('posts/')` validation, parallel to the existing avatar flow. Do not relax the `avatars/` constraint on `media.confirmUpload`.
+
+**Warning signs:** `BAD_REQUEST` error from `confirmUpload` when trying to save a post image key.
+
+### Pitfall 5: Story `expiresAt` Timezone Mismatch
+
+**What goes wrong:** Stories appear expired in the UI even within the 24-hour window, or conversely stay visible after 24 hours.
+
+**Why it happens:** Comparing `new Date()` (local timezone) against Postgres `TIMESTAMP WITH TIME ZONE` values when the Prisma client or Supabase connection is not set to UTC.
+
+**How to avoid:** Always store `expiresAt` as `new Date(Date.now() + 24 * 60 * 60 * 1000)` in UTC. Supabase Postgres uses UTC by default. Verify with `SELECT NOW()` in Supabase Studio — should return UTC time.
+
+**Warning signs:** Off-by-hours story visibility bugs; stories visible for 26 hours in one timezone.
+
+### Pitfall 6: tRPC `useInfiniteQuery` Requires `cursor` Input Field
+
+**What goes wrong:** `trpc.feed.getFeed.useInfiniteQuery(...)` TypeScript error — the hook is not available on the procedure.
+
+**Why it happens:** tRPC v11 only exposes `useInfiniteQuery` on procedures whose input schema includes a field named exactly `cursor` (any type, nullish).
+
+**How to avoid:** Input schema must include `cursor: z.number().nullish()` (or `z.string().nullish()` if using string cursors). The field name must be `cursor` — not `after`, `page`, or `nextPage`.
+
+**Warning signs:** `Property 'useInfiniteQuery' does not exist` TypeScript error on the tRPC procedure.
+
+### Pitfall 7: Feed Hydration Order (Redis vs Prisma)
+
+**What goes wrong:** Feed posts appear in a different order than the Redis sorted set because Prisma `findMany` does not preserve the `in` array order.
+
+**Why it happens:** SQL `WHERE id IN (...)` does not guarantee result order. Prisma uses the DB's natural order unless `orderBy` is specified.
+
+**How to avoid:** After the Prisma `findMany`, sort the result array by the original `postIds` order (which reflects Redis score order). Create an `idToPost` map, then `postIds.map(id => idToPost[id]).filter(Boolean)`.
+
+**Warning signs:** Feed shows oldest post first or in arbitrary order despite Redis sorting correctly.
+
+---
+
+## Code Examples
+
+### Redis Singleton (`src/lib/redis.ts`)
+
+```typescript
+// Source: @upstash/redis npm package (verified installed 1.38.0)
+import { Redis } from "@upstash/redis";
+
+// Singleton — reuse across serverless function invocations
+export const redis = new Redis({
+ url: process.env.UPSTASH_REDIS_REST_URL!,
+ token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+```
+
+### Deduplicated Story View Upsert
+
+```typescript
+// Source: Prisma docs — upsert with composite key
+await ctx.prisma.storyView.upsert({
+ where: {
+ storyId_viewerPetId: { // composite @@id name auto-generated by Prisma
+ storyId: input.storyId,
+ viewerPetId: activePetId,
+ },
+ },
+ update: { viewedAt: new Date() }, // update timestamp on re-view
+ create: {
+ storyId: input.storyId,
+ viewerPetId: activePetId,
+ viewedAt: new Date(),
+ },
+});
+```
+
+### PostCard Story Ring Conditional Classes
+
+```typescript
+// Source: 02-UI-SPEC.md design contract
+// hasActiveStory: boolean — from stories.hasActiveStory query
+// allStoriesSeen: boolean — from viewer's story_views join (Phase 3 enhancement; Phase 2: always false)
+
+
+ {pet.name[0]}
+
+
+```
+
+### shadcn Carousel in PostCard (Photo Carousel)
+
+```typescript
+// Source: shadcn/ui carousel docs (verified 2026-06-07)
+import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type CarouselApi } from "@/components/ui/carousel";
+
+const [api, setApi] = useState
+
+
+ {images.map((img) => (
+
+ )
+
+ ))}
+
+
+ {/* Index indicator */}
+
+ {current} / {images.length}
+
+
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| SQL JOIN feed query (`SELECT ... FROM posts JOIN follows ...`) | Redis sorted set fan-out (pre-computed per-user inbox) | Industry standard since ~2012 (Instagram, Twitter) | Feed load is O(1) Redis lookup vs O(follower count) SQL join |
+| Long-polling for new posts | Supabase Realtime WebSocket subscription | Supabase Realtime GA 2023 | Push-based feed updates without polling (Phase 3+ enhancement; Phase 2 uses TanStack Query refetch on mutation) |
+| OFFSET pagination | Cursor-based pagination (last item's timestamp/ID as cursor) | Industry-wide shift 2018-2020 | No duplicate/missing items when new content is inserted during scroll |
+| Stories stored as posts with TTL column | Separate `stories` table with `expires_at` + lazy-delete | Social platform architecture best practice | Prevents post model pollution, enables separate view tracking, simpler query patterns |
+| Uploading binary through API server | Presigned S3/Supabase Storage URL (client direct upload) | Standard practice since 2015 | API server not a bottleneck; no binary in memory; secure by design |
+| `useEffect` + manual IntersectionObserver | `react-intersection-observer` `useInView` hook | 2021-2022 | Correct observer lifecycle management; SSR-safe |
+
+**Deprecated/outdated patterns in this stack:**
+- `Prisma.findUnique` with client-side ownership check after fetch: replaced by `assertPetOwnership` helper (established in Phase 1 `pets.ts` — copy this pattern).
+- `OFFSET` in any feed, list, or social graph query: replaced by cursor everywhere.
+- Storing media keys as full URLs in the database: Phase 1 established storing `storageKey` only; use `getAvatarUrl` / `getMediaUrl` helpers for URL construction.
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | Post images share the `pet-avatars` Supabase Storage bucket with `posts/` path prefix (rather than a separate `post-media` bucket) | Standard Stack / Pattern 4 | Low — separate bucket is trivially configured; same API surface either way |
+| A2 | `@upstash/redis` 1.38.0 ZRANGE with `{withScores: true}` returns `Array<{member, score}>` objects (not interleaved flat array) | Pattern 2 / Pitfall 1 | Medium — if interleaved, feed hydration will fail; verify in test before using |
+| A3 | Follower milestone threshold values are hard-coded as a constant array in `src/lib/milestone-thresholds.ts` (not a `milestone_thresholds` DB table) | Pattern 1 (schema) | Low — a constant array is simpler and the thresholds don't change in Phase 2; D-09 provides no preference |
+| A4 | `react-intersection-observer` is the appropriate sentinel hook (vs. native `useEffect` + `IntersectionObserver`) | Standard Stack | Low — the native API is a valid fallback; this package is widely used and [OK] verified |
+| A5 | "Seen by viewer" ring state (gray ring for all-seen stories) is computed on the client using the story viewer list — no separate `hasSeenAll` DB column | Pattern 5 | Low — Phase 2 can use `ring-orange-500` unconditionally for all active stories (UI-SPEC shows gray ring as a distinction, but it's a detail that doesn't block STORY-02) |
+
+---
+
+## Open Questions
+
+1. **Redis feed set maximum size / TTL**
+ - What we know: No explicit TTL or max size is configured on the feed sorted set.
+ - What's unclear: Should old feed entries be trimmed (ZREMRANGEBYSCORE) to prevent unbounded set growth?
+ - Recommendation: For Phase 2 at v1 scale, no trim needed. Add `ZREMRANGEBYSCORE feed:{petId} 0 {90_days_ago_ms}` in a weekly Supabase pg_cron job alongside story cleanup.
+
+2. **Story upload: photo only or photo + video in Phase 2?**
+ - What we know: STORY-01 says "photo or short video." VIDEO-01/02 is deferred to Phase 5. The UI-SPEC shows single image upload for stories.
+ - What's unclear: Should video stories be accepted in Phase 2?
+ - Recommendation: Phase 2 stories = photo only (images only via presigned upload). Story video is Phase 5 scope (same Mux transcoding pipeline as video posts). The `stories.storageKey` field accepts image keys only in Phase 2.
+
+3. **Fan-out scope: own posts in own feed?**
+ - What we know: Pattern 2 above recommends also adding the pet's own posts to `feed:{petId}` so they appear in their own feed.
+ - What's unclear: Should the feed show the poster's own posts, or only posts from followed pets?
+ - Recommendation: Include own posts in feed (industry standard: you see your own posts in your timeline). ZADD `feed:{petId}` alongside follower fan-out.
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Supabase Storage (Supabase project) | Photo/story upload | ✓ | 2.107.0 (@supabase/supabase-js) | — |
+| Upstash Redis (REST endpoint) | Feed fan-out, retrieval | ✓ | 1.38.0 (@upstash/redis) | — (env vars must be set) |
+| `UPSTASH_REDIS_REST_URL` env var | redis.ts singleton | Requires `.env.local` | — | Blocks feed if missing |
+| `UPSTASH_REDIS_REST_TOKEN` env var | redis.ts singleton | Requires `.env.local` | — | Blocks feed if missing |
+| `npx prisma migrate dev` | Schema migration | ✓ (prisma 7.8.0 installed) | 7.8.0 | — |
+| shadcn CLI (`npx shadcn@latest add`) | New UI components | ✓ (shadcn 4.10.0 in package.json) | 4.10.0 | — |
+
+**Missing dependencies with no fallback:**
+- `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` must be added to `.env.local`. The feed router will throw if these are absent. Wave 0 task must check for these.
+
+**Missing dependencies with fallback:**
+- None — all runtime dependencies are covered by Phase 1's setup.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | Vitest 4.1.8 |
+| Config file | `vitest.config.ts` (at project root) |
+| Quick run command | `npx vitest run --reporter=verbose` |
+| Full suite command | `npx vitest run --coverage` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| PHOTO-01 | `posts.create` mutation inserts Post + PostImage with correct petId | unit | `npx vitest run src/__tests__/posts.test.ts -t "create single photo"` | Wave 0 |
+| PHOTO-02 | `posts.create` rejects >10 images | unit | `npx vitest run src/__tests__/posts.test.ts -t "carousel limit"` | Wave 0 |
+| PHOTO-03 | `posts.updateCaption` requires ownership | unit | `npx vitest run src/__tests__/posts.test.ts -t "updateCaption forbidden"` | Wave 0 |
+| PHOTO-04 | `posts.delete` cascades PostImages | unit | `npx vitest run src/__tests__/posts.test.ts -t "delete cascades"` | Wave 0 |
+| STORY-01 | `stories.create` sets `expiresAt = now + 24h` | unit | `npx vitest run src/__tests__/stories.test.ts -t "expiresAt 24h"` | Wave 0 |
+| STORY-02 | `stories.hasActiveStory` filters by `expiresAt > now` | unit | `npx vitest run src/__tests__/stories.test.ts -t "hasActiveStory"` | Wave 0 |
+| STORY-03 | `stories.recordView` deduplicates (upsert) | unit | `npx vitest run src/__tests__/stories.test.ts -t "recordView dedup"` | Wave 0 |
+| MILE-01 | `milestones.create` rejects invalid milestone type | unit | `npx vitest run src/__tests__/milestones.test.ts -t "invalid type"` | Wave 0 |
+| SOCL-01 | `follows.create` inserts Follow row | unit | `npx vitest run src/__tests__/follows.test.ts -t "follow creates row"` | Wave 0 |
+| SOCL-02 | `follows.delete` removes Follow row | unit | `npx vitest run src/__tests__/follows.test.ts -t "unfollow removes row"` | Wave 0 |
+| SOCL-03 | `follows.listFollowers` scoped by petId | unit | `npx vitest run src/__tests__/follows.test.ts -t "listFollowers scoped"` | Wave 0 |
+| FEED-01 | `feed.getFeed` returns empty for pet with no follows | unit | `npx vitest run src/__tests__/feed.test.ts -t "empty feed"` | Wave 0 |
+| FEED-01 | `feed.getFeed` cursor pagination returns nextCursor | unit | `npx vitest run src/__tests__/feed.test.ts -t "cursor pagination"` | Wave 0 |
+| SAFE-01 | `blocks.create` inserts Block; blocked pet excluded from feed | unit | `npx vitest run src/__tests__/blocks.test.ts -t "block filters feed"` | Wave 0 |
+| SAFE-02 | `reports.create` inserts Report with reason | unit | `npx vitest run src/__tests__/reports.test.ts -t "report creates row"` | Wave 0 |
+
+### Sampling Rate
+
+- **Per task commit:** `npx vitest run src/__tests__/