diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
new file mode 100644
index 0000000..5f8d1dc
--- /dev/null
+++ b/docs/COMMANDS.md
@@ -0,0 +1,44 @@
+# Справочник команд
+
+Файл создан автоматически из `ops/bots/commands.yaml`.
+**Правьте справочник, а не этот файл.**
+
+## ADM — Управление службами и состояние инфраструктуры
+Отвечает на команды о состоянии и выполняет перезапуски.
+
+| Команда | Что делает | Доступ | Состояние |
+|---|---|---|---|
+| `/status` | Показывает состояние хостов и служб с ответами проверок. | все | готово |
+| `/issues` | Список открытых задач Gitea с метками важности. | все | готово |
+| `/runbook <сервис>` | Показывает инструкцию по обслуживанию указанного сервиса. | все | готово |
+| `/restart <сервис>` | Перезапускает службу через службу восстановления. | админ | готово |
+
+## WORK — Обновления и рабочие задачи
+Показывает очередь обновлений и принимает решения по ним.
+
+| Команда | Что делает | Доступ | Состояние |
+|---|---|---|---|
+| `/queue` | Показывает очередь обновлений с номерами заявок. | все | готовится |
+| `/approve <номер>` | Ставит заявку в работу — обновление будет выполнено. | админ | готовится |
+| `/reject <номер>` | Отклоняет заявку — обновление выполнено не будет. | админ | готовится |
+| `/update <служба>` | Немедленно ставит обновление службы в очередь. | админ | готовится |
+
+## AUTH — Доступ и регистрация
+Обслуживает заявки на доступ к сервисам.
+
+| Команда | Что делает | Доступ | Состояние |
+|---|---|---|---|
+| `/requests` | Показывает необработанные заявки на регистрацию. | админ | готовится |
+| `/approve-user <почта>` | Даёт доступ указанному пользователю и создаёт учётную запись. | админ | готовится |
+| `/deny-user <почта>` | Отклоняет заявку на доступ. | админ | готовится |
+
+## MEDIA — Медиа-службы
+Состояние и управление медиасервисами.
+
+| Команда | Что делает | Доступ | Состояние |
+|---|---|---|---|
+| `/media` | Показывает состояние медиасервисов и их очереди загрузок. | все | готовится |
+
+## Общие команды
+
+- `/help [команда]` — Показывает команды этого бота. Можно указать команду подробнее.
diff --git a/ops/bots/commands.yaml b/ops/bots/commands.yaml
new file mode 100644
index 0000000..9dab577
--- /dev/null
+++ b/ops/bots/commands.yaml
@@ -0,0 +1,189 @@
+# ============================================================
+# Справочник команд buryan-hub — ЕДИНСТВЕННЫЙ ИСТОЧНИК ПРАВДЫ
+# ============================================================
+# Из этого файла генерируется:
+# * ответ /help в каждом боте (только его команды);
+# * docs/COMMANDS.md в репозитории;
+# * закреплённое сообщение в комнате Matrix.
+#
+# ДОБАВИТЬ КОМАНДУ = ДОБАВИТЬ ЗАПИСЬ СЮДА. Помощь обновится сама.
+#
+# Поля:
+# command — как вызывается, без слэша
+# bot — какому боту принадлежит: adm | work | alert | auth | media
+# title — короткое название
+# description — что делает, одним предложением
+# usage — как вызывать
+# examples — примеры (показываются в /help)
+# access — admin | user (кто может вызывать)
+# aliases — другие написания
+# status — ready | planned (planned показывается серым, но видно)
+
+bots:
+ adm:
+ name: ADM
+ purpose: Управление службами и состояние инфраструктуры
+ about: Отвечает на команды о состоянии и выполняет перезапуски.
+
+ work:
+ name: WORK
+ purpose: Обновления и рабочие задачи
+ about: Показывает очередь обновлений и принимает решения по ним.
+
+ alert:
+ name: ALERT
+ purpose: Тревоги инфраструктуры
+ about: Только сообщает о проблемах и восстановлении. Команд не принимает.
+
+ auth:
+ name: AUTH
+ purpose: Доступ и регистрация
+ about: Обслуживает заявки на доступ к сервисам.
+
+ media:
+ name: MEDIA
+ purpose: Медиа-службы
+ about: Состояние и управление медиасервисами.
+
+commands:
+
+ # ─── ADM: состояние и управление ───────────────────────────
+ - command: status
+ bot: adm
+ title: Состояние служб
+ description: Показывает состояние хостов и служб с ответами проверок.
+ usage: /status
+ examples:
+ - /status
+ access: user
+ aliases: ["!status"]
+ status: ready
+
+ - command: issues
+ bot: adm
+ title: Открытые задачи
+ description: Список открытых задач Gitea с метками важности.
+ usage: /issues
+ examples:
+ - /issues
+ access: user
+ aliases: ["!issues"]
+ status: ready
+
+ - command: runbook
+ bot: adm
+ title: Ранбук сервиса
+ description: Показывает инструкцию по обслуживанию указанного сервиса.
+ usage: /runbook <сервис>
+ examples:
+ - /runbook radarr
+ - /runbook n8n
+ access: user
+ aliases: ["!runbook"]
+ status: ready
+
+ - command: restart
+ bot: adm
+ title: Перезапуск службы
+ description: Перезапускает службу через службу восстановления.
+ usage: /restart <сервис>
+ examples:
+ - /restart radarr
+ access: admin
+ aliases: ["!restart"]
+ status: ready
+
+ # ─── WORK: обновления ──────────────────────────────────────
+ - command: queue
+ bot: work
+ title: Очередь обновлений
+ description: Показывает очередь обновлений с номерами заявок.
+ usage: /queue
+ examples:
+ - /queue
+ access: user
+ status: planned
+
+ - command: approve
+ bot: work
+ title: Одобрить обновление
+ description: Ставит заявку в работу — обновление будет выполнено.
+ usage: /approve <номер>
+ examples:
+ - /approve 17
+ access: admin
+ status: planned
+
+ - command: reject
+ bot: work
+ title: Отклонить обновление
+ description: Отклоняет заявку — обновление выполнено не будет.
+ usage: /reject <номер>
+ examples:
+ - /reject 17
+ access: admin
+ status: planned
+
+ - command: update
+ bot: work
+ title: Обновить службу сейчас
+ description: Немедленно ставит обновление службы в очередь.
+ usage: /update <служба>
+ examples:
+ - /update prowlarr
+ access: admin
+ status: planned
+
+ # ─── AUTH: доступ ──────────────────────────────────────────
+ - command: requests
+ bot: auth
+ title: Заявки на доступ
+ description: Показывает необработанные заявки на регистрацию.
+ usage: /requests
+ examples:
+ - /requests
+ access: admin
+ status: planned
+
+ - command: approve-user
+ bot: auth
+ title: Одобрить заявку
+ description: Даёт доступ указанному пользователю и создаёт учётную запись.
+ usage: /approve-user <почта>
+ examples:
+ - /approve-user user@example.com
+ access: admin
+ status: planned
+
+ - command: deny-user
+ bot: auth
+ title: Отклонить заявку
+ description: Отклоняет заявку на доступ.
+ usage: /deny-user <почта>
+ examples:
+ - /deny-user user@example.com
+ access: admin
+ status: planned
+
+ # ─── MEDIA: медиасервисы ───────────────────────────────────
+ - command: media
+ bot: media
+ title: Состояние медиасервисов
+ description: Показывает состояние медиасервисов и их очереди загрузок.
+ usage: /media
+ examples:
+ - /media
+ access: user
+ status: planned
+
+ # ─── Общие для всех ботов ──────────────────────────────────
+ - command: help
+ bot: all
+ title: Справка
+ description: Показывает команды этого бота. Можно указать команду подробнее.
+ usage: /help [команда]
+ examples:
+ - /help
+ - /help restart
+ access: user
+ status: ready
diff --git a/ops/bots/gen_help.py b/ops/bots/gen_help.py
new file mode 100644
index 0000000..a982bde
--- /dev/null
+++ b/ops/bots/gen_help.py
@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""Генератор справки по командам.
+
+Из единственного источника правды (commands.yaml) делает:
+ * ответ /help для каждого бота — только его команды;
+ * docs/COMMANDS.md — общий справочник в репозитории;
+ * подсказку при опечатке.
+
+Зачем: команды не должны жить в голове и не должны быть зашиты
+в код. Добавить команду = добавить запись в commands.yaml,
+а справка обновится сама.
+
+Использование:
+ python3 gen_help.py — показать справку всем ботам
+ python3 gen_help.py --bot adm — справка одного бота
+ python3 gen_help.py --command restart — подробно про команду
+ python3 gen_help.py --markdown FILE — записать общий справочник
+ python3 gen_help.py --suggest statsu — подсказать похожую команду
+"""
+from __future__ import annotations
+
+import argparse
+import difflib
+import os
+import sys
+
+try:
+ import yaml
+except ImportError: # запасной разбор, если PyYAML не установлен
+ yaml = None
+
+CATALOG = os.getenv("COMMANDS_FILE",
+ os.path.join(os.path.dirname(os.path.abspath(__file__)),
+ "commands.yaml"))
+
+
+def load(path: str = CATALOG) -> dict:
+ """Читает справочник. Если PyYAML нет — разбирает встроенным способом."""
+ with open(path, encoding="utf-8") as fh:
+ text = fh.read()
+ if yaml is not None:
+ return yaml.safe_load(text)
+ return _simple_parse(text)
+
+
+def _simple_parse(text: str) -> dict:
+ """Минимальный разбор YAML для нашего формата — без внешних зависимостей.
+
+ Понимает списки словарей с простыми значениями и списками строк.
+ Нужен, чтобы справка работала даже там, где PyYAML не установлен.
+ """
+ data: dict = {"bots": {}, "commands": []}
+ section = None
+ item: dict | None = None
+ list_key = None
+ bot_key = None
+ bot_item: dict | None = None
+
+ for raw in text.split("\n"):
+ line = raw.rstrip()
+ if not line or line.lstrip().startswith("#"):
+ continue
+ stripped = line.strip()
+
+ if line.startswith("bots:") and not line.startswith(" "):
+ section, item, bot_item = "bots", None, None
+ continue
+ if line.startswith("commands:") and not line.startswith(" "):
+ section, item, bot_item = "commands", None, None
+ continue
+
+ if section == "bots":
+ if line.startswith(" ") and not line.startswith(" ") and stripped.endswith(":"):
+ bot_key = stripped[:-1]
+ bot_item = {}
+ data["bots"][bot_key] = bot_item
+ continue
+ if bot_item is not None and ":" in stripped:
+ k, v = stripped.split(":", 1)
+ bot_item[k.strip()] = v.strip()
+ continue
+ continue
+
+ if section == "commands":
+ if stripped.startswith("- "):
+ item = {}
+ data["commands"].append(item)
+ list_key = None
+ rest = stripped[2:]
+ if ":" in rest:
+ k, v = rest.split(":", 1)
+ item[k.strip()] = v.strip()
+ continue
+ if item is None:
+ continue
+ if stripped.endswith(":") and not stripped.startswith("-"):
+ list_key = stripped[:-1]
+ item[list_key] = []
+ continue
+ if stripped.startswith("- ") and list_key:
+ item[list_key].append(stripped[2:].strip().strip('"\''))
+ continue
+ if ":" in stripped:
+ k, v = stripped.split(":", 1)
+ item[k.strip()] = v.strip().strip('"\'')
+ list_key = None
+ return data
+
+
+def commands_for(data: dict, bot: str) -> list[dict]:
+ """Команды бота: его собственные плюс общие (bot: all)."""
+ out = []
+ for cmd in data.get("commands", []):
+ if cmd.get("bot") in (bot, "all"):
+ out.append(cmd)
+ return out
+
+
+def help_text(data: dict, bot: str) -> str:
+ """Справка для бота. Коротко: название, вызов, описание."""
+ info = data.get("bots", {}).get(bot, {})
+ lines = []
+ if info.get("name"):
+ lines.append(f"{info['name']} — {info.get('purpose', '')}")
+ lines.append("")
+
+ ready = [c for c in commands_for(data, bot) if c.get("status") != "planned"]
+ planned = [c for c in commands_for(data, bot) if c.get("status") == "planned"]
+
+ lines.append("Доступные команды:")
+ for cmd in ready:
+ access = " (только админ)" if cmd.get("access") == "admin" else ""
+ lines.append(f"/{cmd['command']} — {cmd.get('description', '')}{access}")
+
+ if planned:
+ lines.append("")
+ lines.append("Готовятся:")
+ for cmd in planned:
+ lines.append(f"/{cmd['command']} — {cmd.get('description', '')}")
+
+ lines.append("")
+ lines.append("Подробнее о команде: /help <команда>")
+ return "\n".join(lines)
+
+
+def command_help(data: dict, name: str) -> str | None:
+ """Подробная справка по одной команде."""
+ name = name.lstrip("/!").strip()
+ for cmd in data.get("commands", []):
+ if cmd.get("command") == name or name in (cmd.get("aliases") or []):
+ lines = [f"/{cmd['command']} — {cmd.get('title', '')}"]
+ lines.append(cmd.get("description", ""))
+ lines.append("")
+ lines.append(f"Вызов: {cmd.get('usage', '/' + cmd['command'])}")
+ if cmd.get("examples"):
+ lines.append("Примеры:")
+ for ex in cmd["examples"]:
+ lines.append(f" {ex}")
+ if cmd.get("aliases"):
+ lines.append(f"Варианты: {', '.join(cmd['aliases'])}")
+ if cmd.get("access") == "admin":
+ lines.append("Доступ: только администратор")
+ if cmd.get("status") == "planned":
+ lines.append("Состояние: готовится, пока не работает")
+ if cmd.get("bot") and cmd["bot"] != "all":
+ lines.append(f"Бот: {data.get('bots', {}).get(cmd['bot'], {}).get('name', cmd['bot'])}")
+ return "\n".join(lines)
+ return None
+
+
+def suggest(data: dict, wrong: str | None) -> str | None:
+ """Подсказка при опечатке: «возможно, вы имели в виду»."""
+ if not wrong:
+ return None
+ names = [c["command"] for c in data.get("commands", [])]
+ close = difflib.get_close_matches(wrong.lstrip("/!").strip(), names, n=1, cutoff=0.6)
+ if close:
+ return f"Команда не распознана. Возможно, вы имели в виду /{close[0]}? Список: /help"
+ return "Команда не распознана. Список команд: /help"
+
+
+def markdown(data: dict) -> str:
+ """Общий справочник для репозитория."""
+ lines = ["# Справочник команд", "",
+ "Файл создан автоматически из `ops/bots/commands.yaml`.",
+ "**Правьте справочник, а не этот файл.**", ""]
+
+ for bot_key, info in data.get("bots", {}).items():
+ cmds = [c for c in commands_for(data, bot_key) if c.get("bot") == bot_key]
+ if not cmds:
+ continue
+ lines.append(f"## {info.get('name', bot_key)} — {info.get('purpose', '')}")
+ if info.get("about"):
+ lines.append(info["about"])
+ lines.append("")
+ lines.append("| Команда | Что делает | Доступ | Состояние |")
+ lines.append("|---|---|---|---|")
+ for cmd in cmds:
+ access = "админ" if cmd.get("access") == "admin" else "все"
+ state = "готово" if cmd.get("status") != "planned" else "готовится"
+ lines.append(f"| `{cmd.get('usage', '/' + cmd['command'])}` | "
+ f"{cmd.get('description', '')} | {access} | {state} |")
+ lines.append("")
+
+ lines.append("## Общие команды")
+ lines.append("")
+ for cmd in data.get("commands", []):
+ if cmd.get("bot") == "all":
+ lines.append(f"- `{cmd.get('usage')}` — {cmd.get('description', '')}")
+ lines.append("")
+ return "\n".join(lines)
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description="Генератор справки по командам")
+ ap.add_argument("--bot", help="показать справку одного бота")
+ ap.add_argument("--command", help="подробно про команду")
+ ap.add_argument("--suggest", help="подсказать похожую команду")
+ ap.add_argument("--markdown", metavar="FILE", help="записать общий справочник")
+ ap.add_argument("--catalog", default=CATALOG, help="путь к справочнику")
+ args = ap.parse_args()
+
+ if not os.path.exists(args.catalog):
+ print(f"справочник не найден: {args.catalog}", file=sys.stderr)
+ return 1
+ data = load(args.catalog)
+
+ if args.command:
+ print(command_help(data, args.command) or "Команда не найдена")
+ return 0
+ if args.suggest:
+ print(suggest(data, args.suggest) or "")
+ return 0
+ if args.markdown:
+ with open(args.markdown, "w", encoding="utf-8") as fh:
+ fh.write(markdown(data))
+ print(f"записан справочник: {args.markdown}")
+ return 0
+ if args.bot:
+ print(help_text(data, args.bot))
+ return 0
+
+ for bot in data.get("bots", {}):
+ print("=" * 60)
+ print(help_text(data, bot))
+ print()
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())