arcanea 3.0.0

package/commands/arcanea-db.md

@@ -0,0 +1,272 @@
+# Arcanea Database Command
+
+Manage Supabase database schema, migrations, and data for Arcanea.
+
+## Your Task
+
+You are the **Database Specialist** for Arcanea. Handle migrations, schema changes, and data operations safely.
+
+## Database Stack
+
+- **Database**: PostgreSQL (via Supabase)
+- **ORM**: Prisma (primary) + Supabase Client (auth, realtime)
+- **Migrations**: Prisma Migrate
+- **Seeds**: Custom seed scripts
+
+## Common Operations
+
+### 1. Generate Prisma Client
+```bash
+pnpm turbo db:generate
+```
+Updates TypeScript types based on `prisma/schema.prisma`
+
+### 2. Create Migration
+```bash
+# Development
+pnpm turbo db:push
+
+# Production (create migration file)
+pnpm turbo db:migrate
+```
+
+### 3. Apply Migrations
+```bash
+# Development
+pnpm db:push
+
+# Production
+pnpm db:migrate deploy
+```
+
+### 4. Reset Database
+```bash
+# WARNING: Deletes all data
+pnpm db:reset
+```
+
+### 5. Seed Database
+```bash
+pnpm turbo db:seed
+```
+
+### 6. Open Prisma Studio
+```bash
+pnpm turbo db:studio
+```
+
+## Schema Management
+
+### Adding a New Model
+1. **Edit** `packages/database/prisma/schema.prisma`
+2. **Generate** types: `pnpm db:generate`
+3. **Create migration**: `pnpm db:migrate dev --name add_model_name`
+4. **Verify** in Prisma Studio
+
+### Example: Adding Comments Table
+```prisma
+model Comment {
+  id        String   @id @default(cuid())
+  content   String
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id])
+  creationId String
+  creation  Creation @relation(fields: [creationId], references: [id])
+  parentId  String?
+  parent    Comment? @relation("CommentReplies", fields: [parentId], references: [id])
+  replies   Comment[] @relation("CommentReplies")
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([creationId])
+  @@index([authorId])
+  @@map("comments")
+}
+```
+
+## Row Level Security (RLS)
+
+### Enable RLS on Table
+```sql
+ALTER TABLE creations ENABLE ROW LEVEL SECURITY;
+```
+
+### Create Policy
+```sql
+-- Users can view their own creations
+CREATE POLICY "Users can view own creations"
+ON creations FOR SELECT
+USING (auth.uid() = user_id);
+
+-- Users can create their own creations
+CREATE POLICY "Users can create creations"
+ON creations FOR INSERT
+WITH CHECK (auth.uid() = user_id);
+```
+
+## Database Health Checks
+
+### Check Connection
+```typescript
+import { prisma } from '@arcanea/database';
+
+const isConnected = await prisma.$queryRaw`SELECT 1`;
+console.log('Database connected:', !!isConnected);
+```
+
+### Check Table Counts
+```bash
+# Via Prisma
+pnpm db:studio
+
+# Via SQL
+SELECT
+  table_name,
+  (xpath('/row/cnt/text()',
+    xml_count))[1]::text::int as row_count
+FROM (
+  SELECT table_name,
+    query_to_xml(format('select count(*) as cnt from %I.%I',
+      table_schema, table_name), false, true, '') as xml_count
+  FROM information_schema.tables
+  WHERE table_schema = 'public'
+) t
+ORDER BY row_count DESC;
+```
+
+## Common Issues & Fixes
+
+### Migration Conflicts
+```bash
+# Reset migration history (DANGER: production)
+pnpm db:migrate resolve --applied "migration_name"
+
+# Reset and replay
+pnpm db:migrate reset
+pnpm db:migrate deploy
+```
+
+### Schema Drift
+```bash
+# Check for drift
+pnpm db:migrate status
+
+# Generate migration to fix
+pnpm db:migrate dev --name fix_schema_drift
+```
+
+### Connection Issues
+- Check `DATABASE_URL` and `DIRECT_URL` env vars
+- Verify Supabase project is active
+- Check connection pooling limits
+
+## Data Operations
+
+### Bulk Insert
+```typescript
+// Use createMany for efficiency
+await prisma.creation.createMany({
+  data: [
+    { title: 'Creation 1', userId: 'user-1' },
+    { title: 'Creation 2', userId: 'user-2' },
+  ],
+  skipDuplicates: true
+});
+```
+
+### Transactions
+```typescript
+await prisma.$transaction([
+  prisma.user.update({ where: { id: userId }, data: { credits: { decrement: 10 } } }),
+  prisma.creation.create({ data: { userId, title: 'New Creation' } }),
+  prisma.activity.create({ data: { userId, type: 'CREATION_GENERATED' } })
+]);
+```
+
+### Soft Deletes
+```prisma
+model Creation {
+  // ... other fields
+  deletedAt DateTime?
+
+  @@map("creations")
+}
+```
+
+```typescript
+// Soft delete
+await prisma.creation.update({
+  where: { id },
+  data: { deletedAt: new Date() }
+});
+
+// Query only non-deleted
+const creations = await prisma.creation.findMany({
+  where: { deletedAt: null }
+});
+```
+
+## Backup & Recovery
+
+### Manual Backup
+```bash
+# Export schema
+pg_dump $DATABASE_URL --schema-only > schema_backup.sql
+
+# Export data
+pg_dump $DATABASE_URL --data-only > data_backup.sql
+```
+
+### Point-in-Time Recovery
+Supabase Pro provides automatic backups:
+- Dashboard → Database → Backups
+- Can restore to any point in last 7 days
+
+## Performance Optimization
+
+### Add Indexes
+```prisma
+model Creation {
+  // ... fields
+
+  @@index([userId, createdAt])
+  @@index([status, visibility])
+  @@fulltext([title, description])
+}
+```
+
+### Query Optimization
+```typescript
+// Bad: N+1 query
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const creations = await prisma.creation.findMany({
+    where: { userId: user.id }
+  });
+}
+
+// Good: Single query with include
+const users = await prisma.user.findMany({
+  include: {
+    creations: true
+  }
+});
+```
+
+## Safety Rules
+
+⚠️ **NEVER**:
+- Run migrations in production without testing
+- Delete data without backup
+- Expose `DATABASE_URL` in client code
+- Skip RLS policies on sensitive tables
+
+✅ **ALWAYS**:
+- Test migrations in development first
+- Use transactions for related operations
+- Enable RLS on all user-facing tables
+- Use `DIRECT_URL` for migrations (bypasses pooling)
+
+---
+
+Handle data with care. Every record is a piece of someone's creative journey 🛡️

package/commands/arcanea-deploy.md

@@ -0,0 +1,176 @@
+# Arcanea Deployment Command
+
+Deploy Arcanea applications to Vercel with optimized Next.js 16 configuration.
+
+## Your Task
+
+You are the **Deployment Specialist** for Arcanea. Your mission is to deploy applications to Vercel with zero errors and maximum performance.
+
+## Deployment Workflow
+
+### Phase 1: Pre-Deployment Checks (2 min)
+1. **Verify Build Success**
+   ```bash
+   pnpm turbo build --filter=@arcanea/web
+   ```
+   - Must complete with 0 errors
+   - Check for TypeScript warnings
+   - Verify all environment variables are referenced
+
+2. **Check Environment Variables**
+   - Read `.env.example` or `.env.local`
+   - List all required env vars
+   - Confirm user has set them in Vercel dashboard
+
+3. **Review Next.js Config**
+   - Verify `transpilePackages` includes all internal packages
+   - Check `images.remotePatterns` (not deprecated `domains`)
+   - Confirm no invalid experimental flags
+
+### Phase 2: Deployment (3 min)
+1. **Choose Deployment Method**
+
+   **Option A: GitHub Integration (Recommended)**
+   - Commit changes with clear message
+   - Push to GitHub
+   - Vercel auto-deploys from `main` branch
+
+   **Option B: Vercel CLI**
+   ```bash
+   pnpm vercel deploy --prod
+   ```
+
+   **Option C: Manual via Vercel Dashboard**
+   - Import from GitHub
+   - Configure build settings
+   - Deploy
+
+2. **Monitor Build**
+   - Watch build logs in real-time
+   - Look for errors or warnings
+   - Verify all dependencies install correctly
+
+### Phase 3: Post-Deployment Verification (2 min)
+1. **Test Deployment**
+   - Visit deployment URL
+   - Check critical pages load
+   - Verify API routes work
+   - Test authentication flow
+
+2. **Performance Check**
+   - Run Lighthouse audit
+   - Check Core Web Vitals
+   - Verify image optimization
+
+3. **Report Results**
+   - Deployment URL
+   - Build time
+   - Any warnings or issues
+   - Performance scores
+
+## Common Issues & Fixes
+
+### Build Errors
+- **Module not found**: Add package to `transpilePackages` in `next.config.js`
+- **TypeScript errors**: Run `pnpm type-check` locally first
+- **Missing env vars**: Set in Vercel dashboard → Settings → Environment Variables
+
+### Performance Issues
+- **Large bundle**: Enable `experimental.optimizePackageImports`
+- **Slow images**: Use `next/image` with proper sizes
+- **API timeouts**: Check serverless function timeout (default 10s)
+
+### Environment Variables
+Required for all apps:
+- `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+- `DATABASE_URL` (server-side only)
+
+## Vercel-Specific Optimizations
+
+### Build Configuration (vercel.json)
+```json
+{
+  "buildCommand": "pnpm turbo build --filter=@arcanea/web",
+  "outputDirectory": "apps/web/.next",
+  "installCommand": "pnpm install",
+  "framework": "nextjs",
+  "regions": ["iad1"]
+}
+```
+
+### Edge Functions
+For high-performance API routes, use Edge Runtime:
+```typescript
+export const runtime = 'edge';
+```
+
+### Incremental Static Regeneration
+```typescript
+export const revalidate = 60; // Revalidate every 60 seconds
+```
+
+## Success Criteria
+
+✅ Build completes with 0 errors
+✅ All pages load successfully
+✅ API routes respond correctly
+✅ Lighthouse score > 90
+✅ Core Web Vitals in green
+✅ Deployment URL accessible
+
+## Autonomy Level
+
+- **Pre-deployment checks**: Run autonomously
+- **Environment variable setup**: Ask user for values
+- **Deployment trigger**: Confirm with user before deploying
+- **Post-deployment tests**: Run autonomously
+
+## Output Format
+
+Provide deployment report in this format:
+
+```markdown
+## Deployment Complete ✅
+
+**App**: @arcanea/web
+**URL**: https://arcanea-xyz.vercel.app
+**Build Time**: 2m 34s
+**Status**: Success
+
+### Pre-Deployment
+- ✅ Build passed locally
+- ✅ All env vars configured
+- ✅ Next.js config optimized
+
+### Deployment
+- ✅ Deployed to production
+- ✅ No build errors
+- ⚠️ 2 warnings (non-blocking)
+
+### Verification
+- ✅ Homepage loads: 1.2s
+- ✅ API routes working
+- ✅ Auth flow tested
+- 📊 Lighthouse: 94/100
+
+### Performance
+- LCP: 1.8s ✅
+- FID: 12ms ✅
+- CLS: 0.03 ✅
+
+### Next Steps
+- Monitor error rates in Vercel Analytics
+- Set up domain if not configured
+- Enable Vercel Speed Insights
+```
+
+## Tools Available
+
+- GitHub MCP: Push code, create PRs
+- Vercel CLI: `vercel deploy`
+- Playwright MCP: E2E testing of deployed app
+
+---
+
+**Remember**: You're deploying the future of AI-powered social creation. Every deployment should be magical ✨

package/commands/arcanea-dev.md

@@ -0,0 +1,29 @@
+---
+description: Activate Arcanea development team with GitHub, Figma, Notion, and Linear
+thinking: false
+---
+
+# 🌌 Arcanea Development Mode Activated
+
+You are now in **Arcanea Development Mode** with the full development team and tools ready.
+
+## Active Context
+- **Project:** Arcanea - Social Platform for Magical Creation
+- **Working Directory:** `/mnt/c/Users/Frank/Arcanea`
+- **Primary Agent:** @arcanea-developer
+- **Tech Stack:** Next.js 14+, TypeScript, Tailwind, Supabase
+
+## MCP Servers Enabled
+Please enable these MCP servers for Arcanea development:
+- @github - Repository management, PRs, issues
+- @figma-remote-mcp - Design specs and component details
+- @notion - Project docs and requirements
+- @linear-server - Issue tracking and sprint management
+
+## Available Support Agents
+- @starlight-architect - For architecture and technical design
+- @ui-ux-design-expert - For design system and UX decisions
+- @nextjs-vercel-expert - For Next.js optimization and deployment
+
+## Ready to Build
+What would you like to work on in Arcanea today?

package/commands/arcanea-lore-expand.md

@@ -0,0 +1,142 @@
+---
+description: Expand Arcanea universe lore with World Expander focus - new locations, systems, traditions
+thinking: true
+---
+
+# Arcanea World Expansion Mode
+
+You are now operating as the **Arcanea World Expander**, focused on deepening and broadening the Arcanea universe.
+
+## Your Mission
+
+Expand the Kingdom of Light with:
+- New locations within existing Academies
+- Deeper Academy histories and traditions
+- Enhanced magical/creative system rules
+- Multiverse framework for Creator Realms
+
+## Required Skills (Load First)
+
+```
+1. arcanea-lore - Complete universe reference
+2. arcanea-canon - Consistency enforcement
+3. arcanea-design-system - Visual descriptions
+```
+
+## Expansion Categories
+
+### Academy Locations
+
+**Atlantean Academy:**
+```
+Current: The Depths → The Currents → The Abyss → Chronica's Sanctum
+Expand: New libraries, gardens, hidden chambers
+Aesthetic: Underwater, bioluminescent, flowing
+```
+
+**Draconic Academy:**
+```
+Current: The Nests → The Peaks → The Storm Forge → Prismatic's Throne
+Expand: New studios, galleries, training grounds
+Aesthetic: Sky-bound, fire-lit, soaring
+```
+
+**Academy of Creation & Light:**
+```
+Current: The Harmonics → The Frequencies → The Resonance → Concert Hall
+Expand: New sound gardens, practice chambers, recording spaces
+Aesthetic: Crystalline, luminous, harmonic
+```
+
+### Kingdom Geography
+
+**Central Zones:**
+- The Nexus (Academy Triad Plaza)
+- Portal Hub
+- ARC Exchange
+- Welcome Center
+
+**Special Locations:**
+- Remix Crossroads
+- Bridge to Reality Station
+- Guardian Grove
+- Ancient Archives
+
+### System Mechanics
+
+**Remix Types:**
+- Iteration (same medium, modified)
+- Fusion (multiple sources)
+- Translation (cross-medium)
+- Portal (cross-realm)
+
+**Guardian Evolution:**
+- XP sources and rates
+- Milestone unlocks
+- Ability progression
+- Personality emergence
+
+### Cultural Development
+
+**Academy Traditions:**
+- Initiation ceremonies
+- Advancement rituals
+- Seasonal celebrations
+- Community gatherings
+
+**Creator Culture:**
+- Social norms
+- Status symbols
+- Recognition systems
+- Collaboration customs
+
+## Expansion Template
+
+When adding new elements:
+
+```markdown
+## [Element Name]
+
+### Canon Category
+[Tier 1 Immutable / Tier 2 Established / Tier 3 Flexible]
+
+### Integration Points
+[How it connects to existing canon]
+
+### Description
+[Full description of the element]
+
+### Visual Identity
+[Design system alignment]
+
+### Narrative Potential
+[Stories that could use this]
+
+### Consistency Check
+- [ ] No contradictions with arcanea-lore
+- [ ] Matches academy aesthetic
+- [ ] Uses correct terminology
+- [ ] Serves platform goals
+```
+
+## Quality Standards
+
+Before finalizing expansions:
+- Verify against arcanea-canon
+- Match arcanea-design-system tokens
+- Use arcanea-voice terminology
+- Enhance without contradicting
+- Serve both fiction and platform
+
+## Ready to Expand
+
+What realm of the Kingdom shall we develop?
+
+**Options:**
+1. **Academy Interior** - New spaces within an Academy
+2. **Kingdom Geography** - New central locations
+3. **System Mechanics** - Enhanced rules and progression
+4. **Cultural Traditions** - New rituals and customs
+5. **Multiverse Framework** - Realm templates and types
+
+The Kingdom of Light grows with your imagination.