Enhance setup, AI management, agent functionality, and documentation

.env.setup.example

@@ -0,0 +1,11 @@
+# Setup wizard sandbox — copy to .env.setup.local (gitignored)
+# Use a SEPARATE Supabase project from your main .env.local dev/deploy DB.
+
+NEXT_PUBLIC_SUPABASE_URL=https://YOUR_SANDBOX_PROJECT.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your_sandbox_anon_key
+SUPABASE_SERVICE_ROLE_KEY=your_sandbox_service_role_key
+POSTGRES_URL_NON_POOLING=postgresql://postgres.YOUR_SANDBOX_REF:YOUR_PASSWORD@aws-0-ap-southeast-1.pooler.supabase.com:5432/postgres
+
+# Optional for local setup testing
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+SCHOOL_AUTH_DOMAIN=localhost

.gitignore

@@ -34,6 +34,7 @@ yarn-error.log*
 # env files (can opt-in for committing if needed)
 .env.local
 .env
+.env.setup.local
 
 # Firebase Service Account Keys (NEVER commit these!)
 *-firebase-adminsdk-*.json

README.md

@@ -120,6 +120,30 @@ bun dev           # http://localhost:3000
 | `bun run gen:students` / `import:students` | สร้าง/นำเข้ารายชื่อนักเรียนจาก CSV |
 | `bun run test:login` | ทดสอบ flow ล็อกอินนักเรียน |
 
+### ทดสอบ Setup Wizard แบบ Sandbox (ไม่กระทบ `.env.local`)
+
+ใช้ **Supabase project แยก** สำหรับลอง wizard ซ้ำๆ โดยไม่ต้อง redeploy และไม่ต้องเปลี่ยน env หลักที่เชื่อม deploy อยู่แล้ว
+
+```bash
+# 1) สร้างโปรเจกต์ Supabase ฟรีอีกตัว (เช่น found-u-setup-sandbox)
+cp .env.setup.example .env.setup.local
+# แก้ .env.setup.local ใส่ URL / keys / POSTGRES ของ sandbox
+
+# 2) รีเซ็ตสถานะ wizard (ทำซ้ำได้ทุกครั้งหลังทดสอบ)
+bun run setup:reset
+
+# 3) รัน dev ด้วย sandbox env (override .env.local ชั่วคราว)
+bun run dev:setup
+# เปิด http://localhost:3000/setup
+```
+
+| คำสั่ง | ใช้ทำอะไร |
+|--------|-----------|
+| `bun run dev:setup` | `next dev` โดยโหลด `.env.setup.local` |
+| `bun run setup:reset` | รีเซ็ต `setup_status`, branding, AI config, แอดมินที่สร้างจาก wizard |
+
+DB ว่างครั้งแรก: เปิด `/setup` แล้ว hydrator จะรัน migration อัตโนมัติ (เหมือน production) — ไม่ต้อง `db:push` ถ้าใช้ sandbox ใหม่เปล่าๆ
+
 ## Deploy ให้โรงเรียนใหม่
 
 แนวทางที่แนะนำ: **Clone + Deploy ก่อน** ให้ใช้งานได้จริง แล้วค่อย **Fork** ทีหลังถ้าต้องการ sync อัปเดตจากโค้ดหลัก

app/(app)/home/page.tsx

@@ -49,8 +49,10 @@ function UserNameSlot({
 }
 
 function HomeQuickMenu({ className }: { className?: string }) {
+  // Always single column — this menu is mobile-only; a 2-col grid on
+  // misreported viewports (≥640px CSS) is what makes phones look "squeezed".
   return (
-    <div className={cn("grid grid-cols-1 sm:grid-cols-2 gap-3", className)}>
+    <div className={cn("grid grid-cols-1 gap-3 w-full max-w-full", className)}>
       {menuItems
         .filter((m) => m.href !== "/home")
         .map((item) => {
@@ -59,20 +61,20 @@ function HomeQuickMenu({ className }: { className?: string }) {
             <Link
               key={item.href}
               href={item.href}
-              className="group block rounded-xl min-h-11 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-line-green/35 focus-visible:ring-offset-2 focus-visible:ring-offset-bg-secondary"
+              className="group block w-full rounded-xl min-h-14 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-line-green/35 focus-visible:ring-offset-2 focus-visible:ring-offset-bg-secondary"
             >
               <div className="bg-bg-card rounded-xl p-4 border border-border-light group-hover:border-border-medium transition-colors duration-200 motion-safe:group-active:scale-[0.99]">
                 <div className="flex items-center gap-4">
                   <div
                     className={cn(
-                      "w-12 h-12 shell-desktop:w-14 shell-desktop:h-14 rounded-xl shell-desktop:rounded-2xl flex items-center justify-center shrink-0",
+                      "w-12 h-12 rounded-xl flex items-center justify-center shrink-0",
                       item.color
                     )}
                   >
-                    <Icon className={cn("w-6 h-6 shell-desktop:w-7 shell-desktop:h-7", item.iconColor)} />
+                    <Icon className={cn("w-6 h-6", item.iconColor)} />
                   </div>
                   <div className="flex-1 min-w-0">
-                    <h3 className="text-base shell-desktop:text-lg font-semibold text-text-primary">
+                    <h3 className="text-base font-semibold text-text-primary">
                       {item.title}
                     </h3>
                     <p className="text-sm text-text-secondary line-clamp-1">{item.subtitle}</p>
@@ -136,7 +138,7 @@ export default function Home() {
   return (
     <div
       className={cn(
-        "bg-bg-primary transition-colors",
+        "bg-bg-primary transition-colors w-full max-w-full",
         "h-dvh max-h-dvh overflow-hidden flex flex-col",
         "shell-desktop:h-auto shell-desktop:max-h-none shell-desktop:min-h-screen shell-desktop:overflow-visible shell-desktop:flex-row"
       )}
@@ -145,13 +147,13 @@ export default function Home() {
 
       <div
         className={cn(
-          "flex flex-1 flex-col min-h-0 min-w-0 main-with-bottom-nav",
+          "flex flex-1 flex-col min-h-0 min-w-0 w-full max-w-full main-with-bottom-nav",
           shellSidebarInset
         )}
       >
         {/* Mobile header — switcher inside the green band */}
-        <header className={cn(shellMobileOnly, "bg-line-green text-white safe-top shrink-0")}>
-          <div className="px-5 pt-5 pb-4 flex flex-col gap-4">
+        <header className={cn(shellMobileOnly, "bg-line-green text-white safe-top shrink-0 w-full")}>
+          <div className="px-4 sm:px-5 pt-4 pb-4 flex flex-col gap-3 sm:gap-4">
             <div className="flex items-center justify-between gap-3">
               <div className="flex items-center gap-3 min-w-0">
                 <div className="w-11 h-11 rounded-full bg-white/20 flex items-center justify-center shrink-0">
@@ -302,12 +304,12 @@ export default function Home() {
           </div>
         </header>
 
-        <main className="relative z-[1] flex-1 min-h-0 overflow-y-auto overscroll-contain min-w-0 bg-bg-secondary px-5 pt-5 pb-6 rounded-t-2xl -mt-3 shell-desktop:mt-0 shell-desktop:rounded-none shell-desktop:px-8 shell-desktop:pt-8 shell-desktop:pb-8 xl:px-12 xl:pb-12">
+        <main className="relative z-[1] flex-1 min-h-0 overflow-y-auto overflow-x-clip overscroll-contain min-w-0 w-full max-w-full bg-bg-secondary px-4 pt-5 pb-6 rounded-t-2xl -mt-3 sm:px-5 shell-desktop:mt-0 shell-desktop:rounded-none shell-desktop:px-8 shell-desktop:pt-8 shell-desktop:pb-8 xl:px-12 xl:pb-12">
           <HomeQuickMenu className={cn("mb-6", shellMobileOnly)} />
 
           <HomeDashboardSection
             {...dashboardProps}
-            className="mt-0"
+            className="mt-0 w-full max-w-full"
           />
         </main>