docs: Update docs for the correctness (#13)

services/docs/content/ru/quetza/troubleshooting/_index.md

@@ -0,0 +1,12 @@
+---
+title: Устранение неполадок
+weight: 5
+---
+
+Устранение неполадок в **Quetza** фокусируется на диагностике структурных и концептуальных проблем. Из-за его природы, основанной на соглашениях (convention-based), большинство ошибок протекают бесшумно (отсутствующие файлы), а не с шумом (трассировка стека/stack traces).
+
+## Основные категории проблем
+
+{{% cards %}}
+{{< card link="diagnostics" title="Руководство по диагностике" icon="exclamation" subtitle="Решения для обнаружения модулей, регистрации команд и утечек состояния." >}}
+{{% /cards %}}

services/docs/content/ru/quetza/troubleshooting/diagnostics.md

@@ -0,0 +1,73 @@
+---
+title: Диагностика
+weight: 1
+---
+
+**Цель:** Определить и устранить распространенные ловушки при разработке Quetza.
+
+## 1. Сбои при обнаружении модулей
+
+**Симптом:** Бот запускается, но ваш модуль игнорируется.
+**Причина:** Нарушение соглашений файловой системы.
+
+{{% details title="Чек-лист: Структура директорий" closed="false" %}}
+
+- [ ] Существует ли `src/modules/<name>/`?
+- [ ] Экспортирует ли `module.ts` переменную `name`?
+- [ ] Находятся ли команды в `commands/` (а не в `cmds/`)?
+- [ ] Запустили ли вы `pnpm build`? (Quetza запускается из `dist/`).
+      {{% /details %}}
+
+## 2. Проблемы с регистрацией команд
+
+**Симптом:** Команда `/command` не появляется в Discord.
+
+### Глобальная регистрация против регистрации в тестовой гильдии (Guild)
+
+- **Глобальная:** Команды, отправленные в приложение глобально, могут обновляться до 1 часа и подчиняются более строгим ограничениям скорости (rate limits).
+- **Тестовая гильдия:** Quetza автоматически отправляет команды в конкретную гильдию в режиме разработки для мгновенного обновления.
+  - **Требование:** Убедитесь, что `NODE_ENV=development` и `DEV_GUILD_ID` корректно установлены в вашем `.env`.
+
+### Ограничения скорости (Rate Limits)
+
+Частые обновления глобальных команд могут вызвать ограничения скорости со стороны Discord. Используйте тестовую гильдию для итеративной разработки.
+
+## 3. Ошибки взаимодействия (Interaction Failures)
+
+**Симптом:** «Приложение не отвечает».
+**Причина:** Выполнение команды заняло более 3 секунд без отложенного ответа (deferral).
+
+**Решение:**
+
+```typescript
+// ПЛОХО
+await longRunningTask();
+await interaction.reply('Готово'); // Слишком поздно!
+
+// ХОРОШО
+await interaction.deferReply();
+await longRunningTask();
+await interaction.editReply('Готово');
+```
+
+## 4. Утечки состояния
+
+**Симптом:** Потребление памяти ботом растет; странности во взаимодействии между серверами.
+**Причина:** Хранение состояния глобально вместо уровня гильдии.
+
+**Диагностика:**
+Проверьте ваш контроллер.
+
+- ❌ `private player: AudioPlayer;` (Общий для всех!)
+- ✅ `private players = new Map<string, AudioPlayer>();` (Разделен по ID гильдии).
+
+## 5. Обработка событий
+
+**Симптом:** События срабатывают несколько раз или не срабатывают вовсе.
+
+- **Несколько раз:** События являются аддитивными. Не зарегистрировали ли вы один и тот же обработчик в двух модулях?
+- **Ни разу:** Правильно ли вы экспортировали `name` и `execute`?
+
+> [!TIP]
+> **Debug Mode:**
+> Включите подробное логирование, чтобы точно увидеть, какие модули и команды загружаются при запуске.