diff --git a/README.md b/README.md
index 1bf03ea..0cc9d30 100644
--- a/README.md
+++ b/README.md
@@ -1,128 +1,82 @@
-# 4NK Project Template — Qualité, Sécurité et Open Source
+# 4NK Project Template — Qualité, Sécurité, Open Source ✨
 
-Ce dépôt est le template de référence 4NK. Il formalise la démarche de qualité, de sécurité et d’open source applicable à tous les projets 4NK et fournit des supports initiaux (modèles CI/CD, règles Cursor, scripts, guides). Chaque projet doit l’adapter à ses spécificités, et proposer des améliorations en retour (feedback) vers ce template.
+Bienvenue dans le template 4NK. Objectifs: démarrer vite, rester propre, publier serein. Vous y trouverez des règles, des workflows CI, des scripts d’agents et une documentation prête à adapter.
 
-## 📋 Table des Matières
+## 📦 Ce que vous obtenez
 
+- Standards de qualité et sécurité (lint, audit, release‑guard)
+- Agents automatisés (qualité, docs, tests, sécurité, déploiement)
+- CI Gitea prête à l’emploi (self‑hosted, linux)
+- Documentation structurée: `docs/project/**` (ce dépôt) et `docs/templates/**` (modèles pour vos projets)
 
-## 🏗️ Architecture
+## 🐧 Linux (Debian) — Prérequis rapides
 
-### 🔄 Flux de Données
+```bash
+sudo apt update
+sudo apt install -y bash git curl jq ca-certificates
+# Lint Markdown
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+```
 
+## ⚙️ Configuration locale (secrets)
 
-## 🚀 Démarrage Rapide
+```bash
+bash scripts/deploy/setup.sh   # crée ~/.4nk_template/.env (chmod 600)
+```
+À renseigner ensuite dans `~/.4nk_template/.env` (extraits):
 
-### Prérequis
+- OPENAI_API_KEY, OPENAI_MODEL (si agents IA)
+- RELEASE_TOKEN (release via API Gitea)
+- BASE_URL (optionnel, par défaut `https://git.4nkweb.com`)
 
+Plus d’infos: `docs/project/CONFIGURATION.md` et `docs/project/GITEA_SETUP.md`.
 
-### Installation
+## 🤖 Exécuter les agents
 
+```bash
+scripts/agents/run.sh              # exécution complète, rapports dans tests/reports/agents
+scripts/agents/run.sh . . documentation  # exécution ciblée (facultatif)
+```
+Fallback Windows: `scripts/agents/run.ps1`.
 
-### Configuration SSH (Recommandé)
+Guide complet: `docs/project/AGENTS_RUNTIME.md`.
 
+## 🔁 CI/CD (Gitea Actions)
+
+- Runners: labels requis `self-hosted,linux` (voir `docs/project/GITEA_SETUP.md`)
+- Jobs clés: `markdownlint`, `agents-smoke`, `release-guard`, `release-create`
+- Secrets/Variables: `RELEASE_TOKEN`, `OPENAI_API_KEY`, `BASE_URL`, `OPENAI_*`
+
+## 🚀 Release
+
+```bash
+# Vérifier/mettre à jour la version
+cat TEMPLATE_VERSION
+
+# Tagger (déclenche la release via API si RELEASE_TOKEN existe côté dépôt)
+git tag -a vYYYY.MM.P -m 'release: vYYYY.MM.P (latest)'
+git push origin vYYYY.MM.P
+```
+
+Changelog: `CHANGELOG.md`. Gardien de release: `release-guard` en CI.
 
 ## 📚 Documentation
 
-### 📖 Guides Principaux
-
-- docs/TEMPLATE_ADAPTATION.md — Comment adapter ce template à votre projet
-- docs/TEMPLATE_FEEDBACK.md — Comment proposer des améliorations au template
-
-
-### 🔧 Guides Techniques
-
-
-### 🧪 Guides de Test
-
-### 🌐 Guides Réseau
-
-
-## 🔧 Configuration
-
-### Services Disponibles
-
-
-### Variables d'Environnement
-
-
-## 🧪 Tests et Monitoring
-
-### Tests de Base
-
-### Monitoring
-
-
-### Tests de Performance
-
-
-## 🌐 Réseau de Relais
-
-### Architecture Mesh
-
-
-### Ajout de Nœuds Externes
-
-
-### Configuration Externe
-
-
-## 🛠️ Développement
-
-### Structure du Projet
-
-
-### Ajout d'un Nouveau Service
-
-
-### Modification de la Configuration
-
-
-## 🚨 Dépannage
-
-### Problèmes Courants
-
-#### 1. Ports Déjà Utilisés
-
-
-#### 2. Problèmes de Synchronisation
-
-
-#### 3. Problèmes de Connectivité
-
-### Logs Détaillés
-
-
-### Healthchecks
-
-
-## 📈 Performance
-
-### Ressources Recommandées
-
-### Optimisations
-
+- Projet (ce dépôt): `docs/project/`
+- Modèles à réutiliser: `docs/templates/`
+- Standards de qualité: `docs/project/QUALITY_STANDARDS.md`
 
 ## 🤝 Contribution
 
-1. Fork le repository
-2. Créer une branche feature (`git checkout -b feature/nouvelle-fonctionnalite`)
-3. Commit les changements (`git commit -am 'Ajout de nouvelle fonctionnalité'`)
-4. Push la branche (`git push origin feature/nouvelle-fonctionnalite`)
-5. Créer une Pull Request
-
-Pour les améliorations du template lui‑même (règles, CI, scripts), se référer à `docs/TEMPLATE_FEEDBACK.md` et utiliser le type d’issue « Template Feedback ».
+- Fork → branche → PR (CI verte, docs/changelog à jour)
+- Respect des règles éditoriales (français, pas de secrets, pas d’exemples applicatifs)
 
 ## 📄 Licence
 
-Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
+MIT — voir `LICENSE`.
 
 ## 🆘 Support
 
-Pour obtenir de l'aide :
-
-1. Consulter la [documentation](docs/)
-2. Vérifier les [issues existantes](https://git.4nkweb.com/4nk/4NK_node/issues)
-3. Créer une nouvelle issue avec les détails du problème
-4. Inclure les logs et la configuration utilisée
-
----
+- Lire `docs/project/INDEX.md`
+- Ouvrir une issue si besoin