# 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`.