# Федерация документации

`green-robot` не должен быть полным зеркалом всех инженерных деталей. Вместо этого используется федеративная модель: опубликованный контур и инженерные контуры синхронизируются по явным правилам.

## 1. Цель модели

- не дублировать одни и те же технические детали в пяти репозиториях;
- сохранить один published-вход для пользователя и регистрации;
- сохранить быстрый вход для агентов через `README.md` каждого repo;
- избежать расхождения общих контрактов и архитектуры.

## 2. Слои документации

### 2.1. Published layer (`green-robot`)

Содержит:

- `Документы`;
- `Продукты`;
- `Платформа`;
- `Применение`.

Это слой для пользователя, аудитора, регистрационного контура и кросс-проектного согласования.

### 2.2. Engineering layer (product repos)

Содержит:

- код и реальные runtime artifacts;
- внутреннюю архитектуру продукта;
- build/test/deploy flow;
- detailed operator/developer docs.

### 2.3. Agent layer (`README.md`)

Содержит краткую инструкцию:

- что это за repo;
- какой продукт он реализует;
- где published canonical в `green-robot`;
- где engineering canonical внутри repo;
- что агент обязан синхронизировать при изменениях.

## 3. Правила синхронизации

1. Изменение локальной реализации без смены published-смысла:
   - правится engineering repo;
   - `green-robot` меняется только если пользовательский/регистрационный смысл изменился.

2. Изменение общего контракта, архитектуры или классификации продукта:
   - сначала правится `green-robot`;
   - затем связанные engineering repo.

3. Изменение отраслевого решения:
   - сначала обновляются `Применение` и платформенные связи в `green-robot`;
   - затем прикладной product repo, если изменена реализация.

4. Изменение обязанностей repo или source-of-truth:
   - обязательно обновляются `README.md` затронутых репозиториев.
5. Изменение published contract `project/monitoring/ws`, `auth/access`, git-driven deploy chain или product-chain `iP-1220 -> green-robot-go -> iP-1510`:
   - published/product docs и engineering docs обновляются в одном push;
   - отложенная документационная синхронизация не допускается.

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

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

## 4. Что проверять агенту перед правкой

1. Это published-изменение или локальная реализация?
2. Затронут ли продуктовый идентификатор, платформенный контракт или отраслевую связность?
3. Обновлен ли `README.md` репозитория, если изменились зоны ответственности?
4. Нужна ли синхронизация в `green-robot` после локальной правки?

## 5. Практический результат

Такая схема позволяет:

- держать `green-robot` как каноническую публикацию и регистрационный контур;
- не дублировать в нем полностью инженерную документацию из `ioot-pro-*`;
- дать агентам быстрый и единый способ понять границы ответственности через `README.md`.