From d72aae696f9a3c8a87153b860cc593b82e1c7537 Mon Sep 17 00:00:00 2001
From: raph666 <raph999@free.fr>
Date: Sat, 18 Jul 2026 15:32:20 +0200
Subject: [PATCH] Document project rules and development setup

---
 AGENTS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0a51994
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# Arkteos — règles de contribution
+
+## Périmètre
+
+Ce dépôt prépare l'intégration custom Home Assistant `arkteos` pour une PAC
+Arkteos Zuran 4. L'intégration est strictement en lecture seule.
+
+## Connexion réseau
+
+- Se connecter exclusivement au proxy TCP de l'addon Home Assistant séparé.
+- Ne jamais établir de connexion directe avec la PAC.
+- Le port de référence du proxy est `9641`; il doit rester configurable.
+- Ne jamais émettre d'octet, de commande ou d'acquittement vers le proxy sans
+  preuve explicite que ce comportement est requis et sans décision explicite.
+
+## Référence protocolaire
+
+- La source de vérité actuelle est `references/arkteos_nodered_flow.json`.
+- `references/proxy_protocol_notes.md` documente le contexte connu.
+- Préserver chaque champ décodé par le flow Node-RED de référence.
+- Ne pas déduire de champ, d'offset, d'unité, d'encodage ou de règle de
+  découpage TCP qui ne soit pas démontré par ces références ou par des captures
+  de trames versionnées.
+- Toute nouvelle connaissance du protocole doit citer sa source et être testée
+  avec une capture anonymisée ou un cas de test reproduisible.
+
+## Changements
+
+- Ne supprimer aucune ligne, commentaire, test ou fichier existant sans
+  justification explicite de l'utilisateur.
+- Avant chaque modification, indiquer les fichiers ou zones concernés et la
+  raison du changement; après modification, récapituler ce qui a été fait.
+- Expliquer la zone concernée et présenter le diff avant toute modification
+  importante.
+- Préserver les fichiers de référence et ne jamais les réécrire pour adapter
+  l'intégration.
+
+## Validation
+
+- Ajouter des tests unitaires pour chaque règle de parsing introduite.
+- Exécuter les tests après chaque modification fonctionnelle.
+- Tester les données tronquées, concaténées et inconnues avant de considérer
+  la gestion du flux TCP comme fiable.
+- Vérifier que les plateformes Home Assistant exposées ne permettent aucune
+  action d'écriture.
+
+## Architecture et dépôt
+
+- Séparer le parsing, le transport TCP et le code des entités Home Assistant.
+- Ne jamais versionner d'identifiant, d'adresse IP, de jeton, de mot de passe
+  ni de capture privée.
+- Préférer des commits petits et facilement relisibles.
+- Créer les commits nécessaires et indiquer explicitement quand la branche est
+  prête à être poussée.
diff --git a/README.md b/README.md
index e69de29..9743c25 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,45 @@
+# Arkteos — développement
+
+Ce dépôt prépare une intégration custom Home Assistant en lecture seule pour
+une PAC Arkteos Zuran 4.
+
+L'intégration devra lire exclusivement le flux du proxy TCP fourni par l'addon
+Home Assistant séparé, sur le port de référence `9641`. Elle ne doit jamais se
+connecter directement à la PAC ni écrire sur le proxy.
+
+## Références disponibles
+
+- `references/arkteos_nodered_flow.json` : flow Node-RED fonctionnel en
+  production et seule référence actuelle pour le parsing.
+- `references/proxy_protocol_notes.md` : notes de contexte sur le proxy et les
+  tailles de trames rapportées.
+
+## État du dépôt
+
+L'intégration Home Assistant n'est pas encore écrite. Aucun comportement de
+framing TCP ne doit être supposé sans captures ou tests démonstratifs.
+
+## Arborescence cible proposée
+
+```text
+custom_components/
+  arkteos/
+    __init__.py
+    manifest.json
+    config_flow.py
+    const.py
+    coordinator.py
+    parser.py
+    sensor.py
+    binary_sensor.py
+    strings.json
+    translations/
+      fr.json
+tests/
+  components/
+    arkteos/
+references/
+```
+
+Cette arborescence est une proposition : elle ne crée encore aucun de ces
+fichiers.