Gnexus Handbook

Единый источник политики, конвенций и инструкций для всех сервисов экосистемы Gnexus.

Зачем этот репозиторий

При создании нового сервиса одни и те же правила приходится повторять каждый раз: как подключить SSO, где хранить секреты, как получить домен, что документировать. Этот репозиторий — место, на которое ссылаются вместо повторения.

Как этим пользоваться

Владельцу

• При постановке задачи на новый сервис: «Конвенции — в gnexus-handbook, раздел X».
• Изменение правила = изменение здесь, а не в очередном чате.

Агентам (Navi и другим ИИ)

• Перед созданием нового сервиса прочитай этот README и релевантные разделы.
• Разделы написаны по-разному: конвенции (10-platform/, 30-operations/) формулируют правила; справочники (20-deployment/) информируют о том, как здесь что устроено, — без предписаний.
• Если правило противоречит задаче владельца — владелец прав, но предложи обновить handbook.
• Нашёл нюанс, баг или недоработку в общем ресурсе — фиксируй в проекте самого ресурса, а не только у себя: 10-platform/feedback.md.
• Не копируй правила в другие репозитории и промпты — ссылайся сюда.

Сервисам и документации

Ссылайся на конкретный файл через raw-URL:

https://git.gnexus.space/root/gnexus-handbook/raw/master/<path>

Оглавление

• 00-principles.md — базовые принципы платформы
• 10-platform/ — конвенции интеграции с общей инфраструктурой
  • auth.md — SSO через gnexus-auth
  • i18n.md — мультиязычность интерфейса
  • mcp.md — MCP и API-токены для ИИ-агентов
  • ui.md — UI и визуальный стиль
  • feedback.md — обратная связь в общие ресурсы: находки и предложения по ui-kit, SDK, контрактам
  • health.md — health-эндпоинт сервисов
  • notifications.md — уведомления через Gnexus Synapse: конвенция интеграции (источник с syn_*, конверт v1, webhook-цель)
  • secrets.md — секреты
  • git.md — Git и GitBucket
• 20-deployment/ — справка о размещении, доменах и бэкапах (информация, не предписания)
  • hosting.md — где что живёт
  • domains.md — домены и маршруты
  • backups.md — бэкапы
• 30-operations/ — конвенции эксплуатации
  • monitoring.md — мониторинг и алерты
  • docs.md — документирование в gnexus-book
• 90-templates/ — шаблоны
  • new-service-checklist.md
  • service-doc-template.md

Границы

Этот репозиторий — только правила и справки. Факты (IP, версии, состояние, маршруты) живут в gnexus-book: https://git.gnexus.space/root/gnexus-book (для агентов — через MCP).