Claude/merge familyos docs ps vhx

docs/familyos/PRD.md

@@ -0,0 +1,183 @@
+# Product Requirements Document (PRD)
+## FamilyOS — Family Task Management App
+
+**Version:** 1.0
+**Status:** Draft — Awaiting Approval
+**Last Updated:** 2025-12-14
+
+---
+
+## 📋 Product Vision
+
+FamilyOS is a calm, Apple Health-style family task management application that helps families coordinate routine tasks, one-off chores, and scheduled activities without overwhelm. The UI prioritizes clarity, safety, and simplicity over cleverness.
+
+**Primary User:** Non-technical family coordinators (parents, caregivers) who need a low-friction way to manage household responsibilities.
+
+**Design Philosophy:** Calm technology. Minimal cognitive load. Health-app aesthetic.
+
+---
+
+## 🎯 Core Goals
+
+1. **Family Coordination:** Allow multiple family members to view and manage shared tasks
+2. **Routine Management:** Support recurring tasks (daily, weekly, custom schedules)
+3. **Simple Auth:** Google-based authentication — no password management
+4. **Production-Ready:** Deploy cleanly to Vercel without container or localhost assumptions
+5. **Graceful Degradation:** Fail gracefully if env vars are missing or services are down
+
+---
+
+## ✅ Core Features (MVP)
+
+### 1. Authentication
+- Google Auth via Firebase Auth or NextAuth.js
+- Family profile creation (one account can create/manage a family)
+- No username/password — Google SSO only
+
+### 2. Family Profiles
+- Create a family
+- Invite family members via email (future: invite links)
+- View family member list
+- Assign tasks to specific members
+
+### 3. Task Management
+- **Routine Tasks:** Recurring tasks (e.g., "Take out trash every Tuesday")
+- **One-Off Tasks:** Single tasks with optional due dates
+- **Scheduled Items:** Calendar-style events (e.g., "Doctor appointment on Jan 15")
+- Mark tasks as complete
+- View completed history (past 30 days)
+
+### 4. UI/UX
+- **Apple Health-style design:**
+  - Sans-serif fonts (system fonts preferred)
+  - Pastel accents (soft blues, greens, no harsh reds)
+  - Generous whitespace
+  - Card-based layouts
+  - Minimal icons
+- Mobile-first responsive design
+- Light mode (dark mode deferred to v2)
+
+### 5. Deployment
+- Must deploy to Vercel
+- `npm run build` must succeed locally and in CI/CD
+- No Docker or container dependencies
+- Graceful fallback if Firebase or DB is unavailable (show error message, not crash)
+
+---
+
+## 🚫 Non-Goals (Out of Scope for MVP)
+
+- **No notifications/reminders** (push, email, SMS) — deferred to v2
+- **No gamification** (points, streaks, badges) — not aligned with "calm" philosophy
+- **No file uploads** (task attachments) — deferred to v2
+- **No calendar sync** (Google Calendar, Outlook) — deferred to v2
+- **No dark mode** — deferred to v2
+- **No real-time collaboration** (live updates) — polling or refresh is acceptable
+- **No custom recurrence rules** beyond basic daily/weekly/monthly — keep it simple
+- **No analytics/tracking** — privacy-first approach
+
+---
+
+## 📊 Success Metrics
+
+**Technical:**
+- `npm run build` succeeds with zero errors
+- Vercel deployment succeeds without manual intervention
+- Page load time < 2 seconds (95th percentile)
+- Zero console errors in production
+
+**User:**
+- User can create a family and add 2+ members in < 5 minutes
+- User can create a routine task in < 1 minute
+- User can mark a task complete in < 10 seconds
+- 90% of users complete onboarding without help docs
+
+---
+
+## 🛡️ Constraints & Guardrails
+
+1. **Vercel Deployment Contract:**
+   - Must use Vercel-compatible framework (Next.js App Router or Astro SSR)
+   - Must have explicit build output directory
+   - No serverless function time limits exceeded (10s max)
+   - No Docker or custom build scripts that break Vercel zero-config
+
+2. **No Localhost Assumptions:**
+   - All features must work on production URLs (https://familyos.vercel.app)
+   - No hardcoded localhost or 127.0.0.1 references
+   - Redirect URIs must be configurable via env vars
+
+3. **Graceful Failure:**
+   - If Firebase config is missing, show "Authentication unavailable" — don't crash
+   - If database is down, show error page with retry button — don't hang
+   - All env vars must have fallback or validation
+
+4. **No Scope Creep:**
+   - Stick to MVP features listed above
+   - Defer all "nice to have" features to backlog
+   - Require written justification for any new dependency
+
+5. **Token Budget:**
+   - Use Task agents for codebase exploration
+   - Avoid reading large generated files (lock files, build outputs)
+   - Summarize before reading files >300 lines
+
+---
+
+## 🗺️ User Flows
+
+### Flow 1: New User Onboarding
+1. User visits `/` (landing page)
+2. Clicks "Sign in with Google"
+3. Redirected to Google OAuth consent
+4. Returns to app, creates family profile
+5. Adds family members (email addresses)
+6. Creates first routine task
+7. Sees dashboard with task list
+
+### Flow 2: Daily Task Completion
+1. User signs in
+2. Sees today's tasks (routines + one-offs due today)
+3. Clicks checkbox to mark task complete
+4. Task moves to "Completed" section
+5. If routine, next occurrence is scheduled
+
+### Flow 3: Adding a Routine Task
+1. User clicks "Add Routine"
+2. Fills form:
+   - Task name (e.g., "Water plants")
+   - Assigned to (family member dropdown)
+   - Frequency (daily, weekly, custom)
+   - Start date
+3. Saves task
+4. Task appears in dashboard on scheduled days
+
+---
+
+## 🚀 Next Steps (After PRD Approval)
+
+1. **Review & Approve PRD** ← You are here
+2. Generate SPEC.md (routes, data model, components)
+3. Generate TOOLING_PLAN.md (framework choice, dependencies)
+4. Generate HANDOFF_PROMPT.md (build tickets, stop points)
+5. Scaffold repo with approved tooling
+6. Implement features per build order
+7. Deploy to Vercel
+8. User acceptance testing
+
+---
+
+## ❓ Open Questions
+
+- **Q:** Which framework — Next.js App Router or Astro SSR?
+  - **A:** Recommend Next.js (more mature auth ecosystem, better Vercel integration)
+
+- **Q:** Which database — Vercel Postgres, Supabase, or Firebase?
+  - **A:** Recommend Vercel Postgres (native integration) or Supabase (generous free tier)
+
+- **Q:** Which auth — Firebase Auth or NextAuth.js?
+  - **A:** Recommend NextAuth.js (Next.js native, simpler config)
+
+---
+
+**Approval Required:** Please review and approve this PRD before proceeding to SPEC.md.

docs/familyos/README.md

@@ -0,0 +1,215 @@
+# FamilyOS — Planning Documentation
+
+**Status:** Planning Complete ✅
+**Next Phase:** Setup & Implementation
+**Created:** 2025-12-14
+
+---
+
+## 📚 Documentation Index
+
+This directory contains all planning and handoff documentation for FamilyOS, a calm, Apple Health-style family task management application.
+
+### 📖 Read in This Order
+
+1. **[PRD.md](./PRD.md)** — Product Requirements Document
+   - Product vision and goals
+   - Core features (MVP scope)
+   - Non-goals (deferred to v2)
+   - Success metrics
+   - User flows
+
+2. **[SPEC.md](./SPEC.md)** — Technical Specification
+   - System architecture
+   - Data model (tables, relationships)
+   - Routes and pages
+   - Component structure
+   - Business logic (routine task scheduling)
+   - UI/UX design tokens
+
+3. **[TOOLING_PLAN.md](./TOOLING_PLAN.md)** — Claude Code Configuration
+   - Memory payload (pinned context)
+   - Hooks checklist (pre-coding, pre-commit)
+   - Skills list (reusable playbooks)
+   - Documentation plan
+   - MCP connector plan
+   - Deployment contract (formalized)
+
+4. **[TOKEN_ECONOMICS.md](./TOKEN_ECONOMICS.md)** — Context Management
+   - Token budget philosophy
+   - Token cost estimates (high/medium/low)
+   - Token-saving strategies
+   - Checkpoint monitoring
+   - Warning signs (context exhaustion)
+   - Expected token breakdown per phase
+
+5. **[SETUP_PACK.md](./SETUP_PACK.md)** — Development Setup
+   - Prerequisites (Node, npm, Google OAuth, database)
+   - Step-by-step scaffolding instructions
+   - Dependency installation
+   - Environment variable configuration
+   - Build verification checklist
+   - Common setup issues
+
+6. **[HANDOFF_PROMPT.md](./HANDOFF_PROMPT.md)** — Implementation Guide ⭐
+   - **START HERE for implementation**
+   - Rules & guardrails (deployment contract, code quality, scope control)
+   - Step-by-step build order (9 phases, 30+ tickets)
+   - Explicit stop points
+   - Definition of Done per phase
+   - Success criteria (final verification)
+
+7. **[DEPLOYMENT.md](./DEPLOYMENT.md)** — Production Deployment Guide
+   - Vercel deployment step-by-step
+   - Database setup (Vercel Postgres & Supabase)
+   - Google OAuth production configuration
+   - Environment variable setup
+   - Database migration instructions
+   - Complete verification checklist
+   - Troubleshooting guide
+   - Security checklist
+
+---
+
+## 🚀 Quick Start
+
+### For Planning Review:
+1. Read **PRD.md** to understand product goals
+2. Read **SPEC.md** to understand technical approach
+3. Approve or request changes
+
+### For Implementation:
+1. Read all 7 documents above (in order)
+2. Follow **HANDOFF_PROMPT.md** step-by-step
+3. Do NOT skip tickets or stop points
+
+### For Deployment:
+1. Complete implementation following **HANDOFF_PROMPT.md**
+2. Follow **DEPLOYMENT.md** for production deployment
+3. Use verification checklist to ensure deployment contract compliance
+
+---
+
+## 🎯 Project Context
+
+### What is FamilyOS?
+A calm, Apple Health-style family task management app with:
+- Google Auth (no passwords)
+- Family profiles (shared task lists)
+- Routine tasks (daily, weekly, monthly)
+- One-off tasks (with due dates)
+- Scheduled items (calendar events)
+
+### Why This Matters
+This project has previously suffered from:
+- Container vs browser preview confusion
+- Unreliable Vercel deployments
+- Missing deployment contracts
+- Tooling assumptions
+- Scope creep before fundamentals were agreed
+
+**This documentation ensures those failures don't happen again.**
+
+---
+
+## 🛡️ Deployment Contract (Summary)
+
+The final app MUST:
+1. ✅ Deploy cleanly to Vercel (no Docker, no containers)
+2. ✅ Have deterministic `npm run build` (succeeds every time)
+3. ✅ Have explicit framework (Next.js App Router) and output directory (`.next`)
+4. ✅ Not rely on container-only assumptions
+5. ✅ Not rely on localhost behavior
+6. ✅ Fail gracefully if env vars are missing
+
+**See TOOLING_PLAN.md for full contract details.**
+
+---
+
+## 📊 Project Status
+
+### ✅ Completed Phases
+- [x] Planning (PRD, SPEC, TOOLING_PLAN)
+- [x] Setup instructions (SETUP_PACK)
+- [x] Implementation guide (HANDOFF_PROMPT)
+- [x] Token budget strategy (TOKEN_ECONOMICS)
+
+### ⏳ Pending Phases
+- [ ] Setup & Scaffolding (Phase 1)
+- [ ] Database Schema (Phase 2)
+- [ ] Authentication (Phase 3)
+- [ ] UI Foundation (Phase 4)
+- [ ] Dashboard & Families (Phase 5)
+- [ ] Task Management (Phase 6)
+- [ ] Routine Scheduling (Phase 7)
+- [ ] Deployment (Phase 8)
+- [ ] Final Verification (Phase 9)
+
+---
+
+## 🔗 Tech Stack (Approved)
+
+- **Framework:** Next.js 15+ (App Router)
+- **Language:** TypeScript 5+
+- **Database:** Vercel Postgres (or Supabase)
+- **ORM:** Drizzle ORM
+- **Auth:** NextAuth.js v5 (Google provider)
+- **Styling:** Tailwind CSS 4+ + shadcn/ui
+- **Hosting:** Vercel
+
+---
+
+## 📋 Key Decisions Made
+
+1. **Framework:** Next.js (over Astro) — better auth ecosystem, Vercel-native
+2. **Database:** Vercel Postgres (over Supabase) — simpler integration
+3. **ORM:** Drizzle (over Prisma) — lighter, better for serverless
+4. **UI:** shadcn/ui (over custom) — Radix + Tailwind, copy-paste components
+5. **Routine Tasks:** Virtual tasks (over generated instances) — simpler for MVP
+
+**See SPEC.md for full justifications.**
+
+---
+
+## 🚨 DO NOT DO (Guardrails)
+
+1. ❌ Write code before reading all planning docs
+2. ❌ Skip tickets or stop points in HANDOFF_PROMPT.md
+3. ❌ Add features not in PRD.md (no scope creep)
+4. ❌ Use Docker or containers for production
+5. ❌ Assume localhost behavior
+6. ❌ Commit secrets or `.env.local` to git
+7. ❌ Deploy without verifying `npm run build` succeeds
+8. ❌ Read large generated files (lock files, build outputs)
+9. ❌ Over-engineer solutions (keep it simple)
+10. ❌ Proceed past stop points without verification
+
+---
+
+## 📞 Support
+
+If you have questions about this documentation:
+1. Check the relevant doc file (use index above)
+2. Search for keywords in HANDOFF_PROMPT.md
+3. Review SPEC.md for technical details
+4. Review PRD.md for product context
+
+---
+
+## 📝 Document Versions
+
+| Document | Version | Last Updated |
+|----------|---------|--------------|
+| PRD.md | 1.0 | 2025-12-14 |
+| SPEC.md | 1.0 | 2025-12-14 |
+| TOOLING_PLAN.md | 1.0 | 2025-12-14 |
+| TOKEN_ECONOMICS.md | 1.0 | 2025-12-14 |
+| SETUP_PACK.md | 1.0 | 2025-12-14 |
+| HANDOFF_PROMPT.md | 1.0 | 2025-12-14 |
+| DEPLOYMENT.md | 1.0 | 2025-12-15 |
+
+---
+
+**Ready to start?** Read **HANDOFF_PROMPT.md** and follow the build order step-by-step. 🚀
+
+**Ready to deploy?** Follow **DEPLOYMENT.md** for production deployment to Vercel.