diff --git a/README.md b/README.md
index df5513c..4e8ab70 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,34 @@
# Habit Pet
-Bootstrap repo for the Calgary hackathon Habit Pet project.
+Calgary hackathon app for building habits while caring for a customizable pixel pet.
## Stack
-- Next.js
-- Supabase
-- Vercel
-- GitHub
+- Next.js 16 (App Router)
+- Supabase (auth + Postgres)
+- Tailwind CSS + shadcn/ui
+- Vercel deployment via GitHub Actions
-## Scope of this bootstrap
+## Features
-This repo currently stops at:
+- **Auth** — email/password sign up and login
+- **Onboarding** — focus-topic quiz, then required avatar customization (DB-gated)
+- **Avatar** — layered sprite pet with per-layer styles and hex colors, naming, equipped shop items
+- **Habits** — catalog + custom habits, streaks, coin rewards
+- **Daily quiz** — wellness sliders and journal that affect pet mood
+- **Shop** — buy and equip items from `shop_items` / `user_items` (hats, glasses, backgrounds)
+- **Profile** — focus topic, vibe, and reminder preferences
-- Next.js app scaffold
-- Supabase auth wiring from the starter
-- environment variable template
-- deployment-ready project structure
+## User flow
-This repo does not yet include MVP feature pages, avatar logic, habits, streaks, or shop logic.
+1. Sign up / sign in
+2. **Step 1:** onboarding quiz (focus topic only)
+3. **Step 2:** avatar customization (required confirm + pet name)
+4. Main app via bottom nav: Pet, Habits, Quiz, Shop, Profile
+
+Onboarding progress is stored in the database (`profiles.onboarding_quiz_complete`, `profiles.onboarding_complete`, `avatar_state.avatar_customized`) and mirrored in auth metadata for fast client checks.
+
+On the **Pet** tab, users rename their pet and switch between **Overview** and **Customize** sub-tabs.
## Local setup
@@ -28,68 +38,80 @@ This repo does not yet include MVP feature pages, avatar logic, habits, streaks,
npm install
```
-2. Create local environment file:
+2. Generate placeholder character/shop sprites (if missing):
+
+ ```bash
+ npm run generate:sprites
+ ```
+
+3. Create local environment file:
```bash
cp .env.example .env.local
```
-3. Add Supabase values to `.env.local`:
+4. Add Supabase values to `.env.local`:
```env
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
```
-4. Start the app:
+5. Apply migrations locally (Supabase CLI):
+
+ ```bash
+ supabase db reset
+ ```
+
+6. Start the app:
```bash
npm run dev
```
-5. Create a production build when needed:
+## Avatar customization data
- ```bash
- npm run build
- ```
+Stored in `avatar_state`:
+
+| Column | Purpose |
+|--------|---------|
+| `avatar_name` | Pet display name |
+| `skin_color` | Skin layer hex color |
+| `pants_style` / `pants_color` | Pants variant id + hex |
+| `shoe_style` / `shoe_color` | Shoes variant id + hex |
+| `torso_style` / `torso_color` | Torso variant id + hex |
+| `eye_type` / `eye_color` | Eyes variant id + hex |
+| `head_style` / `head_color` | Head variant id + hex |
+| `avatar_customized` | True after onboarding confirm |
+| `equipped_items` | Shop item ids currently equipped |
+
+Style columns are validated against allowed variant ids (`none`, `pants-1`, …). Shop accessories overlay equipped variants at render time without overwriting saved customization.
+
+Sprite assets: `public/character/{layer}/` (regenerate via `npm run generate:sprites`).
+
+## Shop
+
+- Sells character layer styles from `public/character/` (`head-1`, `pants-2`, etc.)
+- Shop item `id` = variant id, `type` = layer id (`head`, `pants`, `shoes`, `torso`, `eyes`)
+- Purchases unlock styles in `user_items`; owned styles appear in Customize and can be equipped from the shop
+- Catalog seeded in `supabase/seed.sql`
## Supabase
-Create a Supabase project, then copy the project URL and anon key from **Project Settings > API** into `.env.local` and Vercel project environment variables.
+- Migrations: `supabase/migrations/`
+- Seed: `supabase/seed.sql`
+- Config: `supabase/config.toml`
-The starter also supports Supabase's publishable key name, but this repo documents the anon key convention from the project plan.
+Production deploys on push to `main` via `.github/workflows/deploy.yml` (lint, build, `supabase db push --include-seed`, Vercel).
-### Database workflow
+## Routes
-- Schema migrations live under `supabase/migrations/`.
-- Baseline catalog data lives in `supabase/seed.sql` and is safe to rerun during deploys because it uses idempotent upserts.
-- Local CLI config lives in `supabase/config.toml` for `supabase start`, `supabase db reset`, and related commands.
-- Production database sync runs from GitHub Actions on `main` using `supabase db push --linked --include-seed` before the app deploy relies on those changes.
-
-## Deploy
-
-This repo includes `.github/workflows/deploy.yml`, which runs on pushes to `main`.
-
-The workflow:
-
-- checks out the repo
-- runs `npm ci`, `npm run lint`, and `npm run build`
-- links the Supabase CLI to the production project
-- applies pending database migrations and reruns `supabase/seed.sql` via `supabase db push --linked --include-seed`
-- deploys the app to Vercel production only after the database sync succeeds
-
-### Required GitHub secrets
-
-- `SUPABASE_ACCESS_TOKEN`
-- `SUPABASE_PROJECT_REF`
-- `SUPABASE_DB_PASSWORD`
-- `VERCEL_TOKEN`
-- `VERCEL_ORG_ID`
-- `VERCEL_PROJECT_ID`
-
-### Required Vercel environment variables
-
-- `NEXT_PUBLIC_SUPABASE_URL`
-- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
-
-Frontend and backend are both served from this Next.js app. Supabase provides auth and database services.
+| Route | Access |
+|-------|--------|
+| `/` | Public |
+| `/auth/*` | Public |
+| `/onboarding/quiz` | Authenticated, quiz incomplete |
+| `/onboarding/customize` | Authenticated, quiz complete, avatar not confirmed |
+| `/avatar` | Authenticated, onboarding complete |
+| `/habits`, `/daily/quiz`, `/shop`, `/profile` | Authenticated app |
+| `/character-creator` | Redirects to `/avatar?tab=customize` |
diff --git a/app/(app)/avatar/page.tsx b/app/(app)/avatar/page.tsx
index da2310a..d56b728 100644
--- a/app/(app)/avatar/page.tsx
+++ b/app/(app)/avatar/page.tsx
@@ -1,19 +1,17 @@
-import { AvatarStatusCard } from "@/components/avatar/avatar-status-card";
-import { DailyQuizLinkButton } from "@/components/daily-quiz/daily-quiz-link-button";
-import { HabitTracker } from "@/components/habits/habit-tracker";
+import { Suspense } from "react";
+
+import { AvatarPageContent } from "@/components/avatar/avatar-page-content";
import { AppShell } from "@/components/layout/app-shell";
export default function AvatarPage() {
return (