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
|
||||
{
|
||||
"$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).
|
||||
Reference in new issue
Block a user