# Источник истины

Этот документ фиксирует иерархию источников истины, чтобы `green-robot`, продуктовые репозитории и их `README.md` не расходились по смыслу.

## 1. Уровни истины

### 1.1. Published canonical

Published canonical живет в `green-robot` и используется для:

- пользовательской документации;
- регистрации и нормативного пакета;
- каталога продуктов и приборов;
- общей платформенной архитектуры;
- описания отраслевых применений.

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

### 1.2. Engineering canonical

Engineering canonical живет в инженерных репозиториях и используется для:

- реализации продукта;
- локальной архитектуры;
- build/run/test/deploy деталей;
- внутренних API/firmware/hardware нюансов;
- developer и operator workflows конкретного продукта.

Такие документы могут быть глубже и быстрее меняться, чем published-слой.

### 1.3. Agent-facing canonical

`README.md` в корне каждого репозитория — обязательный agent-facing source-of-truth.

Его задача:

- быстро объяснить, за что отвечает репозиторий;
- указать соответствующий продукт и published-карточку в `green-robot`;
- указать локальные engineering source-of-truth разделы;
- задать правила синхронизации документации.

`README.md` не входит в Jupyter Book, но обязателен для согласованной работы агентов и разработчиков.

## 2. Приоритет при конфликте

1. Для пользовательского, регистрационного, продуктового и платформенного описания приоритет у `green-robot`.
2. Для локальной реализации и инженерных деталей приоритет у product/hardware repo.
3. Если конфликт затрагивает общие контракты или границы продуктов, сначала обновляется `green-robot`, затем локальные repo.
4. Если конфликт затрагивает только локальную реализацию без изменения published-смысла, обновляется инженерный repo; `green-robot` меняется только при необходимости публикации нового смысла.
5. Если меняется связка `iP-1220 -> green-robot-go -> iP-1510`, включая published contract `project/monitoring/ws`, `auth/access`, локальный интерфейс `L1`, верхний уровень `L2` или update/deploy contour, published docs `green-robot` и инженерные docs должны синхронизироваться в том же push/PR.

Дополнение по инженерным семействам:

- `iC-4`, `iO-5`, `iU-6` закреплены как engineering-семейства за `../ioot-pro-hardware`;
- `iD-7` рассматривается как отдельный контур механики и электрики и должен иметь собственный engineering repo.

## 3. Что нельзя делать локально

В продуктовых репозиториях нельзя молча переопределять:

- общую архитектурную модель платформы;
- продуктовые идентификаторы и классификацию;
- общие API/event/security conventions;
- published-состав коробочного отраслевого решения.

Такие изменения должны проходить через `green-robot`.

## 4. Минимальный набор ссылок в каждом README

Каждый корневой `README.md` должен содержать:

- продукт или контур, за который отвечает repo;
- published canonical карточку в `green-robot`;
- локальный engineering source-of-truth;
- правила синхронизации;
- границы ответственности команды/repo.