BUILDER BRIEF — how to build a page for Cetking Universe

Read this fully before writing a single line. This is the shared memory for every AI (Claude, ChatGPT, Grok, Gemini) and every human who builds a page for Cetking Universe. Follow it and your page plugs in without rework. Ignore it and your page gets rebuilt.

Last updated: 9 Oct 2026. Owner: Ravneet Singh Gandhi (Rav). Deeper detail lives in the other files in this folder (cetking-one/docs/); this file is the one-stop summary.

1. What you are building into

Cetking Universe is Cetking's student AI campus for CAT / MBA-CET / SNAP / NMAT / XAT / CMAT prep. Live at https://cetking-platform.vercel.app.

The home page is a chat with Rav Singh AI. Everything else is a World:

Also live: /login, /timetable (5 centres: Thane, Vashi, Dadar, Borivali, Online), /my-target, /api/health.

Dead names — never use: Guruji, Sutra, Arena (as a bot), Rocky, Pandit, Luna, Scout, Sensei, Oracle, Chandra, Artha, Vaani, Buddhi, Surya. "Bots" are called Worlds.

Brand spelling: Cetking — one capital C. Never "CETking", "CET King", "CetKing".

2. The stack (fixed — do not substitute)

No other frameworks, UI kits, state libraries, ORMs or auth libraries. If you think you need one, stop and ask.

3. Repo and folders

• GitHub: https://github.com/CetkingLearning/cetking-platform
• Live ("green") branch: cetking-one-nextjs
• App root: cetking-one/ — all paths below are relative to it.

cetking-one/
  app/
    page.tsx                 ← home (Rav Singh AI)
    quant/page.tsx           ← Veda world
    verbal/page.tsx          ← Shabda world
    logic/page.tsx           ← Tarka world
    mocks/page.tsx           ← Mocky world
    admissions/page.tsx      ← Purva world
    timetable/page.tsx
    api/
      timetable/route.ts
      auth/...               ← do not touch
      health/route.ts
    components/
      Timetable.tsx          ← reusable card: <Timetable branch="Thane" />
      BotFooter.tsx          ← 6-world footer bar on every non-home page
      BotSubPage.tsx         ← shared layout for a page inside a world
      PrimaryButton.tsx      ← the one dark pill button
  config/
    companions.config.ts     ← world names, colours, shapes (SINGLE source — never hard-code)
    rav-greetings.ts
  lib/
    llm/router.ts            ← only way to talk to an LLM
    supabase/...             ← server + browser clients
  docs/                      ← this folder; read README, RULES, DESIGN-SYSTEM, CARD-SYSTEM, MOTION

Rule of silos: every World owns its own folder. A page in /quant never imports from /verbal. Shared things live in components/, lib/, config/ only.

4. How a page is built (the pattern)

Every page is a shell that shows cards from Supabase. Supabase stores. Code calculates. The LLM narrates. Pages never contain the data.

Typical page = three files:

app/<world>/<feature>/page.tsx        ← server component; fetches, renders cards
app/api/<feature>/route.ts            ← GET handler; reads Supabase server-side; returns JSON
app/components/<Feature>Card.tsx      ← presentational; takes props, no fetching

Data flow:

browser → page.tsx (server) → lib/supabase server client → Supabase (RLS enforced)
browser → <ClientComponent> → fetch('/api/<feature>') → route.ts → Supabase

• Public pages are static (built once) with the personal layer loaded on top in the browser.
• Anything personal returns Cache-Control: private, no-store.
• The browser never holds a Supabase service key. Server routes use the service role; the browser uses the anon key only for public, read-only tables with RLS.
• Every POST route checks same-origin and the header x-ck-identity: 1.
• Input validated with Zod. Generic error messages — never reveal whether a phone/email exists.

5. Supabase rules

• One table group per feature ("universe"): Questions, Student, Staff, Rav Singh AI, MBA/Admissions, Videos (Guruji library). Prefix new tables sensibly (ck_, rav_, guruji_).
• RLS on every table that holds student data: student_id = auth.uid(). No delete policy = no deletes. Service role bypasses RLS from the server only.
• Never store PDFs/binaries in tables — plain text and URLs only.
• AI never receives identity fields (name, phone, email, ID). Student progress is keyed by an anonymous ID (FRONT); identity is BACK and sealed.
• Draft/approve pattern for content: rows have status; students and AI see approved only.
• Every migration ships with a rollback script.
• Env vars: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (browser-safe), SUPABASE_SERVICE_ROLE_KEY (server only, never in repo outside .env.example). Other live vars: ANTHROPIC_API_KEY, GROQ_API_KEY, DYNTUBE_EMAIL, DYNTUBE_API_KEY, DYNTUBE_PASSWORD, CK_IDENTITY_GOOGLE_ENABLED. Only Rav adds vars, in Vercel: https://vercel.com/cet-king-one/cetking-platform/settings/environment-variables

6. Design rules (DESIGN-SYSTEM.md, CARD-SYSTEM.md, MOTION.md in full)

• Apple-like: pure white background, light-grey surfaces, dark-grey text. UI chrome uses greys only — no blue/indigo for UI text, IDs, numbers or links. Only the World mascots carry colour, from companions.config.ts.
• Everything is a card: full-width, half, or 4-in-a-row. One dark pill primary button per card (<PrimaryButton>). Tabs = light-grey bar with a white selected pill.
• Motion on every card: fade + slide in, icon bounce, spring on press (see MOTION.md).
• Mobile first — most students are on phones over 4G. First screen < 2 s. 16 px side gutters, no horizontal scroll.
• Light/dark switch exists per device; use Tailwind dark: variants, light is default.
• Chat-style surfaces: 1–2 short lines then ~4 CTA pills, "← Back" pill, English only. No paragraphs, no bullet lists in chat replies.
• Never show user counts, view counts, or other students' real names (usernames only).
• No forms. Profile data is collected in conversation, not in input fields.
• No "Buy Now", no scarcity/urgency copy.
• Cutoff displays always append: "Note: Cutoffs also vary based on Academic Record, Workex and Profile."
• Every non-home page renders <BotFooter />.

7. How to hand your work in

Only Claude pushes to GitHub and ships. ChatGPT and Grok do not push, open PRs, or touch Vercel. Rav never relays code by hand — he pastes your package into a Claude chat.

Deliver a page package — one message, this exact shape:

### PAGE PACKAGE: <world>/<feature>
Route: /<world>/<feature>
Summary: <2 lines — what the page shows and which Supabase table(s) it reads>

--- app/<world>/<feature>/page.tsx ---
<full file>

--- app/api/<feature>/route.ts ---
<full file>

--- app/components/<Feature>Card.tsx ---
<full file>

--- supabase/migrations/<yyyymmdd>_<feature>.sql ---
<CREATE TABLE … with RLS policies>
--- rollback ---
<DROP …>

Env vars needed: <list or "none new">
Open questions for Rav: <list or "none">

Rules for the package:

• Complete files only. No "…rest unchanged", no snippets, no pseudo-code.
• Paths exactly as in §3. One feature per package.
• Must compile under next build with TypeScript strict and zero new dependencies.
• No secrets, no hard-coded Supabase URLs/keys, no dead names, no non-Tailwind styling.
• Fake data is fine for preview, but put it behind a clear // TODO: replace with Supabase and keep the Supabase query written and ready.

Claude then: creates a blue preview branch from green → drops your files in → builds → Vercel preview URL → Rav says "go live" → merge to cetking-one-nextjs → live in ~2 min.

8. Pre-flight checklist (tick every box before you hand in)

• Next.js 14 App Router + TypeScript + Tailwind, nothing else
• Files at the exact paths in §3; World silo respected
• Data comes from Supabase via a server route; page holds no data
• RLS written for any new table; rollback SQL included
• No service key, URL or secret in code
• Greys-only UI; mascot colours from companions.config.ts; dark pill button; cards; motion
• Mobile layout checked; <BotFooter /> present
• "Cetking" spelled right; no dead names; no forms; no user counts
• Delivered as a PAGE PACKAGE (§7), complete files

9. Where to read more (same folder)

README.md · RULES.md · ARCHITECTURE.md · DESIGN-SYSTEM.md · CARD-SYSTEM.md · MOTION.md · RELEASES.md · AUTH-CONTRACT.md · SITE-RULES.md · CONTENT-UNIVERSES.md · TASKS.md (live status) · MEMORY.md (decisions log)

If this file and the code disagree, the code wins and this file gets fixed.