# Gnexus Handbook

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

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

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

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

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

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

### Сервисам и документации
Ссылайся на конкретный файл через raw-URL:

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

## Оглавление

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

## Границы

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