# Архетипы экрана KT AI

Архетип — это форма главной рабочей области под задачу процесса. Набор **открыт**: archetypes/registry.json — это каталог-данные, а не зашитый список. Добавление архетипа = запись в реестр + рендерер + пример, **без правки валидатора и ядра**. Неизвестный или ещё не реализованный архетип безопасно деградирует в `queue`.

Это прямой ответ на вопрос «а если архетипов больше?»: система относится к архетипам как к данным. Реестр растёт; контракт (`product.schema.json`) общий; валидатор (`scripts/validate_product.py`) читает реестр и не меняется; рантайм (`templates/kt-ai-app-shell.html`) подбирает рендерер по id с фолбэком.

## Галерея

Все архетипы живьём в одном экране: `examples/gallery.html` (табы, генерируется `scripts/build_gallery.py` после пересборки прототипов). У каждого stable-архетипа есть отгружаемый пример.

## Контракт записи реестра

```json
{
  "id": "compare",                      // lowercase id, = значение product.archetype
  "title": "Сверка источников",
  "whenToUse": "когда применять (1 фраза)",
  "requires": ["table", "compare"],     // блоки контракта, без которых архетип не имеет смысла → ERROR
  "recommends": ["scenario", "drawer"],  // желательные блоки → WARN, если их нет
  "forbids": [],                         // блоки, которых быть не должно → ERROR
  "renderer": "renderCompare",           // имя функции-рендерера в app-shell (null, если ещё нет)
  "runtimes": ["html", "kit"],           // где архетип РЕАЛЬНО реализован
  "status": "stable"                     // stable – рендерится; planned – пока деградирует в fallback
}
```

**`runtimes` — обязательное поле, и его держит в согласии с кодом гейт 21.**
`status: stable` говорит только о том, что архетип рендерится; в каком рантайме
— не говорит. Пока поля не было, реестр объявлял stable все пятнадцать
архетипов, а React-кит рисовал шесть: продукт на Next выбирал `inbox`, получал
деградацию в `queue` и узнавал об этом, увидев не тот экран. Ни реестр, ни
валидатор, ни гейт не произносили ни слова.

Теперь валидатор пишет об этом заметкой при проверке конфига, а гейт 21 сверяет
реестр с тем, что действительно реализовано в `kt-ai-screen.tsx`. Реализовали
архетип в ките — допишите `kit` в `runtimes`, иначе сборка ДС покраснеет.

В ките сегодня: `queue`, `dashboard`, `cockpit`, `compare`, `conversational`,
`custom`. Остальные девять — только HTML-рантайм.

Валидатор по этой записи проверяет конфиг автоматически — для любого числа архетипов код не меняется.

## Реализованные (stable)

| id | Когда | Главная область | Референс |
|---|---|---|---|
| `queue` | 5+ записей со статусом/сроком/суммой; проверить и закрыть (дефолт) | таблица + drawer | — |
| `dashboard` | управление метрикой процесса | KPI-табы → большой чарт периода + разборы (top/share/cards) + «требует внимания» | ElevenLabs dashboard (Mobbin) |
| `cockpit` | один фокусный объект с сигналами + решение | карточка решения + очередь сбоку | ElevenLabs TTS playground (рабочая область + тихая панель) |
| `compare` | попарная сверка двух источников/версий | две панели, расхождения подсвечены | — |
| `conversational` | чат как главная область, человек вне построчной очереди | центрированный чат, орб-аватар, prompt-bar | ElevenLabs Conversational AI |
| `custom` | **экран не подходит ни под один архетип** (запасной) | центрированная колонка секций-карточек | ElevenLabs settings-detail |
| `document` | документоцентричный процесс: вычитка одного документа (договор, письмо, ТЗ) | документ с diff-правками агента по фрагментам, принять/отклонить каждую | Harvey, «договоры/письма Lotus» |
| `copilot` | агент производит файл/документ/слайды в диалоге | чат слева + живой предпросмотр артефакта справа | ChatGPT Canvas, Claude Artifacts |
| `wizard` | пошаговая подача заявки/оформление с автозаполнением агентом | степпер + поля с бейджем «заполнил агент», Назад/Далее | госуслуги, Typeform |
| `kanban` | поток работ по стадиям, важно распределение | колонки = statuses, карточки = table.rows (без новых блоков) | Trello, Linear board |
| `inbox` | входящие с длинным текстом (обращения, письма) | список слева + постоянная панель чтения с разбором агента | почтовые клиенты, Front |
| `analytics` | главная ценность — анализ и выводы, не построчная работа | сводка агента + чарты (bar/line/donut, чистый SVG) + «Выводы агента» | Amplitude, Metabase |
| `calendar` | работа привязана к датам и слотам | события по дням, тон-подсветка конфликтов | календарь-агенда |
| `map` | объекты распределены в пространстве (станции, площадки) | SVG-схема с точками-статусами и связями; не геокарта с тайлами | схемы линий метро |
| `timeline` | разбор одного дела/инцидента во времени | вертикальная лента: время, событие, актор (шаги агента помечены) | audit log, Intercom timeline |

## Заявленные (planned)

— нет. Все архетипы реестра реализованы.

## Когда экран не подходит ни под один архетип

Это штатная ситуация, не ошибка. Два пути:

1. **Явно** — поставить `archetype: "custom"` и описать `contract.sections` (заголовок + опц. описание/текст/поля). Рендерится колонкой карточек в духе ElevenLabs detail-страниц.
2. **Автоматически** — если архетип неизвестен или не реализован, `mainByLayout` подбирает форму по данным: есть `sections` → custom; есть таблица с рядами → queue; иначе → custom (пустой с подсказкой). Экран никогда не падает и не показывает пустую таблицу не к месту.

## Набор открыт

Реестр прямо перечисляет очевидных кандидатов (`open_set_examples`): `gantt`, `gallery`, `editor`, `org`. Это не обещания — маркер того, что список не закрыт. До появления их рендереров такие экраны делает `custom`.

## Как добавить архетип

По «правилу двух продуктов» (DESIGN.md): архетип появляется, когда он нужен **второму** продукту, не раньше.

1. **Реестр.** Добавить запись в `archetypes/registry.json` (`status:"planned"`, `renderer:null` — на этом шаге уже можно валидировать контракт).
2. **Рендерер.** Написать `renderXxx()` в `templates/kt-ai-app-shell.html` и ветку в `mainByLayout()`; перевести запись в `status:"stable"`, `renderer:"renderXxx"`. Главную оболочку (sidebar/topbar/тема/орб Төре) не трогать — меняется только главная область.
3. **Контракт.** Если архетипу нужен новый блок данных (как `compare`), добавить его в `product.schema.json`.
4. **Пример.** Положить эталонный конфиг в `examples/` и прогнать `scripts/validate_product.py`.
5. **Док.** Дописать строку в таблицу выше.

## Деградация

- Неизвестный `archetype` → WARN + рендерится `queue`.
- `status:"planned"` → WARN + рендерится `fallback` (queue).
- `compare` без `compare.pairs` → WARN + рендерится `queue`.

Прототип никогда не падает из-за архетипа — в худшем случае показывает надёжную таблицу-очередь.