souls-directory: Instructions file for Claude Code

CLAUDE.md — Project Context for AI Assistants

Project Overview

souls.directory is a curated directory of AI personality templates ("souls") — markdown-based SOUL.md files that define how AI agents behave. Users can browse, upload, and share these personality templates.

Tech Stack

• Framework: Next.js (App Router) with TypeScript
• Styling: Tailwind CSS with custom CSS variables (grayscale, dark-mode-only theme)
• Database/Backend: Convex (NOT Supabase, NOT Prisma, NOT any SQL database)
• Auth: Convex Auth (@convex-dev/auth) with GitHub OAuth
• Package Manager: pnpm with Turborepo monorepo
• Linter: Biome (not ESLint)
• Fonts: Geist Sans + Geist Mono

Critical Rules

Database is Convex

• Queries: useQuery(api.tableName.queryName)
• Mutations: useMutation(api.tableName.mutationName)
• Schema: apps/web/convex/schema.ts
• Functions: apps/web/convex/*.ts

Auth Pattern

Always use getAuthenticatedUser(ctx) or getCurrentUser(ctx) from convex/lib/access.ts.

NEVER look up users by email via ctx.auth.getUserIdentity() — this is unreliable. The helper functions use getAuthUserId(ctx) from @convex-dev/auth/server which returns the Convex user _id directly.

No Barrel Files

Do NOT create index.ts files that re-export from multiple modules. Import directly from the specific file.

// BAD
import { SoulCard, Header } from '@/components'

// GOOD
import { SoulCard } from '@/components/souls/soul-card'
import { Header } from '@/components/layout/header'

Upload Page is Fragile

The upload wizard at apps/web/app/upload/page.tsx has been a source of repeated regressions. When modifying it:

1. Do NOT add complex state management (localStorage persistence, useReducer, etc.) without careful testing
2. Do NOT wrap handlers in unnecessary useCallback — React's FileReader async callbacks are sensitive to stale closures
3. Do NOT use <label htmlFor> for file inputs — use a <button> with explicit onClick={() => fileInputRef.current?.click()}
4. The file upload flow is:
   • User clicks button → fileInputRef.current?.click()
   • Browser shows file picker → user selects file
   • onChange fires → handleFileSelect → setFiles(prev => [...prev, ...selected])
   • normalizedFiles memo recalculates
   • useEffect reads first .md file → setContent(text)
5. Test file upload manually after ANY change to the upload page or its hooks