# ChronoMind

> AI-powered contextual clock & timer — never be caught off-guard again.

**ChronoMind** is a cross-platform time awareness layer that understands *why* you set a timer, not just *when*. It provides intelligent pre-warning cascades, urgency-based escalation, routine orchestration, and natural language interaction.

## Platforms

| Platform | Stack | Status |
|----------|-------|--------|
| **Web PWA** | Next.js 16, React 19, TailwindCSS v4, Zustand | ✅ 373 tests passing |
| **iOS** | SwiftUI (iOS 17+), WidgetKit, ActivityKit | ✅ 129 XCTests |
| **Apple Watch** | SwiftUI (watchOS 10+), Complications | ✅ Built |
| **macOS** | SwiftUI menu bar app (macOS 14+) | ✅ Built |
| **Android** | Jetpack Compose, Material 3, Room, Hilt | ✅ 30 JUnit5 tests |
| **Wear OS** | Compose for Wear OS | 🚧 Minimal |
| **Backend** | Platform-service (Fastify 5, port 4003) | ✅ 130 tests (4 modules) |

## Core Features

- **Pre-warning cascades** — configurable warnings before every timer (2h → 1h → 30m → 15m → 5m → NOW)
- **5 urgency levels** — Critical, Important, Standard, Gentle, Passive — each with distinct notification style
- **Routines** — multi-step sequences (Morning, Workout, Cooking, Wind-Down) with transitions
- **Natural language** — "meeting in 30 min", "alarm at 3pm", "pomodoro 4 rounds"
- **Focus mode** — Pomodoro sessions with notification blocking
- **Linked timers** — "When timer A ends, start timer B"
- **Visual timeline** — color-coded, urgency-aware dashboard
- **Stats & streaks** — daily activity, on-time rate, focus hours, streak tracking
- **Calendar import** — .ics file import with conflict detection
- **AI reschedule** — "I slept in 30 minutes" → shift all morning timers
- **Shareable timers** — share timer links across platforms
- **Household shared timers** — family/team coordination (up to 6 members)

## Quick Start

```bash
# Web (development)
cd web && npm install && npm run dev

# Run tests
cd web && npm test            # 373 Vitest tests
cd web && npm run typecheck   # TypeScript check
cd web && npm run build       # Production build

# iOS — open ios/ChronoMind.xcodeproj in Xcode
# Android — open android/ in Android Studio
```

## Project Structure

```
learning_ai_clock/
├── web/          # Next.js 16 PWA (12,960 lines, 58 files)
├── ios/          # SwiftUI iOS + Watch + Mac + Widgets (12,946 lines, 72 files)
├── android/      # Jetpack Compose + Wear OS (3,427 lines, 25 files)
├── docs/         # PRD, roadmap, research
└── .github/      # CI workflows
```

## Backend

Uses the shared **platform-service** from [`learning_ai_common_plat`](../learning_ai_common_plat) with 4 ChronoMind-specific modules:

- `timers` — CRUD + delta sync + batch upsert (42 tests)
- `routines` — CRUD + delta sync + batch upsert (32 tests)
- `households` — group management + invitations (26 tests)
- `shared-timers` — household-scoped timers (30 tests)

All documents use `productId: "chronomind"`.

## Ecosystem

Part of the **ByteLyst** ecosystem alongside [LysnrAI](../learning_voice_ai_agent), [MindLyst](../learning_multimodal_memory_agents), and [NomGap](../learning_ai_fastgap).

## Docs

- [PRD](docs/PRD.md) — Full product requirements
- [Roadmap](docs/roadmap.md) — 5-phase implementation plan
- [Industry Research](docs/INDUSTRY_RESEARCH.md) — Competitive analysis
- [AGENTS.md](AGENTS.md) — AI coding agent instructions

## License

Closed-source application. Timer engine library open-source (license TBD).