diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e75560
--- /dev/null
+++ b/README.md
@@ -0,0 +1,190 @@
+# Nanometrics
+
+Système client-serveur de surveillance matérielle (CPU, RAM, disque) conçu pour une empreinte quasi nulle sur les machines Debian.
+
+## Architecture
+
+```
+┌─────────────────┐       UDP / MQTT       ┌──────────────────────────┐
+│  Agent Rust     │ ─────────────────────▶ │  Serveur Go              │
+│  ~1 Mo binaire  │                        │  SQLite · Prometheus      │
+│  systemd        │                        │  REST API · WebSocket     │
+└─────────────────┘                        └──────────┬───────────────┘
+                                                      │ HTTP
+                                           ┌──────────▼───────────────┐
+                                           │  Dashboard Nginx          │
+                                           │  HTML/CSS/JS · temps réel │
+                                           └──────────────────────────┘
+```
+
+## Fonctionnalités
+
+- **Métriques collectées** : CPU, RAM (libre/utilisée), disque (total/libre/utilisé), uptime, réseau, température, SMART (si `smartctl` disponible)
+- **Double protocole** : UDP (fire-and-forget) et/ou MQTT (bidirectionnel, compatible Home Assistant auto-discovery)
+- **Temps réel** : WebSocket — mise à jour des tuiles sans rechargement
+- **Historique** : SQLite avec rétention configurable (7 à 365 jours)
+- **Dashboard interactif** : grille responsive, popup détail avec courbes, configuration par agent depuis l'UI
+- **Empreinte agent minimale** : pas de runtime async (pas de Tokio), boucle mono-thread, `sysinfo` sans threads de fond
+- **Sécurité systemd** : `DynamicUser=yes`, `ProtectSystem=strict`, `ProtectHome=read-only`
+
+---
+
+## Installation de l'agent Rust
+
+### Prérequis
+
+```bash
+# Rust (si non installé)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+### Compilation
+
+```bash
+cargo build --release --manifest-path agent/Cargo.toml
+# Binaire produit : agent/target/release/nanometrics-agent (~1 Mo)
+```
+
+### Configuration
+
+Créer `/etc/nanometrics/config.toml` :
+
+```toml
+[server]
+ip = "10.0.0.50"    # IP du serveur Go
+port = 9999          # Port UDP du serveur
+
+[mqtt]
+enabled = false
+host = "10.0.0.3"
+port = 1883
+topic_base = "nanometrics/agents"
+auto_discovery = true
+birth_message = true
+last_will = true
+
+[metrics.cpu]
+enabled = true
+udp = true
+mqtt = false
+
+[metrics.memory]
+enabled = true
+udp = true
+mqtt = false
+
+[metrics.disk]
+enabled = true
+udp = true
+mqtt = false
+
+[metrics.smart]
+enabled = true    # nécessite smartctl installé
+udp = true
+mqtt = false
+
+[metrics.uptime]
+enabled = true
+udp = true
+mqtt = false
+
+[metrics.network]
+enabled = true
+udp = true
+mqtt = false
+
+[metrics.temperature]
+enabled = true
+udp = true
+mqtt = false
+```
+
+### Déploiement systemd
+
+```bash
+# Copier le binaire
+sudo cp agent/target/release/nanometrics-agent /usr/local/bin/
+
+# Créer le répertoire de config
+sudo mkdir -p /etc/nanometrics
+sudo cp agent/config.toml /etc/nanometrics/config.toml
+
+# Installer le service
+sudo cp deploy/nanometrics-agent.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now nanometrics-agent
+
+# Vérifier
+sudo systemctl status nanometrics-agent
+journalctl -u nanometrics-agent -f
+```
+
+Pour SMART, installer `smartmontools` sur la machine cible :
+
+```bash
+sudo apt install smartmontools
+```
+
+---
+
+## Installation du serveur Go + dashboard
+
+### Prérequis
+
+- Docker et Docker Compose
+
+### Lancement
+
+```bash
+cd server
+docker compose up -d
+```
+
+Le dashboard est disponible sur **http://<ip-serveur>** (port 80).
+
+### Variables d'environnement
+
+| Variable | Défaut | Description |
+|----------|--------|-------------|
+| `UDP_ADDR` | `0.0.0.0:9999` | Adresse d'écoute UDP |
+| `HTTP_ADDR` | `0.0.0.0:8080` | Adresse du serveur HTTP |
+| `DB_PATH` | `/data/nanometrics.db` | Chemin de la base SQLite |
+| `MQTT_BROKER` | `tcp://10.0.0.3:1883` | Adresse du broker MQTT |
+| `MQTT_TOPIC_BASE` | `nanometrics/agents` | Topic MQTT de base |
+
+### Endpoints exposés
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/agents` | Liste de tous les agents |
+| `GET /api/agents/{id}/history` | Historique des métriques |
+| `GET /api/agents/{id}/config` | Configuration d'un agent |
+| `PUT /api/agents/{id}/config` | Modifier la config d'un agent |
+| `POST /api/agents/{id}/icon` | Upload d'icône (JPG/PNG/WEBP) |
+| `GET /api/config` | Configuration serveur |
+| `PUT /api/config` | Modifier la configuration serveur |
+| `GET /metrics` | Métriques Prometheus |
+| `WS /ws` | WebSocket temps réel |
+
+---
+
+## Commandes de développement
+
+```bash
+# Agent Rust — build, tests, lint
+cargo build --release --manifest-path agent/Cargo.toml
+cargo test --manifest-path agent/Cargo.toml
+cargo clippy --manifest-path agent/Cargo.toml
+
+# Serveur Go — tests, vet
+go test ./server/...
+go vet ./server/...
+
+# Serveur Go — lancement local (sans Docker)
+cd server
+DB_PATH=/tmp/nm.db HTTP_ADDR=0.0.0.0:8080 UDP_ADDR=0.0.0.0:9999 go run .
+
+# Simuler un agent avec netcat
+echo '{"hostname":"test-01","ip":"127.0.0.1","status":"online","cpu_percent":42.5,"memory_used":3000000000,"memory_total":8000000000,"hdd_used":60000000000,"hdd_total":200000000000,"uptime":86400}' \
+  | nc -u 127.0.0.1 9999
+```