Онбординг и First Run — живой чертёж (v1)¶
Статус: живой чертёж (не ADR). Обновлено: 2026-04-06 — первичная версия: принципы, флаг vs режим, PFD + чеклист, связи с ADR.
Принципы и налог на модель — ADR 0021 §19; палитра и discoverability — ADR 0013; ситуационные чеклисты — ADR 0014. Здесь — идеи, сценарии и план реализации, чтобы не раздувать ADR.
1. Назначение документа¶
- Единое место для нарастающего списка решений по первому запуску, повторному онбордингу после обновлений и связанным UX-идеям (PFD, палитра, зоны, агент).
- Дополняется по мере появления инсайтов; инварианты продукта остаются в ADR.
2. Принципы (согласованы с ADR 0021 §19)¶
- Любой заметный блок онбординга закрывает рамку Почему? / Зачем? / Что мне это даст? (таблица в §19.2 ADR 0021).
- Онбординг снижает onboarding tax — не дублирует длинный текст из спецификации, а ведёт к задачам (открыть решение, понять зону, безопасный шаг агента).
- Не путать с обязательным прохождением «курса»: пользователь должен иметь путь пропустить / вернуть позже, без блокировки работы (детали — при реализации).
2.1 Ментальная модель: Driver/Navigator (PF/PM)¶
Чтобы быстро объяснить модель внимания без авиационного лора, используем мостик из парного программирования:
- Driver (PF / Pilot Flying): “руки на штурвале”. Цель — быстро править и двигаться вперёд. В онбординге это означает: держись лобового/редактора, используй HUD‑подсказки, не утопай в панелях.
- Navigator (PM / Pilot Monitoring): “держит картину и риски”. Цель — проверить, что ты не уходишь в неверном направлении. В онбординге это означает: смотреть в PFD/MFD/EICAS (по пресету) за диагностикой, планом, логами, статусами.
Практическое правило для чеклиста: если ты редактируешь — ты Driver; если ты проверяешь/сверяешь/планируешь — ты Navigator.
3. First Run: флаг, не режим UI¶
| Понятие | Смысл |
|---|---|
| Режим UI (Focus / Balanced / Power / …) | Пресет плотности и семьи из ADR 0010 — постоянная политика раскладки. |
| First Run (рабочее имя) | Отдельное состояние онбординга приложения: флаг(и) в настройках (например «первый запуск не завершён», «версия пройденного сценария»), ортогонально текущему UiMode. |
Зачем разделять: пресет режима не должен переключаться только потому, что человек впервые открыл IDE; и наоборот — завершение чеклиста не обязано менять выбранный Focus/Balanced/Power.
Открытые решения (дополнять по мере проектирования): имена ключей, хранение в %LocalAppData%\CascadeIDE\ vs репозиторий, сброс при major-версии (first_run_schema_version).
4. PFD как место для чеклиста First Run (идея)¶
- Якорь PFD в ADR 0021 — первичный контекст workspace; во время First Run туда логично вывести короткий чеклист (открыть решение, зоны внимания, палитра, уровень безопасности агента — состав уточняется).
- После завершения или отложенного пропуска содержимое PFD возвращается к обычному (дерево, мини-карта задачи, другое по пресету и
[attention_zone_panels]— см. ADR 0021 §2 / §17). - Связь с ADR 0014: First Run — частный случай ситуации «первое знакомство»; не заменяет палитру и не смешивается с полным каталогом команд без контекста.
5. Command Palette (Ctrl+Q) и навигация без постоянного дерева¶
- Идея: усилить палитру поиском по файлам / символам (в духе Quick Launch в Visual Studio), чтобы не обязательно держать Solution Explorer в PFD для опытных сценариев.
- Не противоречит чеклисту First Run: шаг «попробуй палитру» может быть явным пунктом.
- Контракт команд и хоткеев — ADR 0013,
command-palette-ux-concept-v1.md.
6. Версионирование сценария онбординга¶
- При смене крупной версии IDE или набора шагов — версия схемы онбординга; показывать только новые пункты повторным пользователям (детали TBD).
- Не ломать раскладку без согласования с ADR 0021 §16 (пресеты и зоны).
7. Статус реализации (заглушка)¶
| Элемент | Статус | Примечание |
|---|---|---|
| Флаг First Run в настройках | TBD | |
| UI чеклиста в зоне PFD | TBD | Зависит от композитора страниц зоны / текущей разметки |
| Пункты сценария (текст, порядок) | TBD | Согласовать с §19 ADR, копирайт по рамке «Почему/Зачем/Что получу» |
| Связь с видео/справкой §19.1 | TBD | Ссылки из чеклиста |
8. Идеи и заметки (пополнять)¶
- (пусто — сюда кратко добавлять новые мысли; при стабилизации — переносить в §7 или отдельные задачи)
9. История обновлений чертежа¶
| Дата | Что изменилось |
|---|---|
| 2026-04-06 | Создан документ: флаг vs режим, PFD + First Run, палитра и файлы, версионирование, таблица реализации. |
| 2026-04-08 | Добавлена ментальная модель Driver/Navigator (PF/PM) как язык онбординга. |