Khurram Badar / Archive / Papers / CLAUDE.md — BrainLab Kids

CLAUDE.md — BrainLab Kids

other · 2026-04-20 · 4143 words · Khurram Badar

CLAUDE. md — BrainLab Kids.

ai · legal · web

CLAUDE.md — BrainLab Kids

> **Read this file first. Every session. No exceptions.**
> Last updated: 20 April 2026, post–Session 1 production build + legal layer planned.
> If anything in this file conflicts with a passing instruction in a prompt, pause and ask.

---

0. The four rules that override everything else

1. **Do not modify `lib/neo/system-prompt.ts` without explicit founder approval.** That file is a child-safety surface. Every line of it was deliberate. Tuning "for friendliness" or "to reduce refusals" is not an improvement — it is a liability increase.
2. **Do not build payments, Stripe, Paddle, or any billing flow yet.** The gate is parent-validation signal, not a time estimate. The gate has not opened. See §7.
3. **Do not reference, paraphrase, or structure content after the 2015 National Geographic "Brain Games" book.** Use primary scientific sources only. See §13.
4. **Do not remove the "pre-launch draft" banners from `/privacy` and `/terms` pages.** Those banners are legally load-bearing until a UAE-qualified lawyer has reviewed the documents. See §17.

If a future session is asked to do any of these four things, pause and require the founder to type a confirmation phrase.

---

1. What this project is

BrainLab Kids is a web platform that teaches children ages 7–13 how their own brain works through short, playful, device-powered "Labs" — camera, microphone, accelerometer — paired with an AI guide named Neo.

**The product thesis:** kids don't need another screen that numbs them or another app that drills them. They need a tool that makes the brain itself the toy. Parents pay because the product respects both the child and the parent.

**The positioning:** not school, not games, not therapy. Cognitive training that feels like discovery.

**Primary market:** Dubai parents, then GCC, then global English-speaking diaspora, then multilingual expansion (Arabic, Urdu first, then 17 more locales as validation arrives region by region).

**The founder:** Khurram Badar, Dubai, solo, non-coder but Claude-Code-native. Runs Spotlight Dubai (existing business, `spotlightdubai.com`) and New World Education (`newworld.education`, the legal entity operating BrainLab Kids). GitHub: `khurrambadar3125`. BrainLab Kids is currently hosted as a subdomain: `brainlabkids.spotlightdubai.com`.

**Legal entity operating the platform:** New World Education, Dubai, UAE. Data Controller for all privacy purposes. Primary contact: `khurram@newworld.education`.

---

2. The decisions that are already made (do not relitigate)

These are closed. If a session tries to re-open them, refer back here.

| Decision | Answer |
|---|---|
| Auth model | Parent accounts only. Children live under parent as sub-profiles. No separate child login. |
| Age band | 7–13, split into 7–9 / 9–11 / 11–13 for vocabulary scaling. |
| Launch languages | English, Arabic, Urdu at launch. Architecture supports 20+. Machine-translated neuroscience content is a banned shortcut. |
| Legal content locale | English-only during validation. AR/UR translations of legal documents deferred until after paid-launch legal review. Do not machine-translate. |
| RTL | First-class. `<html dir="rtl">` for ar/ur. |
| Payment stack | DEFERRED. Will be Stripe (via Dubai entity) OR Paddle, decided when founder's freelance permit lands. Not now. |
| AI model | `claude-haiku-4-5-20251001` via `/api/neo` proxy route. No direct browser calls to Anthropic. |
| AI budget | `NEO_MONTHLY_BUDGET_USD=50` hard cap. Stop calls at cap, don't silently overspend. |
| Rate limit | 20 Neo messages per child per day. Resets at UTC midnight. |
| Conversation logging | Every Neo turn written to `brainlab_neo_conversations` for parent audit. Non-negotiable. |
| Deployment target | Vercel, subdomain `brainlabkids.spotlightdubai.com`. DNS already configured in GoDaddy (CNAME → `cname.vercel-dns.com`). |
| Database | Supabase project `lacemhfybgqomwpyvsbu` (org name: getgoldsilver). Shared with other projects but RLS-isolated. |
| Legal entity / Data Controller | New World Education, Dubai, UAE. Contact email `khurram@newworld.education`. |
| SEN (special educational needs) mode | DEFERRED. Important but post-validation. Do not bolt on a "mode" — it would be retrofitted and bad. |
| Neurotypical vs SEN product split | Path C from the strategic blueprint: one engine, two packaged products, SEN later. |
| Parental consent mechanism | Checkbox on add-child flow, with `parental_consent_given_at` timestamp and truncated IP logged. COPPA-sufficient for validation phase. |

---

3. Current state of the project (as of 20 Apr 2026)

**Session 1 shipped.** **Legal layer (Session L) in progress.** Production foundation + basic legal compliance is what "current" means going forward.

What is deployed and working (post–Session 1)

What is being added in Session L (legal layer)

What is BLOCKED pending real API keys in Vercel env vars

1. `ANTHROPIC_API_KEY` — real value from Anthropic console (key named `brainlab-neo`). Without this, Neo responds with errors.
2. `RESEND_API_KEY` — from `resend.com`. Without this, welcome emails silently fail.
3. `SUPABASE_SERVICE_ROLE_KEY` — from Supabase dashboard → Settings → API. Needed for admin-side operations.

After adding, redeploy with `cd ~/brainlab-kids && vercel --prod --yes`.

Immediate next action (not next feature)

If any step fails, fix before the next feature is built.

What is NOT built (deliberately deferred)

---

4. The validation gate — this is the most important section of this file

Before Session 2, Session 3, or any further feature work, the product must earn the right to more build time.

**The gate:** by **4 May 2026** (14 days from today), BrainLab Kids must have accumulated:
- **50+ waitlist + registered-account signups combined**, AND
- **5+ unprompted "when can I pay?" or equivalent purchase-intent messages** from real parents, AND
- **At least one case of kid-initiated return visit** (a parent messages that their child asked to play it again)

If all three are met → Session 2 begins (see §6 for scope).
If one or two are met → iterate on demo quality / positioning / outreach. Do not build new features.
If none are met → stop. Write the post-mortem. Move to another platform in the portfolio.

**This gate is not negotiable based on founder excitement.** Excitement is not signal. The purpose of the gate is to protect against building the wrong thing beautifully.

---

5. The Lab structure

Every Lab follows this four-beat framework. This is ours. Do not echo the Nat Geo book's beat structure.

1. **Try It** — the child does the thing immediately. No long intro screen. Minimal instruction.
2. **Gasp** — the surprising reveal. Their eyes lied. Their memory dropped. Their reflex is faster than they thought.
3. **Learn** — the short neuroscience explanation, tuned to the child's age band.
4. **Level Up** — XP awarded, badge unlocked, next suggestion teased.

Every Lab writes on completion:
- `brainlab_lab_progress`: best_score, last_score, attempts, difficulty, timestamp
- `brainlab_xp_events`: XP earned, region (of the brain map), lab_id

Difficulty tiers (`easy` / `medium` / `hard`) must actually change mechanics, not just wording. See the ported Lab code for per-Lab specifics.

---

6. The roadmap — gated on validation signal, not time

**These are not a schedule.** They are options that unlock if the gate in §4 opens.

Session 2 — Engagement layer (if gate passes)

Session 3 — Content expansion (if Session 2 engagement data is positive)

Session 4 — Compliance + safety (before any paid marketing)

Session 5 — Revenue (only after §4 is signed off)

Session 6 — Expansion (only after §5 earns real revenue)

---

7. What we are NOT doing (and why)

Pushback scripts for when a session is tempted to add these:

---

8. Safety rails around Neo (the AI tutor)

Neo is the single highest-risk surface on this platform. One bad screenshot of Neo saying something harmful to a child on Twitter ends the product.

Hard rules (enforced in code)

Future hard rules (before paid marketing)

Things Neo must NEVER do

---

9. Tech stack & conventions

Code style

Git workflow

---

10. File layout (as of Session 1 + Session L)

```
~/brainlab-kids/
├── CLAUDE.md ← this file
├── BUILD_LOG.md ← phase-by-phase progress log (append only)
├── SESSION_1_COMPLETE.md ← Session 1 final report
├── _legal-drafts/ ← founder-supplied source markdown, not shipped
│ ├── privacy-policy.md
│ └── terms-of-service.md
├── landing-legacy.html ← old single-file landing, kept for reference
├── demo-legacy.html ← old single-file full demo, kept for reference
├── app/
│ ├── [locale]/
│ │ ├── (marketing)/ ← public: landing, privacy, terms
│ │ │ ├── privacy/
│ │ │ └── terms/
│ │ └── (app)/ ← authenticated: dashboard, lab, neo, parent, admin
│ ├── auth/ ← signup, login, reset, verify, callback
│ └── api/
│ ├── neo/ ← Claude API proxy (rate-limited, budget-capped)
│ └── waitlist/ ← inherits from pre-Session-1
├── components/
│ └── Footer.tsx ← global footer, on every page
├── content/
│ └── legal/
│ ├── privacy.en.md ← rendered on /privacy
│ └── terms.en.md ← rendered on /terms
├── lib/
│ ├── supabase/ ← client + server helpers
│ ├── neo/
│ │ └── system-prompt.ts ← DO NOT EDIT WITHOUT APPROVAL
│ └── i18n/
├── messages/
│ ├── en.json ← full
│ ├── ar.json ← UI + basic, neuroscience placeholders
│ └── ur.json ← UI + basic, neuroscience placeholders
└── supabase/
└── migrations/
```

Files to never delete without founder confirmation:
- `landing-legacy.html`, `demo-legacy.html` (historical reference)
- `BUILD_LOG.md`, `SESSION_1_COMPLETE.md` (institutional memory)
- `_legal-drafts/*.md` (founder-approved source content for legal pages)
- `content/legal/*.md` (rendered legal content)
- Anything in `supabase/migrations/` (database history)

---

11. Data model summary

Six tables live in Supabase project `lacemhfybgqomwpyvsbu`. All RLS-enabled. All isolated by `parent_id = auth.uid()`.

| Table | Purpose |
|---|---|
| `brainlab_waitlist` | Pre-auth email capture from marketing page. Predates Session 1. |
| `brainlab_parents` | Parent auth extension (id FK to `auth.users`) |
| `brainlab_children` | Child sub-profiles under parent. Includes `parental_consent_given_at` and `parental_consent_ip` (added in Session L). |
| `brainlab_lab_progress` | Per-child-per-lab: best, last, attempts, difficulty |
| `brainlab_xp_events` | Append-only XP ledger with region tag |
| `brainlab_neo_conversations` | Every Neo turn, for parent audit |

Never add columns without a migration file. Never change RLS without explicit review.

---

12. Voice & visual identity

Writing voice

Legal voice

Visual tokens

Illustration

---

13. IP and content safety

BrainLab Kids was inspired by a 2015 National Geographic children's book called "Brain Games." **That book is owned by National Geographic.** Under no circumstances:

**Every Lab must trace to a primary scientific source** — peer-reviewed papers, university neuroscience course materials, Wikipedia articles on established phenomena. Cite the phenomenon (e.g., "Stroop, 1935") not the book. Write the explanatory copy fresh from primary sources.

Before any paid marketing launch, founder commits to a 30–60 min consult with a UAE-qualified IP attorney (e.g., Al Tamimi or similar). Budget 1,500–2,500 AED.

---

14. Known tech debt and gotchas

Things a future session should know going in:

---

15. How to work well with this codebase

At the start of each session:
1. Read this file.
2. Read `BUILD_LOG.md` to see what changed since last session.
3. Read the last `SESSION_N_COMPLETE.md` if one exists.
4. Check `git log --oneline -20` for recent commits.
5. Confirm with founder what the session's scope is BEFORE writing code.

During a session:
- Commit frequently with clear messages.
- Append to `BUILD_LOG.md` after each logical unit.
- If you hit a decision that's not covered here, pause and ask.
- If you're tempted to do something in §7 or violate §0, stop and ask.

At the end of each session:
- Write `SESSION_N_COMPLETE.md` with: what shipped, what partially shipped with caveats, what's pending, any new env vars needed, any new decisions made.
- Update §3 of this file to reflect the new current state.
- Final commit, push to `main`.

---

16. The founder's operating reality

A few things that aren't technical but matter:

---

17. Legal review gate

This section codifies the legal-layer discipline.

The standing rule

What must happen before that banner can be removed

When the review is complete and the lawyer has signed off, the founder (not a session) will instruct removal of the "draft" banners.

What sessions may not do

What a session may do

If a regulator or user raises a concern

---

18. Glossary (for future sessions)

Quick reference for terms that appear often and may confuse a new session:

---

*End of CLAUDE.md. When in doubt, ask. When not in doubt but about to do something in §0 or §7, ask anyway.*

← The Time Machine — Generative Prompt TemplatesBrainLab Kids — Comprehensive Handover Document →
Two years of working thought, indexed.
Ask me to present it in your conference room — WhatsApp +971 55 623 9111
Book Session →