| 1 | # Онбординг и First Run — живой чертёж (v1) |
| 2 | |
| 3 | **Статус:** живой чертёж (не ADR). **Обновлено:** 2026-04-06 — первичная версия: принципы, флаг vs режим, PFD + чеклист, связи с ADR. |
| 4 | **Принципы и налог на модель** — [ADR 0021 §19](../adr/0021-pfd-mfd-cockpit-attention-model.md#19-онбординг-снижение-налога-на-модель-и-диалог-с-аудиторией); **палитра и discoverability** — [ADR 0013](../adr/0013-command-surface-and-discoverability.md); **ситуационные чеклисты** — [ADR 0014](../adr/0014-situational-checklists.md). Здесь — **идеи, сценарии и план реализации**, чтобы не раздувать ADR. |
| 5 | |
| 6 | --- |
| 7 | |
| 8 | ## 1. Назначение документа |
| 9 | |
| 10 | - Единое место для **нарастающего** списка решений по первому запуску, повторному онбордингу после обновлений и связанным UX-идеям (PFD, палитра, зоны, агент). |
| 11 | - Дополняется по мере появления инсайтов; **инварианты продукта** остаются в ADR. |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## 2. Принципы (согласованы с ADR 0021 §19) |
| 16 | |
| 17 | - Любой заметный блок онбординга закрывает рамку **Почему? / Зачем? / Что мне это даст?** (таблица в §19.2 ADR 0021). |
| 18 | - Онбординг снижает **onboarding tax** — не дублирует длинный текст из спецификации, а ведёт к **задачам** (открыть решение, понять зону, безопасный шаг агента). |
| 19 | - **Не путать** с обязательным прохождением «курса»: пользователь должен иметь путь **пропустить / вернуть позже**, без блокировки работы (детали — при реализации). |
| 20 | |
| 21 | ### 2.1 Ментальная модель: Driver/Navigator (PF/PM) |
| 22 | |
| 23 | Чтобы быстро объяснить модель внимания без авиационного лора, используем мостик из парного программирования: |
| 24 | |
| 25 | - **Driver (PF / Pilot Flying)**: “руки на штурвале”. Цель — быстро править и двигаться вперёд. В онбординге это означает: держись лобового/редактора, используй HUD‑подсказки, не утопай в панелях. |
| 26 | - **Navigator (PM / Pilot Monitoring)**: “держит картину и риски”. Цель — проверить, что ты не уходишь в неверном направлении. В онбординге это означает: смотреть в PFD/MFD/EICAS (по пресету) за диагностикой, планом, логами, статусами. |
| 27 | |
| 28 | Практическое правило для чеклиста: если ты **редактируешь** — ты Driver; если ты **проверяешь/сверяешь/планируешь** — ты Navigator. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## 3. First Run: флаг, не режим UI |
| 33 | |
| 34 | | Понятие | Смысл | |
| 35 | |--------|--------| |
| 36 | | **Режим UI** (Focus / Balanced / Power / …) | Пресет плотности и семьи из [ADR 0010](../adr/0010-ui-modes-toml-configuration.md) — **постоянная** политика раскладки. | |
| 37 | | **First Run (рабочее имя)** | Отдельное состояние онбординга приложения: **флаг(и)** в настройках (например «первый запуск не завершён», «версия пройденного сценария»), **ортогонально** текущему `UiMode`. | |
| 38 | |
| 39 | **Зачем разделять:** пресет режима не должен переключаться только потому, что человек впервые открыл IDE; и наоборот — завершение чеклиста не обязано менять выбранный Focus/Balanced/Power. |
| 40 | |
| 41 | *Открытые решения (дополнять по мере проектирования):* имена ключей, хранение в `%LocalAppData%\CascadeIDE\` vs репозиторий, сброс при major-версии (`first_run_schema_version`). |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## 4. PFD как место для чеклиста First Run (идея) |
| 46 | |
| 47 | - **Якорь PFD** в ADR 0021 — первичный **контекст** workspace; во время First Run туда логично вывести **короткий чеклист** (открыть решение, зоны внимания, палитра, уровень безопасности агента — состав уточняется). |
| 48 | - После завершения или отложенного пропуска содержимое PFD возвращается к **обычному** (дерево, мини-карта задачи, другое по пресету и `[attention_zone_panels]` — см. ADR 0021 §2 / §17). |
| 49 | - Связь с [ADR 0014](../adr/0014-situational-checklists.md): First Run — частный случай **ситуации** «первое знакомство»; не заменяет палитру и не смешивается с полным каталогом команд без контекста. |
| 50 | |
| 51 | --- |
| 52 | |
| 53 | ## 5. Command Palette (`Ctrl+Q`) и навигация без постоянного дерева |
| 54 | |
| 55 | - Идея: усилить палитру **поиском по файлам / символам** (в духе Quick Launch в Visual Studio), чтобы **не обязательно** держать Solution Explorer в PFD для опытных сценариев. |
| 56 | - Не противоречит чеклисту First Run: шаг «попробуй палитру» может быть явным пунктом. |
| 57 | - Контракт команд и хоткеев — [ADR 0013](../adr/0013-command-surface-and-discoverability.md), `command-palette-ux-concept-v1.md`. |
| 58 | |
| 59 | --- |
| 60 | |
| 61 | ## 6. Версионирование сценария онбординга |
| 62 | |
| 63 | - При смене крупной версии IDE или набора шагов — **версия схемы** онбординга; показывать только **новые** пункты повторным пользователям (детали TBD). |
| 64 | - Не ломать раскладку без согласования с ADR 0021 §16 (пресеты и зоны). |
| 65 | |
| 66 | --- |
| 67 | |
| 68 | ## 7. Статус реализации (заглушка) |
| 69 | |
| 70 | | Элемент | Статус | Примечание | |
| 71 | |---------|--------|------------| |
| 72 | | Флаг First Run в настройках | TBD | | |
| 73 | | UI чеклиста в зоне PFD | TBD | Зависит от композитора страниц зоны / текущей разметки | |
| 74 | | Пункты сценария (текст, порядок) | TBD | Согласовать с §19 ADR, копирайт по рамке «Почему/Зачем/Что получу» | |
| 75 | | Связь с видео/справкой §19.1 | TBD | Ссылки из чеклиста | |
| 76 | |
| 77 | --- |
| 78 | |
| 79 | ## 8. Идеи и заметки (пополнять) |
| 80 | |
| 81 | - *(пусто — сюда кратко добавлять новые мысли; при стабилизации — переносить в §7 или отдельные задачи)* |
| 82 | |
| 83 | --- |
| 84 | |
| 85 | ## 9. История обновлений чертежа |
| 86 | |
| 87 | | Дата | Что изменилось | |
| 88 | |------|----------------| |
| 89 | | 2026-04-06 | Создан документ: флаг vs режим, PFD + First Run, палитра и файлы, версионирование, таблица реализации. | |
| 90 | | 2026-04-08 | Добавлена ментальная модель Driver/Navigator (PF/PM) как язык онбординга. | |
| 91 | |