From 8863122afc473f2b6630fcea027ea70c6dd7a95b Mon Sep 17 00:00:00 2001
From: Pierre <pierre@pgironde.fr>
Date: Fri, 13 Nov 2026 13:35:47 +0100
Subject: [PATCH] created a new agents.md

---
 AGENTS.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..438c9f3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,94 @@
+# Repository instructions
+
+## Language
+
+Use French when communicating with the user unless they ask otherwise. All new
+technical artifacts must be in English: code, identifiers, variable and
+function names, Home Assistant entity and sensor names, log messages, comments,
+test names, configuration keys, and technical documentation. Do not rename
+existing French identifiers or entities unless explicitly requested.
+
+## Context
+
+This repository is an AppDaemon configuration for Home Assistant. Python apps
+in `apps/` control real equipment, including heating, shutters, lighting, a
+projector, and a television. Application configuration is in `apps/apps.yaml`,
+supplemented by YAML files in `apps/global/` and `apps/rooms/`. Runtime
+configuration is in `appdaemon.yaml`.
+
+`apps/ad_toolbox` is a shared Git submodule. It provides the base classes,
+conditions, virtual sensors, and logging used by the apps. Only change it when
+the request explicitly concerns that component. Do not update its revision or
+discard its local changes without approval.
+
+## Security and operations
+
+- Never display, copy into responses, or commit tokens, passwords,
+  `secrets.yaml`, `apps/theframe_token.txt`, or persisted data in `apps/data/`.
+  Refer to their paths and redact sensitive values in diagnostics.
+- Do not start a second AppDaemon instance, rerun `dockerStart.sh`, or execute
+  `archiveLogs.sh` manually while the service is running. The archive script
+  moves active log files.
+- Do not restart the container, send device commands, or change heating
+  setpoints unless the user explicitly requests it. To test heating logic, use
+  mocks first or `send_commands: false` where available.
+- Local AppDaemon-core and startup-script patches may exist outside this
+  persistent repository. Read `docs/appdaemon-local-changes.md` and
+  `docs/appdaemon-upgrade-rollback-instructions.md` before upgrading or
+  changing the runtime. Do not overwrite or "clean up" these patches.
+
+## Logs and diagnosis
+
+When asked to investigate a warning, error, or runtime behavior, inspect
+`/conf/logs` first:
+
+1. `appdaemon.log`, `error.log`, and `virtualsensors.log` for the current run;
+2. `archive/<timestamp>/` for previous runs;
+3. `memory_usage.csv` when memory use is suspected.
+
+Always inspect the lines following a warning: a successful reconnection or
+recovery can make an incident transient. Distinguish application problems from
+Home Assistant, MQTT, or hardware connectivity losses.
+
+## Changes
+
+- Follow the style and conventions of the app or module being changed. Apps
+  often inherit from `SmartObject` and use `SmartCondition`; do not bypass
+  these abstractions without a clear reason.
+- Keep an app, its `apps/apps.yaml` entry, its Home Assistant entities, and any
+  related `apps/global/` or `apps/rooms/` configuration consistent.
+- Preserve AppDaemon lifecycle behavior: cancel timers, tasks, listeners, and
+  sockets on reload or termination when a change introduces them.
+- Do not overwrite or reorganize the user's existing work. Keep diffs limited
+  to the requested change.
+- Update documentation in `docs/` when operational behavior, a hardware
+  protocol, or a deployment procedure changes.
+
+## Validation
+
+The project uses `unittest`; no formatter or linter is configured. After a
+Python change, run the focused test when one exists, for example:
+
+```sh
+python3 -m unittest discover -s tests -p 'test_vertex2.py' -v
+python3 -m unittest discover -s tests -p 'test_boilerclimate.py' -v
+python3 -m unittest discover -s tests -p 'test_samsungtheframe_async.py' -v
+```
+
+For shared changes or before a broader delivery:
+
+```sh
+python3 -m unittest discover -s tests -v
+python3 -m unittest discover -s apps/ad_toolbox/unit_tests -p 'test_*.py' -v
+```
+
+The legacy YAML test runner for `ad_toolbox` is:
+
+```sh
+python3 apps/ad_toolbox/unittests.py
+```
+
+After a shell-script change, validate syntax at minimum with
+`sh -n <script>`. Changes to the VS Code extension in
+`apps/ad_toolbox/vscode-appdaemon/` must also follow its own `AGENTS.md`,
+including compilation, packaging, and installation.