Client Kobo (overlay trmnl-kobo) + README + sonde usage

README.md

@@ -0,0 +1,54 @@
+# Monitorink
+
+Transforme une **Kobo Libra 2** (e-reader e-ink) en écran de monitoring domestique affichant :
+**heure**, **météo**, **statuts Home Assistant**, et surtout le **reste de tokens de
+l'abonnement Claude**.
+
+## Architecture
+
+```
+[Homelab]  backend PNG (FastAPI + Playwright, Docker, derrière Caddy)
+              ├─ Claude  : GET /api/oauth/usage (token longue durée `claude setup-token`)
+              ├─ Météo   : Open-Meteo (sans clé)
+              └─ Home Assistant : API REST /states
+                    │
+                    └── GET /image.png  (1264×1680 niveaux de gris)
+                              │  WiFi à la demande
+                        [Kobo Libra 2]  boucle NickelMenu : fetch → fbink → suspend rtcwake
+```
+
+- **`backend/`** — serveur Python qui agrège les données et génère l'image du dashboard.
+- **`kobo/`** — scripts client pour la Kobo (overlay sur `usetrmnl/trmnl-kobo`).
+- **`dev/`** — utilitaires de dev (sonde de l'endpoint usage Claude).
+
+## Le « reste de tokens Claude »
+
+L'endpoint OAuth `/usage` (celui derrière la commande `/usage` de Claude Code) renvoie des
+**pourcentages d'utilisation** des fenêtres glissantes (session 5 h + hebdo), pas un nombre brut
+de tokens — Anthropic n'expose pas de compteur absolu côté abonnement. Monitorink affiche donc
+le **% restant** (`100 − utilisation`) et le temps avant reset. *(ChatGPT : hors scope, aucune
+API officielle de quota restant.)*
+
+Le backend s'authentifie avec un **token longue durée dédié** généré par `claude setup-token`
+(env `MONITORINK_CLAUDE_TOKEN`) — il ne touche jamais aux credentials de Claude Code et ne fait
+aucun refresh (le token est valide ~1 an).
+
+## Démarrage backend (dev, sur Mac)
+
+```sh
+cd backend
+python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+.venv/bin/python -m playwright install chromium
+cp ../.env.example ../.env   # puis compléter
+.venv/bin/uvicorn app:app --reload --port 8080
+# -> http://localhost:8080/image.png  et  /debug.html (itération design)
+```
+
+## Déploiement (homelab, Docker + Caddy)
+
+1. Générer le token sur le homelab : `ssh -t homelab claude setup-token`.
+2. Créer `.env` (depuis `.env.example`) avec le token, les coords météo, et la config HA.
+3. `docker compose up -d --build` (le service s'expose via caddy-docker-proxy sur
+   `monitorink.homelab.nestor-server.fr`).
+
+Voir `kobo/README.md` pour l'installation côté Kobo.