diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..94fce6b
--- /dev/null
+++ b/AGENTS.md
@@ -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`.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..15a32c1
--- /dev/null
+++ b/LICENSE
@@ -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.
diff --git a/README-MINDLIST.md b/README-MINDLIST.md
deleted file mode 100644
index 9768d6d..0000000
--- a/README-MINDLIST.md
+++ /dev/null
@@ -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.
diff --git a/README.md b/README.md
index d6af7e3..e8a7d04 100644
--- a/README.md
+++ b/README.md
@@ -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).