wiki search people tested pipeline

CLAUDE.md

@@ -125,3 +125,100 @@ git push http://alvis:$GITEA_TOKEN@localhost:3000/alvis/AgapHost.wiki.git main
 - Remove outdated or redundant content when updating
 - Create a new page if a topic doesn't exist yet
 - Wiki files are Markdown, named `<PageTitle>.md`
+
+## Home Assistant API
+
+**Instance**: `https://haos.alogins.net`
+**Token**: Read from `$HA_TOKEN` environment variable — never hardcode it
+**Base URL**: `https://haos.alogins.net/api/`
+**Auth header**: `Authorization: Bearer <token>`
+
+### Common Endpoints
+```bash
+# Health check
+curl -s -H "Authorization: Bearer $HA_TOKEN" \
+  https://haos.alogins.net/api/
+
+# Get all entity states
+curl -s -H "Authorization: Bearer $HA_TOKEN" \
+  https://haos.alogins.net/api/states
+
+# Get specific entity
+curl -s -H "Authorization: Bearer $HA_TOKEN" \
+  https://haos.alogins.net/api/states/<entity_id>
+
+# Call service (e.g., turn on light)
+curl -s -X POST \
+  -H "Authorization: Bearer $HA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"entity_id":"light.example"}' \
+  https://haos.alogins.net/api/services/<domain>/<service>
+```
+
+**Note**: Status 401 = token invalid/expired
+
+## HA → Zabbix Alerting
+
+Home Assistant automations push alerts to Zabbix via `history.push` API (Zabbix 7.4 trapper items). No middleware needed.
+
+### Architecture
+
+```
+[HA sensor ON] → [HA automation] → [rest_command: HTTP POST] → [Zabbix history.push] → [trapper item] → [trigger] → [Telegram]
+```
+
+### Water Leak Sensors
+
+3x HOBEIAN ZG-222Z moisture sensors → Disaster-level Zabbix alert with room name.
+
+| HA Entity | Room |
+|-----------|------|
+| `binary_sensor.hobeian_zg_222z` | Kitchen |
+| `binary_sensor.hobeian_zg_222z_2` | Bathroom |
+| `binary_sensor.hobeian_zg_222z_3` | Laundry |
+
+**Zabbix side** (host "HA Agap", hostid 10780):
+- Trapper item: `water.leak` (text type) — receives room name or "ok"
+- Trigger: `last(/HA Agap/water.leak)<>"ok"` — Disaster (severity 5), manual close
+- Trigger name uses `{ITEM.LASTVALUE}` to show room in notification
+
+**HA side** (`configuration.yaml`):
+- `rest_command.zabbix_water_leak` — POST to Zabbix `history.push`, accepts `{{ room }}` template variable
+- `rest_command.zabbix_water_leak_clear` — pushes "ok" to clear
+- Automation "Water Leak Alert" — any sensor ON → sends room name to Zabbix
+- Automation "Water Leak Clear" — all sensors OFF → sends "ok"
+
+### Adding a New HA → Zabbix Alert
+
+1. **Zabbix**: Create trapper item (type 2) on "HA Agap" via `item.create` API. Create trigger via `trigger.create`.
+2. **HA config**: Add `rest_command` entry in `configuration.yaml` with `history.push` payload. Restart HA.
+3. **HA automation**: Create via `POST /api/config/automation/config/<id>` with trigger on sensor state and action calling the rest_command.
+4. **Test**: Call `rest_command` via HA API, verify Zabbix problem appears.
+
+## Zabbix API
+
+**Instance**: `http://localhost:81` (local), `https://zb.alogins.net` (external)
+**Endpoint**: `http://localhost:81/api_jsonrpc.php`
+**Token**: Read from `$ZABBIX_TOKEN` environment variable — never hardcode it
+**Auth header**: `Authorization: Bearer <token>`
+
+### Common Requests
+```bash
+# Check API version
+curl -s -X POST http://localhost:81/api_jsonrpc.php \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $ZABBIX_TOKEN" \
+  -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'
+
+# Get all hosts
+curl -s -X POST http://localhost:81/api_jsonrpc.php \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $ZABBIX_TOKEN" \
+  -d '{"jsonrpc":"2.0","method":"host.get","params":{"output":"extend"},"id":1}'
+
+# Get problems/issues
+curl -s -X POST http://localhost:81/api_jsonrpc.php \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $ZABBIX_TOKEN" \
+  -d '{"jsonrpc":"2.0","method":"problem.get","params":{"output":"extend"},"id":1}'
+```