# 🧠 Mindlist — Free & Open-Source ADHD Task Breaker

A free and open-source alternative to [Neurolist](https://neurolist.app): an AI-assisted planner built as a **cognitive prosthetic** for ADHD executive dysfunction — task-initiation paralysis, overwhelming to-dos, and time blindness.

You bring the task. Mindlist breaks it into calm, timed micro-steps and walks you through them **one at a time** with a focus playlist timer. **BYOK**: your own OpenRouter key, your data stays on your device.

![Mindlist logo](public/logo.svg)

## ✨ Features

| Area | What it does |
|---|---|
| **Magic Subtasks** | Any daunting task → sequenced micro-step checklist with per-step minutes, in **Easy / Medium / Hard** granularity (Hard = hyper-granular, zero-implicit-knowledge physical moves) |
| **Life Context** | Persistent constraints (small apartment, low energy, distractions…) shape every AI breakdown |
| **AI Edit** | Conversational patching — *"no vacuum, shorter phases", "expand step 4"* — full plan recalculated |
| **Brain Dump import** | Paste chaos → AI extracts distinct tasks and breaks each down |
| **Focus playlist** | Single-task card (future steps hidden), countdown ring, pause / +1 min / skip / complete, Wake Lock |
| **Voice + recalibration** | Spoken step transitions (Web Speech), dynamic projected end-time |
| **Library** | One-tap reuse of tuned breakdowns (morning routine, cleaning, …) |
| **Calendar export** | `.ics` with alarms, based on live remaining time |
| **Offline fallback** | No key / offline / API error → built-in heuristic breakdowns, timer keeps working |
| **Local-first** | Dexie (IndexedDB) persistence, no backend, no tracking, dark mode, PWA installable |

## 🔑 BYOK setup (2 minutes)

1. Get an OpenRouter key: <https://openrouter.ai/keys> (default model `deepseek/deepseek-v4.1-flash` costs a fraction of a cent per breakdown)
2. Open the app → ⚙️ Settings → paste the key, confirm the model
3. The key lives in `localStorage` (`mindlist.or.key`) on your device only and is sent straight to `https://openrouter.ai/api/v1/chat/completions`. It is **never** committed — `.gitignore` blocks key files.

## 🛠️ Development

```bash
npm install
npm run dev      # http://localhost:5173
npm test         # vitest
npm run build    # PWA output in dist/
```

Deploy the PWA anywhere static: `dist/` → GitHub Pages / Netlify / Vercel. On Android: browser → *Add to Home screen*, or build the native wrapper below.

## 🤖 Android app (Capacitor)

Prerequisites (macOS): JDK 21 (`brew install openjdk@21`), Android SDK platform + build-tools 36 (`sdkmanager`), `ANDROID_HOME` set, `sdk.dir` in `android/local.properties` (untracked).

```bash
npm run build
npx cap sync android
cd android
export JAVA_HOME=/opt/homebrew/opt/openjdk@21
./gradlew assembleDebug        # quick on-device test
./gradlew assembleRelease      # signed, needs keystore (below)
adb install -r app/build/outputs/apk/release/app-release.apk
```

**Signing:** release builds need `android/mindlist-release.keystore` + `android/keystore.properties` (both git-ignored — **back them up**: password manager + offline copy. Lose them and no future update can ship under the same signature).

```bash
# one-time: create key
keytool -genkeypair -keystore android/mindlist-release.keystore \
  -alias mindlist -keyalg RSA -keysize 2048 -validity 10000
# then create android/keystore.properties:
#   storeFile=../mindlist-release.keystore
#   storePassword=…
#   keyAlias=mindlist
#   keyPassword=…
```

## 🗂️ Project structure

```
src/
  App.tsx            # all views: Today, Composer, Focus, Dump, Library, Settings
  lib/openrouter.ts  # BYOK client (default: deepseek/deepseek-v4.1-flash)
  lib/prompts.ts     # Easy/Med/Hard + BrainDump + AI-Edit system prompts
  lib/fallback.ts    # offline heuristic plans + speech/beep
  lib/store.ts       # Dexie schema, prefs, .ics export
  app.test.ts        # vitest suite
logo/                # logo sources (v3 = final) + Android foreground asset
public/              # favicon, PWA icons (192/512), apple-touch-icon
android/             # Capacitor native project (icons, signing config)
```

See [AGENTS.md](AGENTS.md) if you (or an AI agent) want to contribute.

## 📄 License

MIT — free for personal and commercial use. See [LICENSE](LICENSE).