docs: обновить AGENTS.md с описанием архитектуры, API, конвертаций и безопасности

AGENTS.md

@@ -1,38 +1,83 @@
 # AGENTS.md
 
 ## Проект
-Discord-бот на Python (discord.py). Команды: `!msg` (повтор текста), `!pogoda` (прогноз погоды для Магнитогорска).
+Discord-бот на Python (discord.py) для Магнитогорска.
+- Команды Discord: `!msg` (повтор текста), `!pogoda` (прогноз погоды)
+- Консольные команды: `stop` (остановка бота)
 
 ## Запуск
-```
+```bash
 pip install -r requirements.txt
 python bot.py
 ```
 
-Введите `stop` в терминал для остановки.
+Введите `stop` в терминал для остановки бота.
 
 ## Токен
 Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.env.example`.
 
 ## Конвенции
-Используй TODO-списки для каждого запроса с несколькими шагами.
+- Используй TODO-списки для каждого запроса с несколькими шагами.
+- Пиши комментарии на русском.
+- Обработка ошибок: try/except для всех внешних вызовов (API, БД, файловая система).
 
 ## Архитектура
 ```
-commands/                # Discord команды (cogs)
-  __init__.py            # ALL_COMMANDS — явные импорты
-  pogoda.py              # !pogoda
-console_commands/        # Консольные команды
-  __init__.py            # ALL_CONSOLE_COMMANDS — явные импорты
-  stop.py                # stop
+bot.py                  # Точка входа, инициализация бота, console_input()
+commands/               # Discord команды (cogs)
+  __init__.py           # ALL_COMMANDS — явные импорты
+  pogoda.py             # !pogoda — погода с retry + fallback (wttr.in → Open-Meteo)
+console_commands/       # Консольные команды
+  __init__.py           # ALL_CONSOLE_COMMANDS — явные импорты
+  stop.py               # stop — остановка бота
 ```
 
-**Добавление Discord команды:**
+### Добавление Discord команды
 1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog`
 2. Добавить импорт в `commands/__init__.py`
 3. Добавить класс в `ALL_COMMANDS`
 
-**Добавление консольной команды:**
-1. Создать файл `console_commands/имя.py` с функцией
+### Добавление консольной команды
+1. Создать файл `console_commands/имя.py` с функцией `func(stop_event, bot)`
 2. Добавить импорт в `console_commands/__init__.py`
 3. Добавить функцию в `ALL_CONSOLE_COMMANDS`
+
+## API и внешние сервисы
+
+### Погода (!pogoda)
+- **Основной**: `wttr.in` (бесплатный, без ключа)
+- **Fallback**: `api.open-meteo.com` (бесплатный, без ключа)
+- Retry: 3 попытки с экспоненциальной задержкой при SSL/Connection/Timeout ошибках
+- Fallback срабатывает автоматически при неуспешных попытках
+- WMO weather codes → русский перевод в `_wmo_to_russian()`
+
+### Конвертации
+- Давление: hPa → мм рт. ст. (`* 0.750062`)
+- Ветер: км/ч → м/с (`/ 3.6`)
+- Погодные описания: английский → русский (`_translate_weather()`)
+
+## Конфигурация
+| Переменная | Описание | Где взять |
+|------------|----------|-----------|
+| `DISCORD_TOKEN` | Токен бота | Discord Developer Portal |
+
+## Зависимости
+```txt
+discord.py>=2.3.2
+python-dotenv>=1.0.0
+requests>=2.31.0
+```
+
+## Структура данных погоды
+Команда `!pogoda` возвращает:
+```
+[TEMP]   Температура: X°C (ощущается как Y°C)
+[DESC]   Описание: Z
+[HUMID]  Влажность: X%
+[WIND]   Ветер: X м/с
+[PRESS]  Давление: X мм рт. ст.
+```
+
+## Безопасность
+- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий.
+- Используй `.env.example` как шаблон.