Docs: proper README, AGENTS.md, MIT LICENSE

2026-10-02 10:24:47 +02:00
1 parent 4fc6be04da
commit fe9e75a4e7
@@ -1,32 +1,87 @@
-# React + TypeScript + Vite
+# 🧠 Mindlist — Free & Open-Source ADHD Task Breaker

-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+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.

-Currently, two official plugins are available:
+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.

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+![Mindlist logo](public/logo.svg)

-## React Compiler
+## ✨ Features

-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+| 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 |

-## Expanding the Oxlint configuration
+## 🔑 BYOK setup (2 minutes)

-If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
+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.

-```json
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["react", "typescript", "oxc"],
-  "options": {
-    "typeAware": true
-  },
-  "rules": {
-    "react/rules-of-hooks": "error",
-    "react/only-export-components": ["warn", { "allowConstantExport": true }]
-  }
-}
+## 🛠️ Development
+
+```bash
+npm install
+npm run dev      # http://localhost:5173
+npm test         # vitest
+npm run build    # PWA output in dist/
 ```

-See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
+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).