# 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.