docs: Add test agents fix documentation

docs/TEST_AGENTS_FIX.md

@@ -0,0 +1,110 @@
+# Виправлення проблеми з тестовими агентами
+
+## Проблема
+
+Тестові агенти (`ag_atlas`, `ag_oracle`, `ag_builder`, `ag_greeter`) з'являлися в базі даних після застосування міграцій або відновлення з бекапу, замінюючи реальні агенти з НОДА2.
+
+## Причини
+
+1. **Міграції**: Раніше міграція `013_city_map_coordinates.sql` містила INSERT для тестових агентів
+2. **Бекапи**: Старі бекапи містили тестові агенти
+3. **Відсутність захисту**: Не було автоматичного видалення тестових агентів
+
+## Виправлення
+
+### 1. Міграції оновлено
+
+Файл `migrations/013_city_map_coordinates.sql`:
+- INSERT для тестових агентів закоментовано
+- Додано коментар про те, що тестові агенти не повинні створюватися
+
+### 2. Створено скрипт видалення
+
+**`scripts/remove-test-agents.sh`**:
+- Автоматично видаляє тестові агенти
+- Може викликатися після міграцій або вручну
+
+### 3. Інтегровано в health check
+
+**`scripts/db-health-check.sh`**:
+- Автоматично перевіряє наявність тестових агентів
+- Видаляє їх при виявленні
+- Запускається кожні 30 хвилин через cron
+
+### 4. Sync скрипт для НОДА2
+
+**`scripts/sync-node2-dagi-agents.py`**:
+- Завантажує 50 реальних DAGI агентів з `config/agents_city_mapping.yaml`
+- Призначає їх до `node-2-macbook-m4max`
+
+## Використання
+
+### Видалити тестові агенти вручну
+
+```bash
+cd /opt/microdao-daarion
+bash scripts/remove-test-agents.sh
+```
+
+### Завантажити агентів НОДА2
+
+```bash
+cd /opt/microdao-daarion
+python3 scripts/sync-node2-dagi-agents.py
+```
+
+### Перевірити стан
+
+```bash
+docker exec daarion-postgres psql -U postgres -d daarion -c "
+SELECT 
+  COUNT(*) as total,
+  COUNT(CASE WHEN node_id = 'node-2-macbook-m4max' THEN 1 END) as node2,
+  COUNT(CASE WHEN id IN ('ag_atlas', 'ag_oracle', 'ag_builder', 'ag_greeter') THEN 1 END) as test
+FROM agents;
+"
+```
+
+## Тестові агенти (не повинні існувати)
+
+- `ag_atlas` - Atlas
+- `ag_oracle` - Oracle
+- `ag_builder` - Builder Bot
+- `ag_greeter` - Greeter
+
+## Реальні агенти НОДА2
+
+50 агентів з `config/agents_city_mapping.yaml`, організовані по районах:
+
+- **Leadership Hall (4)**: Solarius, Sofia, PrimeSynth, Nexor
+- **System Control (6)**: monitor-node2, vindex, helix, aurora...
+- **Engineering Lab (5)**: byteforge, vector, chainweaver, cypher, canvas
+- **Marketing Hub (6)**: roxy, mira, tempo, harmony, faye...
+- **Finance Office (4)**: financial-analyst, accountant, budget-planner...
+- **Web3 District (5)**: smart-contract-dev, defi-analyst, tokenomics-expert...
+- **Security Bunker (7)**: shadelock, exor, penetration-tester...
+- **Vision Studio (4)**: iris, lumen, spectra, video-analyzer
+- **R&D Lab (6)**: protomind, labforge, testpilot, modelscout...
+- **Memory Vault (3)**: somnia, memory-manager, knowledge-indexer
+
+## Запобігання повторенню
+
+1. **Health check**: Автоматично видаляє тестові агенти кожні 30 хвилин
+2. **Міграції**: Тестові агенти закоментовані в міграціях
+3. **Sync скрипт**: Завжди використовувати для завантаження реальних агентів
+
+## Перевірка після відновлення з бекапу
+
+```bash
+# 1. Видалити тестові агенти
+bash scripts/remove-test-agents.sh
+
+# 2. Завантажити агентів НОДА2
+python3 scripts/sync-node2-dagi-agents.py
+
+# 3. Перевірити
+docker exec daarion-postgres psql -U postgres -d daarion -c "
+SELECT COUNT(*) FROM agents WHERE node_id = 'node-2-macbook-m4max';
+"
+```
+