docs: expand AI Clock raw idea into comprehensive PRD (ChronoMind)

2026-02-27 16:40:26 -08:00 · 2026-02-27 16:40:26 -08:00 · 67e17609ca
commit 67e17609ca
2 changed files with 678 additions and 0 deletions
--- a/docs/PRD.md
+++ b/docs/PRD.md
@ -0,0 +1,677 @@
+# ChronoMind — AI-Powered Contextual Clock & Timer
+
+> **Product:** ChronoMind
+> **Repo:** `learning_ai_clock`
+> **Version:** 0.1 (MVP)
+> **Date:** February 2026
+> **Author:** Saravana
+
+---
+
+## 1. Origin (Raw Idea)
+
+> Build an alarm clock to set a specified date and time and also give a warning maybe with a configured 1 hour to 2 hours before that. For example if the alarm is going to go off in 2 hours, so that the user can remember or take action or let it ring depending on the critical task they are supposed to do during the time.
+
+---
+
+## 2. Vision
+
+**ChronoMind** is a context-aware, AI-augmented clock/timer application that understands *why* you set a timer — not just *when*. It provides intelligent pre-warnings, adaptive escalation, routine orchestration, and natural language interaction. It bridges the gap between dumb alarms and full calendar apps by focusing on one thing: **making sure you never miss what matters, and always have time to prepare.**
+
+### The Problem with Current Timers & Clocks
+
+| Gap | Current Market | ChronoMind |
+|-----|---------------|------------|
+| **No pre-warnings** | Alarm fires once, at the exact time | Configurable cascade: 2h → 1h → 30m → 15m → 5m → NOW |
+| **No context** | "Alarm at 3:00 PM" — why? | "Meeting with Sarah in 2 hours — prep slides?" |
+| **No urgency levels** | Every alarm sounds the same | Critical (can't miss) → Important → Casual → Gentle |
+| **No prep-time awareness** | You set alarm for meeting at 3pm, forget 20min prep | Auto-adds prep buffer: "Start preparing at 2:40 PM" |
+| **No travel awareness** | Alarm for dentist at 2pm, 30min drive away | "Leave by 1:25 PM (traffic is heavy today)" |
+| **No chaining** | Timer for pasta, but forget sauce timing | Linked timers: "Boil water → Add pasta → Start sauce at T-3min" |
+| **No routines** | Set same 5 alarms every morning manually | "Morning routine" = Wake → Meditate (10m) → Exercise (30m) → Shower (15m) → Leave |
+| **No countdown to events** | Separate app for "days until vacation" | Built-in event countdown with milestone warnings |
+| **No shared timers** | Can't coordinate with family/team | "Pizza timer" visible to everyone in household |
+| **No natural language** | Tap through 4 screens to set a timer | "Remind me to call Mom 2 hours before my flight" |
+| **No adaptive snooze** | Fixed 5/10min snooze | Snooze learns: "You always snooze this one 3 times — should I set it 15min earlier?" |
+| **No focus integration** | Timer has no concept of deep work | "Block notifications for 90min, warn me 10min before standup" |
+| **No voice** | Visual-only or basic "Hey Siri" | Full voice control: "What's my next timer?" / "Push everything back 30 minutes" |
+
+---
+
+## 3. Target Platforms
+
+| Phase | Platform | Tech Stack |
+|-------|----------|------------|
+| **MVP** | Web app (PWA) | Next.js 14, React 18, CSS custom properties |
+| **v1.1** | macOS menu bar | Tauri or SwiftUI |
+| **v1.2** | iOS app | SwiftUI (native) |
+| **v2.0** | Android | Jetpack Compose |
+| **v2.0** | Windows | Tauri |
+
+> **MVP is web-first** — works on any device, installable as PWA with notification support.
+
+---
+
+## 4. Core Concepts
+
+### 4.1 Timer Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Alarm** | Fires at a specific date/time | "Wake up at 6:30 AM" |
+| **Countdown** | Fires after a duration | "Timer for 25 minutes" |
+| **Event Countdown** | Days/hours until a future date | "14 days until vacation" |
+| **Routine** | Ordered sequence of timed steps | "Morning routine (5 steps, 75 min total)" |
+| **Linked Timer** | Timer that triggers another timer | "When pasta timer ends, start sauce timer" |
+| **Recurring** | Repeats on a schedule | "Every weekday at 9:00 AM" |
+| **Shared** | Visible/controllable by multiple people | "Family dinner timer" |
+
+### 4.2 Urgency Levels
+
+Every timer has an urgency level that controls notification behavior:
+
+```
+┌─────────────┬────────────────────────────────────────────────────────────────┐
+│ Level       │ Behavior                                                       │
+├─────────────┼────────────────────────────────────────────────────────────────┤
+│ CRITICAL    │ Full screen takeover, persistent sound, vibration, cannot      │
+│             │ dismiss without acknowledgment. Pre-warnings at 2h, 1h, 30m,  │
+│             │ 15m, 5m, 1m. Example: flight departure, job interview.        │
+│             │                                                                │
+│ IMPORTANT   │ Prominent notification with sound. Pre-warnings at 1h, 30m,   │
+│             │ 15m, 5m. Snooze allowed (max 3x). Example: team meeting,      │
+│             │ doctor appointment.                                            │
+│             │                                                                │
+│ STANDARD    │ Normal notification with gentle sound. Pre-warnings at 30m,   │
+│             │ 5m. Snooze allowed. Example: laundry, cooking timer.           │
+│             │                                                                │
+│ GENTLE      │ Silent notification (badge/banner only). Single pre-warning   │
+│             │ at 15m. Auto-dismiss after 2 minutes. Example: "check on      │
+│             │ bread in oven", casual reminder.                               │
+│             │                                                                │
+│ PASSIVE     │ No notification at all — just visible in the app timeline.    │
+│             │ For event countdowns and tracking. Example: "days until        │
+│             │ vacation", "months until lease renewal".                       │
+└─────────────┴────────────────────────────────────────────────────────────────┘
+```
+
+### 4.3 Pre-Warning Cascade
+
+The core differentiator. Every timer can have a **configurable cascade** of pre-warnings before the main alarm fires.
+
+```
+Example: Flight at 2:00 PM (CRITICAL)
+
+  10:00 AM  [-4h]  "Flight to NYC in 4 hours. Have you packed?"
+  11:00 AM  [-3h]  "Flight in 3 hours. Check-in reminder."
+  12:00 PM  [-2h]  "Flight in 2 hours. Start getting ready."
+  12:30 PM  [-90m] "Flight in 90 minutes. Suggested: leave in 45 min."
+   1:00 PM  [-1h]  "Flight in 1 HOUR. Leave NOW if driving."
+   1:30 PM  [-30m] "Flight in 30 minutes. You should be at airport."
+   1:45 PM  [-15m] "BOARDING SOON — 15 minutes."
+   2:00 PM  [  0 ] "FLIGHT TIME — NOW"
+```
+
+**Default cascade presets:**
+
+| Preset | Warnings At | Best For |
+|--------|-------------|----------|
+| **Aggressive** | 4h, 3h, 2h, 90m, 1h, 30m, 15m, 5m, 1m | Flights, once-in-a-lifetime events |
+| **Standard** | 2h, 1h, 30m, 15m, 5m | Meetings, appointments |
+| **Light** | 1h, 15m, 5m | Cooking, laundry, casual |
+| **Minimal** | 15m | Gentle reminders |
+| **None** | — (fire only) | Simple countdown timers |
+| **Custom** | User-defined | Any |
+
+### 4.4 Prep Time & Travel Time
+
+Timers can optionally include **prep time** and **travel time** that shifts warnings earlier.
+
+```
+Example: Dentist at 2:00 PM
+  + Prep time: 15 min (get dressed, grab wallet)
+  + Travel time: 25 min (auto-estimated or manual)
+  + Buffer: 5 min (arrive early)
+
+  Effective "start preparing" time: 1:15 PM
+  Effective "leave by" time: 1:30 PM
+
+  Warnings shift to target 1:15 PM for prep, 1:30 PM for departure.
+```
+
+**Travel time estimation** (v1.1+):
+- Manual entry (MVP)
+- Integration with maps API for real-time traffic estimates (v2)
+- Learn from past patterns: "You usually take 35 min to get to the office"
+
+---
+
+## 5. Feature Breakdown
+
+### 5.1 MVP (v0.1) — Web PWA
+
+| # | Feature | Priority | Description |
+|---|---------|----------|-------------|
+| 1 | **Create alarm** | P0 | Set date/time, label, urgency level |
+| 2 | **Create countdown** | P0 | Set duration, label, urgency level |
+| 3 | **Pre-warning cascade** | P0 | Configure cascade per timer (presets + custom) |
+| 4 | **Urgency levels** | P0 | 5 levels controlling notification style |
+| 5 | **Active timers dashboard** | P0 | See all timers, sorted by "next to fire" |
+| 6 | **Browser notifications** | P0 | Push notifications via Web Notifications API |
+| 7 | **Sound alerts** | P0 | Multiple alarm sounds, volume per urgency |
+| 8 | **Snooze / dismiss** | P0 | Snooze with configurable duration, dismiss with confirmation for CRITICAL |
+| 9 | **Recurring timers** | P1 | Daily, weekday, weekly, monthly, custom cron |
+| 10 | **Timer labels + notes** | P1 | Add context: "Call Dr. Smith — phone: 555-1234" |
+| 11 | **Dark mode** | P1 | Full dark theme (default) |
+| 12 | **PWA install** | P1 | Installable on mobile/desktop via browser |
+| 13 | **Local storage** | P1 | All data in IndexedDB — no account needed |
+| 14 | **Timer history** | P2 | Past timers log with stats |
+| 15 | **Keyboard shortcuts** | P2 | Quick-create, navigate, snooze |
+| 16 | **Quick timer** | P0 | One-tap presets: 5m, 15m, 25m (pomodoro), 1h |
+
+### 5.2 v1.0 — Intelligence Layer
+
+| # | Feature | Description |
+|---|---------|-------------|
+| 17 | **Natural language input** | "Remind me to call Mom at 3pm with 1 hour warning" |
+| 18 | **Routines** | Create ordered sequences of timed steps |
+| 19 | **Linked timers** | "When timer A ends, start timer B" |
+| 20 | **Prep time** | Add preparation buffer before any timer |
+| 21 | **Adaptive snooze** | Learn snooze patterns, suggest earlier alarm |
+| 22 | **Focus mode** | Block notifications, only allow CRITICAL through |
+| 23 | **Event countdowns** | "132 days until wedding" with milestone warnings |
+| 24 | **Categories / tags** | Work, Personal, Health, Cooking, etc. |
+| 25 | **Statistics** | How many timers set, snooze rate, on-time rate |
+
+### 5.3 v2.0 — Platform Expansion
+
+| # | Feature | Description |
+|---|---------|-------------|
+| 26 | **Shared timers** | Family/team timers visible to invited users |
+| 27 | **Calendar sync** | Import from Google/Apple/Outlook calendars |
+| 28 | **Travel time (live)** | Maps API integration for real-time estimates |
+| 29 | **Voice control** | "What's my next alarm?" / "Push everything back 30 minutes" |
+| 30 | **Native apps** | macOS menu bar, iOS, Android, Windows |
+| 31 | **Watch complications** | Apple Watch, Wear OS |
+| 32 | **Widgets** | iOS/Android home screen widgets |
+| 33 | **API** | REST API for programmatic timer management |
+| 34 | **Zapier / webhooks** | Timer events trigger external actions |
+| 35 | **AI suggestions** | "You have a gap between 2-3pm, want to schedule focus time?" |
+
+---
+
+## 6. Routines (Deep Dive)
+
+Routines are a killer feature that no current timer app does well. A routine is an **ordered sequence of timed activities** with transitions.
+
+### Example: Morning Routine
+
+```
+Morning Routine                                   Total: 1h 35m
+
+  Step 1: Wake Up + Hydrate              5 min     6:00 - 6:05
+  Step 2: Meditation                    15 min     6:05 - 6:20
+  Step 3: Exercise                      30 min     6:20 - 6:50
+  Step 4: Shower + Get Ready            20 min     6:50 - 7:10
+  Step 5: Breakfast                     15 min     7:10 - 7:25
+  Step 6: Commute Buffer                10 min     7:25 - 7:35
+
+  Notification at each step transition
+  "Skip step" and "Extend +5min" buttons on each notification
+  Tracks actual vs planned duration over time
+```
+
+### Example: Cooking Routine (Linked Timers)
+
+```
+Thanksgiving Dinner Prep (work backwards from 6:00 PM serve time)
+
+  2:00 PM  Turkey in oven (4 hours)
+  4:30 PM  Start mashed potatoes (45 min)
+  5:00 PM  Start gravy (30 min)
+  5:15 PM  Rolls in oven (25 min)
+  5:30 PM  Set table (15 min)
+  5:45 PM  Turkey resting (15 min, auto-started when turkey timer ends)
+  6:00 PM  Serve!
+
+  All timers visible in one timeline view with progress bars.
+```
+
+### Example: Pomodoro Focus Session
+
+```
+Focus Session: "Write PRD"
+
+  Round 1:  25 min work -> 5 min break
+  Round 2:  25 min work -> 5 min break
+  Round 3:  25 min work -> 5 min break
+  Round 4:  25 min work -> 15 min long break
+
+  Total: 2h 10m
+  Focus mode active (only CRITICAL timers break through)
+  Track completed rounds, interruptions
+```
+
+---
+
+## 7. User Interface
+
+### 7.1 Design Principles
+
+| Principle | Rationale |
+|-----------|-----------|
+| **Glanceable** | See time-to-next-alarm in < 1 second |
+| **One-tap creation** | Quick timer presets always visible |
+| **Dark-first** | Alarm apps are used in bed, at night |
+| **Information density** | Power users want to see all timers at once |
+| **Accessible** | Large touch targets, high contrast, screen reader support |
+| **Beautiful sounds** | Alarm sounds that don't trigger anxiety |
+
+### 7.2 Key Screens
+
+```
+SCREEN MAP
+
+  Dashboard       Create         Routines
+  (Home)          Timer
+
+  - Clock         - Alarm        - Templates
+  - Next up       - Countdown    - Active
+  - Timeline      - Event        - History
+  - Quick         - Routine
+    presets       - NL input
+
+  Focus           History        Settings
+  Mode            & Stats
+
+  - Pomodoro      - Past         - Sounds
+  - Custom          timers       - Defaults
+  - DND sync      - Streaks      - Theme
+                  - Insights     - Backup
+                                 - Import
+```
+
+### 7.3 Dashboard Layout
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  ChronoMind                                          Settings       │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│                         10:42:38 AM                                  │
+│                       Thursday, Feb 27                               │
+│                                                                      │
+│  -- NEXT UP --------------------------------------------------------│
+│  |  [IMPORTANT] Team Standup                         in 1h 18m      │
+│  |  Pre-warning in 18 min - Prep: review tickets (15 min)           │
+│  ------------------------------------------------------------------ │
+│                                                                      │
+│  -- QUICK TIMER --------------------------------------------------- │
+│  |  [ 5m ]  [ 15m ]  [ 25m ]  [ 1h ]  [ Custom ]  [ NL Input ]    │
+│  ------------------------------------------------------------------ │
+│                                                                      │
+│  -- TIMELINE ------------------------------------------------------ │
+│  |                                                                 | │
+│  |  12:00 PM  [IMPORTANT] Team Standup ............. in 1h 18m     | │
+│  |            Pre-warning at 11:00 AM (in 18m)                     | │
+│  |                                                                 | │
+│  |   2:00 PM  [STANDARD] Dentist Appointment ....... in 3h 18m    | │
+│  |            Leave by 1:30 PM (25 min drive)                      | │
+│  |                                                                 | │
+│  |   5:00 PM  [GENTLE] Pick up dry cleaning ........ in 6h 18m    | │
+│  |                                                                 | │
+│  |   6:30 PM  [STANDARD] Pasta timer (linked) ...... in 7h 48m    | │
+│  |            -> Sauce timer starts when this ends                 | │
+│  |                                                                 | │
+│  |  -- Tomorrow -------------------------------------------------- | │
+│  |   6:00 AM  Morning Routine (1h 35m) ............ in 19h 18m    | │
+│  |   9:00 AM  [IMPORTANT] Sprint Planning ......... in 22h 18m    | │
+│  |                                                                 | │
+│  |  -- Event Countdowns ------------------------------------------ | │
+│  |   [PASSIVE] Vacation in 47 days                                 | │
+│  |   [PASSIVE] Lease renewal in 132 days                           | │
+│  |                                                                 | │
+│  ------------------------------------------------------------------ │
+│                                                                      │
+│  -- ACTIVE ROUTINES ---------------------------------------------- │
+│  |  Morning Routine          Weekdays at 6:00 AM      [Edit]      | │
+│  |  Pomodoro Focus           On-demand                 [Start]     | │
+│  |  Wind Down                Daily at 9:30 PM          [Edit]      | │
+│  ------------------------------------------------------------------ │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 8. Technical Architecture (MVP)
+
+### 8.1 Stack
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| **Framework** | Next.js 14 (Pages Router) | Fast, SSR for landing, PWA-friendly |
+| **UI** | React 18 + CSS custom properties | No Tailwind — clean vanilla CSS like MindLyst web |
+| **State** | Zustand | Lightweight, persists to IndexedDB |
+| **Storage** | IndexedDB (via idb) | Offline-first, no backend needed for MVP |
+| **Notifications** | Web Notifications API + Service Worker | Works when app is backgrounded (PWA) |
+| **Audio** | Web Audio API | Low-latency alarm sounds |
+| **Time** | date-fns | Lightweight date manipulation |
+| **PWA** | next-pwa | Service worker, offline support, installable |
+| **Testing** | Vitest + Playwright | Unit + E2E |
+
+### 8.2 Data Model
+
+```typescript
+interface Timer {
+  id: string;                    // UUID
+  type: 'alarm' | 'countdown' | 'event' | 'routine_step';
+  label: string;
+  notes?: string;
+  urgency: 'critical' | 'important' | 'standard' | 'gentle' | 'passive';
+
+  // When it fires
+  targetTime: Date;              // For alarms: specific datetime
+  duration?: number;             // For countdowns: milliseconds
+  startedAt?: Date;              // For countdowns: when started
+
+  // Pre-warning cascade
+  cascade: CascadePreset | number[];  // Preset name or custom minutes array
+  preWarnings: PreWarning[];          // Computed from cascade
+
+  // Optional enhancements
+  prepTime?: number;             // Minutes of preparation time
+  travelTime?: number;           // Minutes of travel time
+  location?: string;             // For travel time estimation
+
+  // Recurrence
+  recurrence?: RecurrenceRule;
+
+  // Linking
+  linkedTimerId?: string;        // Timer to start when this one fires
+  routineId?: string;            // Parent routine
+  routineStep?: number;          // Step index in routine
+
+  // State
+  status: 'active' | 'paused' | 'fired' | 'dismissed' | 'snoozed';
+  snoozedUntil?: Date;
+  snoozeCount: number;
+  firedAt?: Date;
+  dismissedAt?: Date;
+  acknowledgedAt?: Date;         // For CRITICAL: must explicitly acknowledge
+
+  // Metadata
+  category?: string;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface PreWarning {
+  minutesBefore: number;
+  message: string;
+  firedAt?: Date;
+  status: 'pending' | 'fired' | 'skipped';
+}
+
+interface Routine {
+  id: string;
+  name: string;
+  steps: RoutineStep[];
+  totalDuration: number;         // Computed sum
+  schedule?: RecurrenceRule;     // When this routine runs
+  status: 'template' | 'active' | 'completed';
+  startedAt?: Date;
+  currentStep: number;
+}
+
+interface RoutineStep {
+  label: string;
+  duration: number;              // Minutes
+  notes?: string;
+  sound?: string;                // Transition sound
+  skippable: boolean;
+  extendable: boolean;           // Allow +5min
+}
+
+type CascadePreset = 'aggressive' | 'standard' | 'light' | 'minimal' | 'none';
+
+interface RecurrenceRule {
+  frequency: 'daily' | 'weekdays' | 'weekends' | 'weekly' | 'monthly' | 'custom';
+  daysOfWeek?: number[];         // 0=Sun, 6=Sat
+  interval?: number;             // Every N days/weeks/months
+  endDate?: Date;
+}
+```
+
+### 8.3 Notification Architecture
+
+```
+Timer Engine (runs in Service Worker)
+
+  Timer Store    -->   Scheduler        -->   Notification
+  (IndexedDB)         (checks every           Dispatcher
+                       30 seconds)
+                                                  |
+                              ┌───────────────────┤
+                              |                   |
+                     Web Push              In-App Alert
+                     (backgrounded)        (foregrounded)
+
+                     - OS banner           - Full-screen (CRITICAL)
+                     - Sound               - Toast (others)
+                     - Badge               - Sound
+                     - Vibration
+```
+
+**Key challenge:** Browser Service Workers can be killed by the OS. Mitigation:
+- Schedule next-fire via `setTimeout` with periodic checks every 30s
+- Use `navigator.serviceWorker` for background notifications
+- Fallback: `setInterval` poll in active tab
+- Critical timers register OS-level alarms where supported (native app)
+
+### 8.4 Project Structure
+
+```
+learning_ai_clock/
+├── docs/
+│   ├── raw_idea.md              # Original idea
+│   └── PRD.md                   # This document
+├── web/                         # Next.js 14 web app
+│   ├── src/
+│   │   ├── pages/               # Pages Router
+│   │   │   ├── index.tsx        # Landing page
+│   │   │   ├── app.tsx          # Main app (dashboard)
+│   │   │   ├── create.tsx       # Create timer
+│   │   │   ├── routines.tsx     # Routines
+│   │   │   ├── focus.tsx        # Focus / pomodoro
+│   │   │   ├── history.tsx      # Timer history
+│   │   │   └── settings.tsx     # Settings
+│   │   ├── components/
+│   │   │   ├── Clock.tsx        # Large analog/digital clock
+│   │   │   ├── TimerCard.tsx    # Individual timer display
+│   │   │   ├── Timeline.tsx     # Vertical timeline of upcoming
+│   │   │   ├── QuickTimer.tsx   # One-tap preset buttons
+│   │   │   ├── CascadeEditor.tsx# Pre-warning cascade config
+│   │   │   ├── RoutineEditor.tsx# Routine step editor
+│   │   │   ├── AlarmOverlay.tsx # Full-screen alarm (CRITICAL)
+│   │   │   └── NLInput.tsx      # Natural language input
+│   │   ├── lib/
+│   │   │   ├── timer-engine.ts  # Core scheduling logic
+│   │   │   ├── store.ts         # Zustand store + IndexedDB
+│   │   │   ├── notifications.ts # Web Notifications wrapper
+│   │   │   ├── sounds.ts        # Web Audio API sounds
+│   │   │   ├── cascade.ts       # Pre-warning cascade logic
+│   │   │   ├── recurrence.ts    # Recurrence rule engine
+│   │   │   └── nl-parser.ts     # Natural language time parser
+│   │   └── styles/
+│   │       └── globals.css      # Full design system
+│   ├── public/
+│   │   ├── sounds/              # Alarm sound files
+│   │   └── icons/               # PWA icons
+│   ├── package.json
+│   └── next.config.js
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 9. Design System
+
+### 9.1 Color Palette (Dark Theme)
+
+| Token | Hex | Use |
+|-------|-----|-----|
+| `--cm-bg` | `#0A0B0F` | Page background |
+| `--cm-surface` | `#12141D` | Cards, panels |
+| `--cm-surface-hover` | `#1A1D2A` | Hover states |
+| `--cm-border` | `#2A2D3A` | Borders |
+| `--cm-text` | `#E8ECF4` | Primary text |
+| `--cm-text-secondary` | `#8A92A6` | Secondary text |
+| `--cm-text-muted` | `#5A6178` | Timestamps, hints |
+| `--cm-critical` | `#FF4757` | Critical urgency |
+| `--cm-important` | `#FF9F43` | Important urgency |
+| `--cm-standard` | `#FECA57` | Standard urgency |
+| `--cm-gentle` | `#2ED573` | Gentle urgency |
+| `--cm-passive` | `#5B8DEE` | Passive/info |
+| `--cm-accent` | `#5B8DEE` | Primary accent, links |
+| `--cm-accent-glow` | `#5B8DEE33` | Glow effects on timers |
+
+### 9.2 Typography
+
+| Token | Font | Weight | Use |
+|-------|------|--------|-----|
+| `--cm-font-display` | Space Grotesk | 700 | Clock face, timer digits |
+| `--cm-font-body` | Inter | 400/500/600 | Body text, labels |
+| `--cm-font-mono` | JetBrains Mono | 400 | Countdown digits, time displays |
+
+### 9.3 Clock Face Digits
+
+The main clock display uses a large, beautiful monospaced font with a subtle glow effect:
+
+```css
+.clock-display {
+  font-family: var(--cm-font-mono);
+  font-size: 4rem;
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.05em;
+  color: var(--cm-text);
+  text-shadow: 0 0 30px var(--cm-accent-glow);
+}
+```
+
+---
+
+## 10. Competitive Analysis
+
+| Feature | iOS Clock | Google Clock | Alarmy | Due | Toggl Track | **ChronoMind** |
+|---------|----------|-------------|--------|-----|-------------|----------------|
+| Basic alarm | Yes | Yes | Yes | Yes | No | **Yes** |
+| Countdown timer | Yes | Yes | No | Yes | Yes | **Yes** |
+| Pre-warnings | No | No | No | No | No | **Yes (core)** |
+| Urgency levels | No | No | Partial | No | No | **Yes** |
+| Cascade config | No | No | No | No | No | **Yes** |
+| Routines | No | No | No | No | No | **Yes** |
+| Linked timers | No | No | No | No | No | **Yes** |
+| Prep time | No | No | No | No | No | **Yes** |
+| Travel time | No | No | No | No | No | **Yes** |
+| Focus / pomodoro | No | No | No | No | Yes | **Yes** |
+| Event countdowns | No | No | No | No | No | **Yes** |
+| Natural language | Siri | Google | No | No | No | **Yes** |
+| Shared timers | No | No | No | No | Yes (team) | **Yes (v2)** |
+| Adaptive snooze | No | No | No | No | No | **Yes (v1)** |
+| Web PWA | No | No | No | No | Yes | **Yes** |
+| Offline-first | N/A | N/A | Yes | Yes | No | **Yes** |
+| Free | Yes | Yes | Freemium | $7 | Freemium | **Yes** |
+
+**ChronoMind's moat:** No existing app combines pre-warning cascades + routines + linked timers + urgency levels + focus mode in a single, beautiful, offline-first web app. Most clock apps are feature-frozen utility apps from the early smartphone era.
+
+---
+
+## 11. Monetization (Future — v2+)
+
+ChronoMind is **free and open-source** for personal use. Potential future revenue:
+
+| Tier | Price | Features |
+|------|-------|----------|
+| **Free** | $0 | All MVP features, unlimited timers, local storage |
+| **Pro** | $4/mo | Cloud sync, shared timers, calendar integration, custom sounds |
+| **Team** | $8/user/mo | Team timers, admin dashboard, API access, webhooks |
+
+---
+
+## 12. Success Metrics (MVP)
+
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| **PWA installs** | 100 in first month | Service worker registration |
+| **Daily active users** | 50 | IndexedDB activity timestamp |
+| **Timers created/week** | 500+ | In-app analytics |
+| **Pre-warning engagement** | >60% of timers use cascade | Default-on, track opt-out |
+| **Routine usage** | >20% of users create a routine | Feature adoption tracking |
+| **Snooze rate** | <30% (means alarms are well-timed) | Snooze event tracking |
+
+---
+
+## 13. Development Phases
+
+### Phase 1: MVP (2 weeks)
+
+| Week | Deliverable |
+|------|------------|
+| Week 1 | Project setup, data model, timer engine, dashboard UI, create timer flow |
+| Week 2 | Pre-warning cascade, notifications, sounds, PWA, quick timers, dark theme |
+
+### Phase 2: Intelligence (2 weeks)
+
+| Week | Deliverable |
+|------|------------|
+| Week 3 | Routines, linked timers, focus/pomodoro mode |
+| Week 4 | Natural language input, recurring timers, prep time, history + stats |
+
+### Phase 3: Platform (4 weeks)
+
+| Week | Deliverable |
+|------|------------|
+| Week 5-6 | macOS menu bar app (Tauri/SwiftUI), cloud sync (optional) |
+| Week 7-8 | iOS native app, shared timers, calendar sync |
+
+---
+
+## 14. Open Questions
+
+| # | Question | Decision Needed |
+|---|----------|----------------|
+| 1 | Should MVP include cloud sync or be 100% local? | **Decision: local-only MVP, cloud in v1.1** |
+| 2 | Natural language parsing: local regex or LLM API? | **Decision: local regex MVP, optional LLM v2** |
+| 3 | Should the main clock be analog, digital, or both? | **Decision: digital primary, analog option** |
+| 4 | PWA notification reliability — is it good enough? | **Test: if <90% delivery, prioritize native** |
+| 5 | Should routines support branching (if/else steps)? | **Decision: linear-only MVP, branching v2** |
+
+---
+
+## 15. Appendix: Naming
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **ChronoMind** | Unique, conveys "smart time" | Slightly long |
+| **PreWarn** | Describes core feature | Too narrow |
+| **TimeShift** | Cool, implies flexibility | Vague |
+| **CascadeTimer** | Describes cascade feature | Too technical |
+| **Nudge** | Friendly, approachable | Generic |
+
+**Working name: ChronoMind** — subject to change.
+
+---
+
+## 16. Summary
+
+ChronoMind fills a real gap: the space between "dumb alarm" and "full calendar app." Every phone has a clock app, but none of them answer the question *"how do I make sure I'm prepared for what's coming?"*
+
+**Three core innovations:**
+1. **Pre-warning cascade** — configurable escalation so you're never surprised
+2. **Routines** — timed sequences that guide you through multi-step activities
+3. **Urgency-aware intelligence** — the app understands that a flight and a laundry timer are fundamentally different
+
+The MVP is achievable in 2 weeks as a web PWA with no backend dependency.
--- a/docs/raw_idea.md
+++ b/docs/raw_idea.md
@ -0,0 +1 @@
+Build an alarm clock to set a specified date and time and also give a warning maybe with a configured 1 hour to 2 hours before that. For example if the alarm is going to go off in 2 hours, so that the user can remember or take action or let it ring depending on the critical task they are supposed to do during the time
				`@ -0,0 +1 @@`
				`Build an alarm clock to set a specified date and time and also give a warning maybe with a configured 1 hour to 2 hours before that. For example if the alarm is going to go off in 2 hours, so that the user can remember or take action or let it ring depending on the critical task they are supposed to do during the time`