CLAUDE.md — BrainLab Kids
> This file is the standing instruction set for Claude Code working on BrainLab Kids. Read this before every session. Keep it honest and up to date.
---
1. What BrainLab Kids is
BrainLab Kids is a subscription learning platform for children ages 7–12 that teaches them how their own brain works through short, interactive, device-native experiments. Each experiment is called a **Lab** and lasts 5–8 minutes. Labs use the phone's camera, microphone, motion sensors, and the child's own reflexes. There are 36 Labs planned across 5 Worlds. Each Lab follows the pedagogy: **Try It → Gasp → Learn → Level Up**.
**Positioning:** *Not school. Not games. A laboratory where kids discover the most fascinating machine they'll ever own: their own mind.*
The product has three audiences in one:
- **Kids** use the Labs and talk to Neo, the AI tutor
- **Parents** read the weekly Brain Report and manage their child's experience
- **Schools and therapists** (Phase 3+) assign Labs and view anonymized class data
The business model is tiered subscription, priced by geography: Tier 1 (US/UK/GCC) $9.99, Tier 2 (LatAm/SEA/EE) $4.99, Tier 3 (South Asia/Africa) $1.99.
The product is designed, owned, and operated by Khurram Badar (Dubai-based non-technical founder) as part of the YDR Labs family of AI-powered platforms. Primary development partner is Claude Code.
---
2. The founder you're working with
- **Name:** Khurram Badar
- **Location:** Dubai, UAE
- **GitHub:** khurrambadar3125
- **Technical level:** Non-technical founder. Deep domain knowledge. Thinks in terms of markets, audiences, parent psychology. Does not write code — delegates entirely to Claude Code.
- **Work style:** Moves fast. Ships daily. Prefers direct honest feedback over hedged options. Pushes back hard, expects you to push back too when he's wrong.
- **Context to preserve:** He runs Spotlight Dubai (physical business) and has 20+ other AI platforms live (newworld.education, getgoldsilver.com, createagent.ai, WEZA, ZEROAGENCY, and more). BrainLab is one of many — respect his time accordingly.
**Communication rules:**
- Be concrete. Give him next actions, not long menus.
- When something is simple, say so. Don't pad estimates.
- When something is hard or risky, say so. Don't soften.
- He prefers step-by-step execution with one action at a time during deployments.
- When he's wrong, say he's wrong and explain why.
---
3. Current state of the project (update this section at the end of every session)
**Last updated:** 2026-04-20, end of Session 1 foundation build
**What is live:**
- Landing page: `https://brainlabkids.spotlightdubai.com`
- Waitlist form backed by Supabase (table: `brainlab_waitlist`)
- Full single-page app demo with 9 Labs (pending port to Next.js)
**What is building (Session 1):**
- Next.js 14 app migration
- Supabase Auth (parent accounts)
- Child sub-profiles
- Database schema for progress + XP + Neo conversations
- Port 9 Labs from single-file demo
- Real Neo AI tutor via Claude API proxy
- Admin dashboard
- i18n for EN / AR / UR (architecture for 20+ locales)
- Basic welcome email via Resend
**What is NOT built yet:**
- Payments (deferred until Dubai freelance permit active)
- 27 remaining Labs
- Voice narration
- Weekly Brain Report generation
- COPPA / GDPR explicit consent flows
- External child-safety review of Neo
- Mobile native wrapper (Capacitor)
- 17 additional language translations
---
4. Tech stack
**Frontend:** Next.js 14 (App Router), TypeScript strict mode, Tailwind CSS
**Backend:** Supabase (Postgres + Auth + RLS). Project: `lacemhfybgqomwpyvsbu` (name: getgoldsilver, shared with other YDR Labs projects — tables prefixed with `brainlab_` to namespace)
**AI:** Anthropic Claude via `/api/neo` server-side proxy. Model: `claude-haiku-4-5-20251001`. Key env var: `ANTHROPIC_API_KEY`.
**Email:** Resend
**Payments:** DEFERRED — will be Stripe Dubai once freelance permit + bank account operational (~3 weeks out). Do NOT build payment code until Khurram confirms readiness.
**Hosting:** Vercel, project `brainlab-kids-landing`
**Analytics:** Vercel Analytics (to be added) + Supabase-native queries for user behavior
**DNS:** GoDaddy, domain spotlightdubai.com, subdomain brainlabkids via CNAME to cname.vercel-dns.com
**i18n:** next-intl with URL-based routing (`/en/`, `/ar/`, `/ur/`)
---
5. Architecture conventions
Folder structure
Database tables (all prefixed `brainlab_`)
Row-Level Security
API routes
---
6. Design system
**Fonts:** Unbounded (display / headings), Figtree (body), JetBrains Mono (labels / pills)
**Color tokens:**
```
--bg-deep: #0a0a1f
--bg-mid: #12132e
--bg-card: #1a1b3a
--ink: #f5f0e6
--ink-dim: #a8a5c0
--accent-orange: #ff6b35 (primary CTA)
--accent-pink: #ec4899 (emphasis)
--accent-cyan: #22d3ee (visual cortex world)
--accent-yellow: #fbbf24 (amygdala world)
--accent-lime: #a3e635 (prefrontal world)
--accent-violet: #8b5cf6
```
**Style direction:** Midnight navy backgrounds. Orange/pink accents. Never use purple gradients on white (generic AI aesthetic). Typography does heavy lifting. Generous spacing. Never "cute kids app" — this is a serious neuroscience platform that happens to be for kids.
**Do not introduce new color tokens without updating this file.**
---
7. The Five Worlds and Labs
| World | Region | Color | Mascot concept |
|---|---|---|---|
| Signal City | Occipital | Cyan | Visual cortex |
| Memory Vault | Hippocampus | Pink | Memory |
| Feeling Forest | Amygdala | Yellow | Emotion |
| Decision Desert | Prefrontal | Lime | Self-control |
| Motion Mountain | Cerebellum | Orange | Motor |
**The 9 Labs currently built (preserve exactly):**
- `kanizsa` — Kanizsa triangle illusion (Signal City)
- `facevase` — Face/vase illusion (Memory Vault)
- `memory` — 12-word memory test (Memory Vault)
- `stroop` — Stroop color/word conflict (Decision Desert)
- `decoy` — Decoy effect (Decision Desert)
- `reaction` — Reaction time (Motion Mountain)
- `balance` — Balance Master, uses accelerometer (Motion Mountain)
- `emotion` — Emotion Mirror, uses camera (Feeling Forest)
- `breath` — Breath Scientist, uses microphone (Feeling Forest)
**27 remaining Labs** will be designed and built in a dedicated content-expansion session. Do not invent new Labs without an explicit ask from Khurram.
Lab structure (every Lab)
Every Lab writes to `brainlab_lab_progress` and `brainlab_xp_events` on completion.
---
8. The Neo AI tutor — safety rules
**Neo is the single highest-risk surface in this product.** A bad Neo response screenshot could end the business. Treat Neo code with the same care as a medical device.
Hard rules
Technical guardrails
Before launching Neo to real children
---
9. Internationalization
**Launch languages:** English (en), Arabic (ar), Urdu (ur)
**Planned locales (17 more):** fr, es, hi, bn, id, tr, ru, de, pt, zh, ja, ko, it, fa, th, vi, sw
**Rules:**
- All user-facing text pulled from `/messages/{locale}.json`
- Never hardcode strings in components
- For new copy, always add to `en.json` first. Mark `ar.json` and `ur.json` entries with `[TRANSLATE: english text]` if you don't have verified translations
- **Do not machine-translate neuroscience explanations for kids.** Mistranslation of a concept is worse than no translation. Flag these for human review.
- UI buttons, simple instructions, labels: machine translation is acceptable but should be flagged for review
- RTL (`dir="rtl"`) must be set on `<html>` for `ar`, `ur`, `fa`, `he`
- Layout must work in RTL — test both directions when building UI
- Claude API in Neo responds natively in the child's language — no translation needed server-side
- Dates, numbers, currencies use `Intl` APIs with the user's locale
---
10. Compliance commitments
Privacy
COPPA
Child safety
---
11. Working rules for Claude Code sessions
1. **Read this file at the start of every session.** Update Section 3 at the end of every session.
2. **Commit to git frequently** — at minimum after each phase of a build plan. Clear commit messages.
3. **Keep a BUILD_LOG.md** updated as you work. Khurram checks it when he's offline.
4. **Pause for DECISION points** — never make business/product decisions alone. Architectural decisions you can make. Product/naming/pricing/legal — always ask.
5. **Never break what's live.** The landing page at brainlabkids.spotlightdubai.com must keep working throughout any refactor.
6. **Never modify the `brainlab_waitlist` table or its RLS** without explicit approval — it's collecting real data.
7. **TypeScript strict mode.** No `any` unless justified with a comment.
8. **No new dependencies without a reason.** Keep the stack lean.
9. **When stuck, write what you tried and ask.** Don't hallucinate solutions.
10. **Budget for API costs.** Every Neo call costs real money. Cache, rate-limit, monitor.
11. **Flag any security risk immediately** — never silently accept a pattern that exposes keys, user data, or bypass RLS.
12. **Do not add payments, do not add new Labs, do not add new languages beyond en/ar/ur** without explicit instruction. Scope creep kills quality.
---
12. The voice of BrainLab
When writing copy, microcopy, error messages, UI text — the voice is:
- **Smart but warm.** Neuroscience-grade, never condescending, never babyish.
- **Direct.** Short sentences. Active voice.
- **Curious.** Questions more than declarations. "What do you see?" beats "Look at this."
- **Honest about the brain.** "Your brain tricked you" is the right vibe, not "Oh no, try again!"
- **No emoji in product copy** unless specifically celebratory. Occasional 🧠 in success states is fine.
- **Never cute kids-app language.** No "Oopsie!" or "Let's go adventuring!" — kids this age can smell condescension.
---
13. What to never do
- Never let a child talk to the raw Claude API without the Neo system prompt and safety rails
- Never expose the Anthropic API key to client code
- Never expose the Supabase service-role key to client code
- Never machine-translate educational content without flagging for human review
- Never add a payment flow until Khurram's Dubai freelance permit and business bank are live
- Never add new Labs without explicit approval
- Never reference or copy from the National Geographic Kids "Brain Games" book — the underlying science is public, but the book's language and structure are not ours to use
- Never introduce dark patterns: streak guilt, lootboxes, push notifications to re-engage children
- Never add advertising
- Never run analytics that track individual children across sessions beyond what's needed for the parent report
- Never market to children directly — parents are the buyers, kids are the users
---
14. Where things live (quick reference)
- **Supabase project:** `lacemhfybgqomwpyvsbu` (URL: `https://lacemhfybgqomwpyvsbu.supabase.co`)
- **Vercel project:** `brainlab-kids-landing`
- **GitHub:** (to be created as `brainlab-kids-app` under khurrambadar3125)
- **Live URL:** https://brainlabkids.spotlightdubai.com
- **Domain registrar:** GoDaddy (spotlightdubai.com)
- **Reference files (do not delete):**
- `landing-legacy.html` — original single-file landing page
- `demo-legacy.html` — original single-file full demo with 9 Labs
---
15. Roadmap horizons
**Week 1–2 (now):** Validate with real parents in Dubai. Send link to trusted contacts. Monitor waitlist growth, demo usage.
**Week 3–4:** Based on validation signal, decide whether to continue or pivot. If continue: set up Dubai freelance permit + business bank for payments.
**Week 5–8:** Content expansion (27 new Labs). Voice narration. Real leaderboard.
**Week 9–12:** Compliance + safety hardening. External Neo review. GDPR/COPPA flows.
**Week 13+:** Mobile native wrapper. Additional languages. SEN mode. B2B school pilots.
Roadmap is fluid — validation signal dictates sequencing.
---
*End of CLAUDE.md. Keep it alive. If you change something fundamental, update this file in the same commit.*