Docs: proper README, AGENTS.md, MIT LICENSE
This commit is contained in:
Lukas Holzner committed
1 parent
4fc6be04da
commit
fe9e75a4e7
4 files changed
+135
-54
No files matched your search
@@ -0,0 +1,37 @@
|
|||||||
|
# AGENTS.md — Instructions for AI agents working in this repo
|
||||||
|
|
||||||
|
Mindlist: Vite + React 19 + TS + Tailwind v4 + Dexie PWA, Capacitor 8 Android wrapper.
|
||||||
|
Default AI model (app + agents): `deepseek/deepseek-v4.1-flash` via OpenRouter.
|
||||||
|
|
||||||
|
## Golden commands (run from repo root)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
npm run dev # http://localhost:5173
|
||||||
|
npm test # vitest, must be green
|
||||||
|
npm run build # tsc -b + vite build; PWA in dist/
|
||||||
|
npx cap sync android
|
||||||
|
cd android && export JAVA_HOME=/opt/homebrew/opt/openjdk@21 ANDROID_HOME=$HOME/Library/Android/sdk
|
||||||
|
./gradlew assembleDebug # or assembleRelease (needs keystore, see README)
|
||||||
|
```
|
||||||
|
|
||||||
|
Toolchain notes: JDK **21** for Gradle (17 also installed, 26 breaks Gradle).
|
||||||
|
SDK root on this machine is a symlink: `~/Library/Android/sdk -> /opt/homebrew/share/android-commandlinetools`.
|
||||||
|
Device install: `adb install -r <apk>`; Pixel 9 Pro attached. Screenshots: `adb exec-out screencap -p > /tmp/x.png`.
|
||||||
|
SVG→PNG rendering without extra deps: headless Chrome `--screenshot` at 512px,
|
||||||
|
downscale with `sips -z <n> <n>` (Chrome enforces min window width — never screenshot small sizes directly).
|
||||||
|
|
||||||
|
## Hard rules
|
||||||
|
|
||||||
|
1. **Never commit secrets.** Blocked by `.gitignore`: `Openrouter.md`, `**/*.keystore`, `**/keystore.properties`, `node_modules/`, `dist/`, `*.apk`, `android/local.properties`. Before every commit, run `git status --short` and grep the staged diff for `sk-or-v1-[A-Za-z0-9]{8,}`.
|
||||||
|
2. **Never hardcode API keys.** BYOK only — key comes from `localStorage` (`mindlist.or.key`), model from `mindlist.or.model` w/ `DEFAULT_MODEL` fallback in `src/lib/openrouter.ts`.
|
||||||
|
3. **Release keystore is irreplaceable** (`android/mindlist-release.keystore` + `keystore.properties`, untracked). Never delete, move, or regenerate. Remind the human to keep backups.
|
||||||
|
4. **No new dependencies without need.** Prefer existing: Dexie, Tailwind, lucide-react, zod.
|
||||||
|
5. **Accessibility bar:** 44px touch targets, `bg-teal-700`+ for white text (never `bg-teal-500` + white), labels for all inputs, `role="dialog"` + Esc on sheets, `:focus-visible` styles. See `src/index.css`.
|
||||||
|
|
||||||
|
## Working agreements (how this repo was built)
|
||||||
|
|
||||||
|
- **Builder/critic loop:** implement → run `npm test` + `npm run build` → spawn one design critic + one functionality critic (subagents, read-only) scoring 0–10 → fix top items → repeat until avg **≥ 8/10 or 5 iterations**, then stop and report. Same protocol for logo work (`logo/` sources, critic reads rendered PNGs at 512 + 48 + 16px).
|
||||||
|
- **Final assets:** `logo/mindlist-logo-v3.svg` = app logo; `logo/mindlist-logo-foreground.svg` = Android adaptive foreground. Don't add new logo versions without retiring the loop first.
|
||||||
|
- **OpenRouter calls:** always `response_format: { type: "json_object" }`, `HTTP-Referer` + `X-Title` headers, `max_tokens: 2000`; validate with `parsePlanExported` (reconciles `totalMin = Σ steps`); **always** fall back to `heuristicPlan`/`offlineSplit`/`offlineExpand` on any failure — the timer must never strand the user.
|
||||||
|
- **Keep it local-first:** no backend, no analytics, no network calls except `api.openrouter.ai`.
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Mindlist contributors
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
# Mindlist — Free Open-Source Neurolist Alternative (BYOK)
|
|
||||||
|
|
||||||
PWA built with Vite + React + TS + Tailwind + Dexie. Local-first, no backend, no tracking.
|
|
||||||
|
|
||||||
## Features
|
|
||||||
- Magic Subtasks Easy/Medium/Hard with Life Context shaping
|
|
||||||
- Brain Dump AI Import, AI Edit chat patching
|
|
||||||
- Single-task Focus playlist timer + voice announcements + dynamic end-time + Wake Lock
|
|
||||||
- Task Library reuse, calendar export (.ics with VALARM), dark mode, offline heuristic fallback
|
|
||||||
- BYOK OpenRouter, default `deepseek/deepseek-v4.1-flash` (`response_format: json_object`)
|
|
||||||
|
|
||||||
## BYOK setup
|
|
||||||
1. Get a key at https://openrouter.ai/keys
|
|
||||||
2. Open ⚙️ Settings in the app, paste key, confirm model `deepseek/deepseek-v4.1-flash`
|
|
||||||
3. Key is stored in `localStorage` only (`mindlist.or.key`), sent directly to `https://openrouter.ai/api/v1/chat/completions`. Never committed.
|
|
||||||
|
|
||||||
> The example key in `../Openrouter.md` is revoked/placeholder — do not reuse.
|
|
||||||
|
|
||||||
## Dev
|
|
||||||
```bash
|
|
||||||
cd app
|
|
||||||
npm install
|
|
||||||
npm run dev # http://localhost:5173
|
|
||||||
npx vitest run
|
|
||||||
npm run build # PWA in dist/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Deploy
|
|
||||||
Static hosting: `npm run build` → deploy `dist/` to GitHub Pages / Netlify / Vercel. PWA installable on Android via browser → Add to Home screen. Optional Capacitor/TWA wrapper for Play Store later.
|
|
||||||
|
|
||||||
## License
|
|
||||||
MIT — free for personal + commercial use.
|
|
||||||
@@ -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/)
|
|
||||||
|
|
||||||
## 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
|
## 🛠️ Development
|
||||||
{
|
|
||||||
"$schema": "./node_modules/oxlint/configuration_schema.json",
|
```bash
|
||||||
"plugins": ["react", "typescript", "oxc"],
|
npm install
|
||||||
"options": {
|
npm run dev # http://localhost:5173
|
||||||
"typeAware": true
|
npm test # vitest
|
||||||
},
|
npm run build # PWA output in dist/
|
||||||
"rules": {
|
|
||||||
"react/rules-of-hooks": "error",
|
|
||||||
"react/only-export-components": ["warn", { "allowConstantExport": true }]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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).
|
||||||
Reference in new issue
Block a user