[2026-05-13] openmediavault-rpi5: add agent constraints section

family/how-to/openmediavault-rpi5.md

@@ -242,6 +242,43 @@ rsync -avh --progress /path/to/movies/ kraken@kraken.local:/srv/.../media/movies
 
 ---
 
+## Hermes агент — ограничения и архитектура
+
+> Важно знать при отладке поведения агента.
+
+Агент работает **внутри** контейнера `hermes-kraken`. Это означает:
+
+| Возможность | Статус | Способ |
+|---|---|---|
+| Читать/писать vault | ✅ | `/vault/` через mcpvault MCP |
+| Писать файлы на хост | ✅ только через alpine+bind `/:/host` | Portainer API |
+| docker / docker cp | ❌ нет в контейнере | только Portainer API |
+| SSH на хост | ❌ нет ключей | — |
+| apt install | ⚠️ слетает при rebuild | не использовать |
+| Portainer endpoint ID | **3** (не 1!) | проверять: `GET /api/endpoints` |
+
+### Передача файлов на хост — только base64
+
+```bash
+# Контент → base64 → Cmd alpine-контейнера → decode на хосте
+B64=$(printf '%s' 'content' | base64 | tr -d '\n')
+# Cmd: ["sh", "-c", "echo <B64> | base64 -d > /host/path && echo DONE"]
+# HostConfig.Binds: ["/:/host"]
+```
+
+**Никогда не использовать:** echo с кавычками, printf escaping, heredoc — все они ломаются при передаче через Docker Cmd array.
+
+### Токены в Portainer API — не через shell-переменные
+
+Hermes маскирует секреты как `***` в terminal output. `$TOKEN` в JSON передаётся буквально.
+Правильно: интерполировать значение ДО построения JSON (через Python), не в shell-строке curl.
+
+### Правило трёх попыток
+
+Если действие не удаётся 3 раза — агент должен остановиться и сообщить пользователю.
+
+---
+
 ## Шаг 11 — Hermes агент Кракен
 
 **Статус: ✅ запущен (2026-05-12), mcpvault ✅ (2026-05-13)**