docs: заложить фундамент проектирования Штурмана

Каркас документации + содержательный фундамент (фаза проектирования, реализация отложена): - vision: видение, позиционирование, границы (вариант B, 2 красные линии) - principles: 13 сквозных принципов (red lines, offline-first, power-safe…) - architecture: тонкое ядро + SDK, planes, lifecycle, песочница, хостинг UI, карта связей + журнал из 6 решений - dev-environment: разработка с Mac (Lima/ARM64, vcan, Vehicle Simulator) - индексы contracts/ и domains/ (+ единый шаблон домена, заделы по камерам) - заготовки glossary, capability-catalog, roadmap Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 19:28:16 +03:00
commit 9e685edd02
11 changed files with 771 additions and 0 deletions
@@ -0,0 +1,20 @@
 # macOS
 .DS_Store
 # Rust
 /target/
 **/target/
 # Python (dev-инструменты / Vehicle Simulator / скрипты)
 __pycache__/
 *.py[cod]
 .venv/
 venv/
 # Редакторы
 .idea/
 .vscode/
 *.swp
 # Локальные dev-артефакты
 *.log
@@ -0,0 +1,37 @@
 # Штурман — документация проекта
 > Открытый русскоязычный программный слой («ОС поверх Linux») для автомобиля:
 > быстрый красивый бортовой интерфейс + голосовой ассистент на русском, который
 > видит данные машины и объясняет их по-человечески. Только чтение CAN, никогда
 > не safety-critical. Лицензия **MIT**.
 **Статус: фаза проектирования.** Реализация сознательно отложена — сначала
 проектируем всё от и до, связно и детально. Этот каталог `docs/` — единственный
 источник правды по дизайну.
 ## Карта документации
 ### Tier 0 — фундамент
 - [vision.md](vision.md) — зачем, что, чем НЕ является, моат, стратегия, границы.
 - [glossary.md](glossary.md) — единый словарь терминов.
 - [principles.md](principles.md) — сквозные принципы и ограничения (правила для всех доменов).
 - [architecture.md](architecture.md) — слои, процессы, шина, **карта связей**.
 ### Tier 1 — сквозные контракты (соединительная ткань)
 - [contracts/](contracts/README.md) — IPC, модель данных, plugin-SDK, безопасность, железо.
 ### Инфраструктура разработки
 - [dev-environment.md](dev-environment.md) — как вести разработку изолированно, с Mac.
 ### Tier 2 — домены
 - [domains/](domains/README.md) — детальные спеки подсистем (A–L) по единому шаблону.
 ### Tier 3 — планирование
 - [capability-catalog.md](capability-catalog.md) — мастер-индекс всех функций (MVP/later + фаза).
 - [roadmap.md](roadmap.md) — фазы реализации с зависимостями.
 ## Как мы работаем
 Сверху вниз, по одному документу за раз: **предложение → правки → фиксация →
 следующий.** Каждый домен потом получит отдельный цикл «спека → план → реализация»
 (но реализация — позже, не сейчас).
@@ -0,0 +1,218 @@
 # Архитектура системы
 > Как устроен Штурман: слои, процессы, шина IPC, изоляция — и **карта связей**
 > между компонентами. Это верхнеуровневый документ: домены (Tier 2) и контракты
 > (Tier 1) ссылаются сюда. Все 6 базовых решений приняты — см. «Журнал решений».
 Статус: **v1 (на ревью).**
 Связано с: [principles.md](principles.md) · [contracts/](contracts/README.md) · [domains/](domains/README.md) · [dev-environment.md](dev-environment.md)
 ---
 ## 1. Главный принцип: тонкое ядро + всё на SDK
 Доверенное **ядро минимально** — только инфраструктура, безопасность и данные.
 Всё прикладное (shell, ассистент, медиа, навигация, телефон) — отдельные процессы
 на **том же SDK**, что и сторонние плагины (first-party получают расширенные
 capabilities). Это делает открытый API не лозунгом, а основой: им пользуемся мы
 сами.
 Ключевое следствие для безопасности: к «опасным» ресурсам (CAN, питание)
 прикасается ровно один привилегированный сервис каждый. **Read-only CAN — не
 правило, а физический факт:** к шине машины прикасается только Vehicle-Data, и в
 нём нет write-кода.
 ---
 ## 2. Слои
 ```
 HARDWARE       RK3588 · экран · CAN/OBD · GPS · mic-массив · power-path · камеры
   │
 LINUX BASE     read-only rootfs + overlay · Wayland · systemd · hardware watchdog
   │
 TRUSTED CORE   Power/Lifecycle · Vehicle-Data (CAN read-only) · Settings/State
 (привилегии)   Security/Perm-Broker · Plugin/App-Host · Connectivity
   │   ──────────────── control plane: D-Bus ────────────────
 SDK            единый API: D-Bus + биндинги (Rust, Python…) + манифест/capabilities
   │
 FIRST-PARTY    Shell/UX-host · Assistant (Py) · Media · Nav · Phone   ← расш. права
 APPS (на SDK)
   │
 PLUGINS (3rd)  плагин · плагин · …                                    ← узкие права
 ```
 Высокополосные данные (аудио/видео/графика) идут **не** через D-Bus, а через
 data-plane — см. §4.
 ---
 ## 3. Компоненты и процессная модель
 Каждый компонент — **отдельный процесс**. Падение одного не роняет остальные
 (изоляция). Раздача привилегий — через Perm-Broker (§7).
 ### Доверенное ядро (привилегированное, минимум)
 | Компонент | Роль | Почему в ядре |
 |-----------|------|---------------|
 | **Power/Lifecycle** | ACC-детект, graceful shutdown, sleep/wake, watchdog | владеет power-GPIO; критично для защиты от corruption |
 | **Vehicle-Data** | читает CAN/OBD, публикует сигналы (VSS-like) на шину | единственный владелец железа CAN → гарантирует read-only |
 | **Settings/State** | центральная конфигурация и состояние, пишет в `/data` | общий источник правды; единственный писатель в `/data`-конфиг |
 | **Security/Perm-Broker** | выдаёт/режет capabilities по манифесту | привратник всех привилегий |
 | **Plugin/App-Host** | запуск, супервизия, песочница апов и плагинов | посредник доступа к шине; владеет sandbox-механизмом |
 | **Connectivity** | обёртка ModemManager/NetworkManager, статус сети | управляет сетевым железом |
 ### First-party апы (отдельные процессы на SDK, расширенные права)
 | Ап | Кратко | Особое |
 |----|--------|--------|
 | **Shell/UX-host** | лаунчер, экраны, тема, driver-distraction | ещё и Wayland-**хост** UI остальных (§8) |
 | **Assistant** | wake→STT→LLM→TTS, контекст машины, память о водителе (`.md`) | на Python; провайдер-агностик LLM |
 | **Media** | аудио, BT A2DP/AVRCP, радио, стриминг | владеет аудио-политикой (с PipeWire) |
 | **Nav** | офлайн-карты, роутинг | богатые поверхности (карта) |
 | **Phone** | BT HFP, контакты, звонки | аудио через PipeWire |
 ### Сторонние плагины
 Тот же SDK, **узкие** capabilities, запускаются и песочатся App-Host'ом, доступ к
 привилегиям — только через Perm-Broker. API расширения — [contracts/plugin-sdk.md](contracts/plugin-sdk.md);
 рантайм/дистрибуция/sandbox — домен F (`domains/f-plugin-host.md`).
 ---
 ## 4. IPC: control plane vs data plane
 Принцип: **D-Bus — для управления и событий, не для медиа-потоков.**
 | Plane | Транспорт | Что несёт |
 |-------|-----------|-----------|
 | **Control** | **D-Bus** | методы, сигналы, свойства: команды, состояние, события, сигналы машины (VSS), интенты ассистента, настройки, выдача capabilities |
 | **Audio/video** | **PipeWire** (+ WirePlumber) | микрофон ассистента, TTS-выход, медиа, BT-аудио, маршрутизация на усилитель |
 | **Graphics** | **Wayland** | поверхности апов, сводимые shell-композитором (Panfrost/Mesa) |
 | **Camera** | **PipeWire / V4L2 (DMABUF)** | видео-источники; самые латентные (задняя камера) — почти прямой путь |
 Нюанс: Vehicle-Data перемалывает сырой высокочастотный CAN **внутри себя** и
 публикует на шину уже digested-сигналы в разумном темпе — шина остаётся лёгкой.
 Камеры спроектированы как **динамический набор 0..N источников** (задняя,
 dashcam-фронтальная, surround), расширяемый плагинами — см. задел в
 [domains/README.md](domains/README.md).
 ---
 ## 5. Карта связей (кто с кем говорит)
 | От | К | Plane | Зачем |
 |----|---|-------|-------|
 | любой ап/плагин | Perm-Broker | D-Bus | проверка capabilities на каждую привилегию |
 | App-Host | апы/плагины | процессы | запуск, супервизия, песочница, рестарт |
 | Assistant | Vehicle-Data | D-Bus | live-контекст машины в промпт |
 | Assistant | Connectivity → сеть | D-Bus/сеть | онлайн RU-LLM (GigaChat/YandexGPT) |
 | Assistant, Media, Phone | PipeWire | audio | микрофон, TTS, музыка, BT-аудио |
 | Nav, Shell | Vehicle-Data | D-Bus | скорость/положение для карты и виджетов |
 | Nav, Media, камеры-виды | Wayland | graphics | богатые поверхности в слот shell |
 | Shell | все апы | D-Bus + Wayland | хостинг UI: декларативные вклады + поверхности |
 | все апы | Settings/State | D-Bus | чтение/запись настроек |
 | Vehicle-Data | CAN/OBD | драйвер | **только чтение** |
 | Power/Lifecycle | все | D-Bus сигналы | ACC-on/off, shutdown, sleep |
 ```mermaid
 graph TD
  Apps["Апы и плагины (SDK, песочница)"]
  Broker["Perm-Broker"]
  AppHost["App-Host"]
  Vehicle["Vehicle-Data (read-only)"]
  Power["Power / Lifecycle"]
  Settings["Settings / State"]
  Conn["Connectivity"]
  PW["PipeWire (audio/video)"]
  WL["Wayland (в Shell)"]
  CAN[("CAN / OBD")]
  Net(("Сеть / RU-LLM"))
  Apps -->|"capabilities"| Broker
  AppHost -.->|"запуск/супервизия"| Apps
  Apps -->|"read сигналы"| Vehicle
  Apps -->|"конфиг"| Settings
  Apps -->|"аудио"| PW
  Apps -->|"поверхности"| WL
  Apps -->|"онлайн"| Conn
  Conn --> Net
  Vehicle ==>|"READ-ONLY"| CAN
  Power -.->|"lifecycle"| AppHost
 ```
 ---
 ## 6. Жизненный цикл и загрузка
 **Кто кого супервизит:**
 - **systemd** — доверенные системные сервисы ядра (+ App-Host и Shell). Рестарт при падении, watchdog.
 - **App-Host** — динамические апы и сторонние плагины (жизненный цикл по манифесту, песочница, своя политика рестарта).
 **Быстрый boot фазами (цель — < 10 c до интерактива):**
 - **Stage 0 (мгновенно):** загрузчик → splash. Низколатентный путь задней камеры/парктроника, если включена задняя.
 - **Stage 1 (~3–5 c):** ядро-минимум (шина + Power + Settings) → **Shell с первым кадром** (home-тайлы кликабельны).
 - **Stage 2 (фоном):** Vehicle-Data, Assistant, Media, Nav прогреваются после того, как UI интерактивен.
 **Завершение:** ACC-off → Power/Lifecycle инициирует graceful shutdown (systemd-таргет): апам сигнал «сохранись», Settings флашится в `/data`, размонтирование, снятие питания через supercap/MCU-копилот. Вместе с read-only rootfs это защита от corruption.
 **Устойчивость:** hardware watchdog + systemd-watchdog; зависший сервис ядра перезапускается, зависшая система — ребутается watchdog'ом.
 ---
 ## 7. Изоляция и разрешения
 Песочница — **defense-in-depth** поверх архитектурных гарантий (даже сбежавший
 плагин не запишет в CAN — write-пути нет).
 - **Механизм:** апы/плагины — в **bubblewrap**-песочнице (namespaces, seccomp, минимальный FS); ядро — **systemd-hardening**. WASM — опциональный тир для лёгких логических плагинов позже.
 - **Модель разрешений:** манифест декларирует capabilities (`vehicle_read:[…]`, `assistant_intents`, `ui_tiles`, `network`, `storage`…). **Perm-Broker — единственная дверь** к привилегиям (модель «порталов» как у Flatpak): плагин не трогает ресурсы напрямую, а просит брокера.
 - **Грант:** first-party — авто; сторонние — показываем запрашиваемые capabilities при установке, пользователь подтверждает.
 Детали модели разрешений и приватности — [contracts/security-privacy.md](contracts/security-privacy.md).
 ---
 ## 8. Хостинг UI в shell (гибрид / слоты)
 Shell — Wayland-хост; апы/плагины — отдельные песочные процессы. Их UI попадает на
 экран двумя путями:
 - **Декларативные вклады** (данные/описание, **не код**) для частого/лёгкого:
  home-тайлы, настройки, простые экраны плагинов, карточки ассистента. Рендерит
  **сам shell** своими Slint-компонентами → единый стиль, безопасность (чужой код
  в процесс shell не пускаем).
 - **Wayland-поверхности** для богатых апов: нав-карта, медиа, камеры, GPU-тяжёлое.
  Ап рисует у себя и отдаёт shell готовую поверхность.
 **Модель слотов:** shell задаёт слоты (грид home, полноэкранная зона, оверлей,
 статус-бар); ап вкладывает либо декларативный элемент, либо поверхность. Так
 консистентность UX (наш дифференциатор) сочетается с мощью и ложится на песочницу.
 ---
 ## 9. Что вынесено в другие документы (связи)
 - **Интерфейсы шины** (имена сервисов, методы, схемы) → [contracts/ipc.md](contracts/ipc.md).
 - **Модель сигналов машины** (VSS-таксономия) → [contracts/data-model.md](contracts/data-model.md).
 - **API расширения** (манифест, capability-модель, точки расширения) → [contracts/plugin-sdk.md](contracts/plugin-sdk.md).
 - **Разрешения и приватность** (детали брокера, 152-ФЗ) → [contracts/security-privacy.md](contracts/security-privacy.md).
 - **Железо и HAL/board-support** (питание, периферия, портирование) → [contracts/hardware.md](contracts/hardware.md).
 - **Камеры как 0..N источников, dashcam/surround; парктроники** → [domains/README.md](domains/README.md) (заделы) → домены J/K.
 - **Аудио-арбитраж (ducking/приоритеты)** → домены Media/Assistant (политика поверх PipeWire).
 - **Ранний путь задней камеры (Stage 0)** → роадмап (объём работ) + домен J.
 ---
 ## Журнал решений (architecture)
 | # | Решение | Выбор | Дата |
 |---|---------|-------|------|
 | 1 | Граница ядра | **Тонкое ядро + всё на SDK** | 2026-06-16 |
 | 2 | Состав компонентов | Мин. доверенное ядро (6 сервисов) + first-party апы на SDK + плагины; Connectivity в ядре | 2026-06-16 |
 | 3 | Control vs data plane | D-Bus (control) + PipeWire (audio/video) + Wayland (graphics) + V4L2/DMABUF (камеры) | 2026-06-16 |
 | 4 | Lifecycle/boot | systemd (ядро) ↔ App-Host (апы/плагины); фазовый boot; graceful shutdown по ACC | 2026-06-16 |
 | 5 | Песочница | bubblewrap + Perm-Broker (порталы), systemd-hardening ядра; WASM — тир позже | 2026-06-16 |
 | 6 | Хостинг UI | Гибрид/слоты: декларативные вклады (shell рендерит) + Wayland-поверхности | 2026-06-16 |
@@ -0,0 +1,12 @@
 # Каталог возможностей (мастер-индекс)
 > Единый список **всех** функций платформы со сквозными тегами. Заполняется по
 > мере проработки доменов (Tier 2); служит источником для [roadmap.md](roadmap.md).
 Статус: **заготовка**. Колонки фиксированы:
 | ID | Функция | Домен | MVP / later | Фаза | Зависит от | Статус проработки |
 |----|---------|-------|-------------|------|------------|-------------------|
 | — | _TODO: наполняется по ходу проработки доменов_ | — | — | — | — | — |
 > Каждая строка домена-спеки должна иметь соответствие здесь — это сводный реестр.
@@ -0,0 +1,17 @@
 # Контракты (Tier 1) — соединительная ткань
 > Сквозные интерфейсы, которыми домены связаны друг с другом. **«Связи» проекта
 > живут здесь.** Каждый контракт — отдельный документ; создаём по мере наполнения.
 Статус: **индекс**. Документы наполняем после фундамента (architecture + principles).
 | Документ | Назначение |
 |----------|------------|
 | `ipc.md` | D-Bus сервисы, интерфейсы, схемы сообщений: кто что публикует/слушает. |
 | `data-model.md` | VSS-подобная таксономия сигналов машины + общие типы данных. |
 | `plugin-sdk.md` | API расширения: манифест, capability-модель, точки расширения (экраны, тайлы, интенты, доступ к данным). *Рантайм плагинов — домен F.* |
 | `security-privacy.md` | Sandboxing плагинов, модель разрешений, обработка данных, 152-ФЗ. |
 | `hardware.md` | Целевой таргет (RK3588), топология питания, периферия + **HAL/board-support API** для портирования на другое железо/авто. |
 > Важный нюанс: **plugin-SDK** (API, тут) и **домен F «Plugin host»** (рантайм,
 > sandbox, дистрибуция — в [domains/](../domains/README.md)) — разные вещи, ссылаются друг на друга.
@@ -0,0 +1,132 @@
 # Среда разработки
 > Как вести разработку Штурмана корректно и изолированно — не выходя с Mac,
 > ничего не ломая, со спокойным тестированием подсистем без реального железа.
 Статус: **v1 (на ревью).**
 Связано с: [architecture.md](architecture.md) · [principles.md](principles.md) (#13) · [contracts/hardware.md](contracts/hardware.md)
 ---
 ## Цель
 - Вся разработка и тестирование с текущего **Mac**.
 - **Изоляция:** эксперименты не трогают хост.
 - **Безопасное тестирование** подсистем без машины.
 ## Хост и что это даёт
 **Apple M4 (ARM64), 10 ядер, 16 ГБ, macOS 26.5.**
 - **ARM64-хост ↔ ARM64-таргет (RK3588).** Linux в ARM64-VM крутится нативно-быстро
  через Apple Virtualization (без эмуляции). Бинари, собранные в VM, уже целевой
  архитектуры.
 - **QEMU-эмуляция** нужна только если захотим эмулировать сами периферии RK3588 —
  редкий случай, не базовый поток.
 - **16 ГБ RAM — единственное ограничение.** VM держим лёгкой; локальную офлайн-LLM
  по умолчанию **мокаем**, реальную квантованную модель гоняем точечно (закрыв
  лишнее) или уже на железке.
 ## Изоляция «ничего не сломать» — бесплатно
 Весь Linux / CAN / systemd живёт **в VM**. Хост-Mac держит только редактор,
 нативный Slint и менеджер VM. Сломал что-то в стеке — **сбросил VM, хост цел**.
 ---
 ## Четыре слоя
 ```
 L1  Mac host        редактор · git · Rust-тулчейн · НАТИВНЫЙ Slint (быстрый UI) · justfile · Lima
        │
 L2  Linux dev-VM    systemd · D-Bus · SocketCAN(vcan) · PipeWire · Wayland(cage)
    (Lima, vz,      ← интегрированный стек; сервисы = systemd-юниты + bubblewrap (как в проде)
     ARM64)
        │
 L3  Симуляция       Vehicle Simulator (vcan) · моки LLM/STT/TTS · фейк-GPS · мок-сеть
        │
 L4  Реальный RK3588  (позже) сборка образа → флеш → путь «VM → железка»
 ```
 ## Стек инструментов
 | Задача | Инструмент | Зачем |
 |--------|-----------|-------|
 | Linux dev-VM | **Lima** (vz-backend) | нативная ARM64-виртуализация, open-source, scriptable YAML |
 | Итерация UI | **нативный Slint на macOS** + `cage`/`weston` в VM | гибрид: быстрый дизайн-цикл + проверка реального Wayland |
 | Виртуальный CAN | **SocketCAN `vcan`** (в VM) | тест Vehicle-Data без железа |
 | Симуляция OBD | **ELM327-emulator** + `python-can` + `can-utils` | OBD-II PID и DTC без авто |
 | Сборка Rust | **в VM** (та же арка) + кросс `aarch64-unknown-linux-gnu` с хоста | target-arch бинари |
 | Аудио | **PipeWire** в VM | тест аудио-пайплайна |
 | Изоляция сервисов | **systemd-юниты + bubblewrap** | dev зеркалит прод, а не Docker-огород |
 | Оркестрация | **`justfile`** | единые dev-команды (`just vm-up`, `just sim`, `just test`…) |
 | CI | **GitHub Actions, ARM64-Linux** | совпадает с таргетом |
 | License-check | **`cargo-deny`** | принцип #12 (без AGPL-заразы) |
 ---
 ## Vehicle Simulator (first-class актив)
 «Виртуальная машина» — то, чем тестируется killer-фича без авто. Реализует
 принцип #13. Умеет:
 - писать реалистичные кадры в **vcan**;
 - отвечать на **OBD-II PID-запросы** (ELM327-стиль и raw CAN);
 - **инжектить/чистить DTC** (set/clear) — для теста расшифровки и объяснения;
 - проигрывать реальные **CAN-дампы** (`candump` → `canplayer`);
 - гонять сценарии: холостой / езда / неисправность.
 Строим тонко поверх `can-utils` (`cangen`/`candump`/`canplayer`), `python-can`,
 ELM327-emulator. **Эталонный тест killer-фичи:** симулятор инжектит `P0420` →
 ассистент через Vehicle-Data → контекст → объясняет по-русски.
 ## Моки
 - **LLM** — заглушка (canned-ответы/echo) или крошечная локальная модель.
 - **STT** — обход голоса вводом текста; **TTS** — тихий/лог-режим.
 - **GPS** — NMEA-реплей; **модем/сеть** — управляемые состояния (для теста offline-first).
 ---
 ## Воспроизводимость
 - **Lima-шаблон** (`lima.yaml`): Ubuntu ARM64, модули (`vcan`), пакеты (systemd,
  dbus, pipewire, cage, can-utils, rust, python).
 - **Provisioning-скрипт** + **`justfile`** с целями для подъёма/симуляции/тестов.
 - Минимальный порог входа для контрибьюторов.
 - **Nix** — опция *позже* для эталонно-пиннутого тулчейна (power-users), не сейчас.
 ## CI
 GitHub Actions на ARM64-Linux-раннерах:
 - **lint** (clippy + rustfmt), **unit**, **интеграция** (vcan + симулятор + моки,
  сервисы на шине), **license** (`cargo-deny`), позже — **сборка образа**.
 - *Если ARM64-раннеры вне бесплатного тира — фолбэк: x86 + кросс или self-hosted.*
 ## Пирамида тестов
 - **Unit** — на хосте/в VM, по крейтам/модулям.
 - **Интеграция** — сервисы на шине против Vehicle Simulator и моков. Здесь
  тестируется контекст машины без авто.
 - **E2E** — полный стек в VM: boot < 10 c, graceful shutdown по ACC, реверс→камера,
  поток «почему горит чек» (`P0420`), офлайн-фолбэк при выключенной мок-сети.
 - **HW-in-the-loop** — на реальном RK3588 (позже).
 ---
 ## Связи
 - Процессная модель и planes, которые здесь воспроизводим, — [architecture.md](architecture.md).
 - Тестируемость-без-машины как принцип — [principles.md](principles.md) #13.
 - Путь «VM → железка», флеш, board support — [contracts/hardware.md](contracts/hardware.md).
 - Vehicle Simulator кормит домен — [domains/](domains/README.md) (E: Vehicle-Data).
 ## Журнал решений (dev-environment)
 | Решение | Выбор | Дата |
 |---------|-------|------|
 | Linux-окружение | Lima (vz-backend), ARM64, нативная виртуализация | 2026-06-16 |
 | Итерация UI | гибрид: нативный Slint на macOS + `cage` в VM | 2026-06-16 |
 | Изоляция сервисов в dev | systemd-юниты + bubblewrap (зеркало прода) | 2026-06-16 |
 | Воспроизводимость | Lima-шаблон + provisioning + `justfile` (Nix — позже) | 2026-06-16 |
 | CI | GitHub Actions, ARM64-Linux | 2026-06-16 |
@@ -0,0 +1,47 @@
 # Домены (Tier 2)
 > Детальные спеки подсистем. Каждый домен — отдельный документ по **единому
 > шаблону** (ниже). Файлы создаём по мере наполнения; здесь — карта и план.
 Статус: **индекс + шаблон**. Содержательные файлы доменов появляются по ходу работы.
 ## Единый шаблон домена
 1. **Назначение и границы** — что делает, чего НЕ делает.
 2. **Функции** — таблица: `функция | MVP / later | зависит от | фаза`.
 3. **Данные и интерфейсы** — что домен публикует/потребляет на шине (ссылки на `../contracts/`).
 4. **Зависимости** — ссылки на другие домены и контракты (← здесь «связи»).
 5. **Открытые вопросы / решения.**
 ## Карта доменов
 | # | Домен | Файл | Кратко |
 |---|-------|------|--------|
 | A | Базовая система / OS | `a-base-system.md` | образ, read-only rootfs, boot, watchdog, OTA, board support |
 | B | Питание и жизненный цикл | `b-power-lifecycle.md` | ACC, graceful shutdown, sleep, защита eMMC |
 | C | Shell / UX / лаунчер | `c-shell-ux.md` | тайлы, темы день/ночь, профили, driver-distraction, ввод с **мультируля**, мультидисплей |
 | D | Голосовой ассистент | `d-assistant.md` | wake→STT→LLM→TTS, vehicle-context, **память о водителе (`.md`)**, офлайн-фолбэк, провайдер-агностик |
 | E | Vehicle Data (OBD/CAN, read-only) | `e-vehicle-data.md` | PIDs, DTC + расшифровка, поездки, расход, VSS-модель |
 | F | Plugin host & экосистема | `f-plugin-host.md` | загрузка/sandbox/lifecycle плагинов, дистрибуция, dev-tools (API — в `../contracts/plugin-sdk.md`) |
 | G | Связь / телефон | `g-connectivity-phone.md` | BT HFP, модем/LTE, WiFi/hotspot, проекция телефона |
 | H | Медиа / аудио | `h-media-audio.md` | **вся стандартная мультимедиа**: локальное аудио, BT A2DP/AVRCP, радио, стриминг |
 | I | Навигация | `i-navigation.md` | офлайн-карты OSM, роутинг, POI, связка с ассистентом |
 | J | Камеры / видео | `j-cameras-video.md` | задняя камера, парктроник-оверлей, dashcam |
 | K | Датчики / периферия | `k-sensors-peripherals.md` | GPS, IMU, кнопки руля (чтение), TPMS, климат-дисплей (чтение) |
 | L | Облако / компаньон | `l-cloud-companion.md` | мобильное приложение, синхронизация, бэкап, OTA-канал, телеметрия (opt-in) |
 > Порядок наполнения определим в [roadmap.md](../roadmap.md); технически — после контрактов.
 ## Заделы (сиды для будущих доменов)
 Идеи на будущее, пойманные по ходу проектирования; раскрываются при наполнении домена.
 - **J (Камеры).** Камеры — **динамический набор 0..N источников видео**, не одна задняя.
  Задел: подключение доп. камер — фронтальная для **видеорегистратора (dashcam)**,
  камеры **кругового обзора (360°/surround)** и т.п. Набор источников и «виды»
  (например surround-композит) — расширяемые, плагин может добавить источник/вид.
 - **K (Датчики).** **Парктроники** и подобные датчики ближнего действия — как источник
  *данных* (чтение с CAN через Vehicle-Data или отдельный датчик) для оверлеев/
  предупреждений поверх видео-вида.
 - **Архитектурная связь:** видео-источники идут через data-plane (PipeWire/V4L2);
  задняя/парктроник-вид требуют низколатентного раннего пути (см. Решение №3 и lifecycle).
@@ -0,0 +1,27 @@
 # Глоссарий
 > Единый словарь Штурмана: один термин — одна строка. Пополняем по мере того как
 > термины появляются в других документах, чтобы говорить на одном языке.
 Статус: **заготовка** (TODO наполнить определения).
 | Термин | Определение |
 |--------|-------------|
 | OBD-II | TODO |
 | PID | TODO |
 | DTC | TODO |
 | CAN / SocketCAN / vcan | TODO |
 | ELM327 | TODO |
 | VSS (Vehicle Signal Specification) | TODO |
 | ECU | TODO |
 | AUTOSAR | TODO |
 | AGL (Automotive Grade Linux) | TODO |
 | D-Bus | TODO |
 | Capability (манифест плагина) | TODO |
 | Intent (ассистента) | TODO |
 | Wake-word / VAD / STT / TTS | TODO |
 | Driver memory (`.md` контекст водителя) | TODO |
 | ACC (сигнал зажигания) | TODO |
 | HAL / board support | TODO |
 > TODO: дополнить список и заполнить определения по ходу проработки документов.
@@ -0,0 +1,75 @@
 # Принципы и сквозные ограничения
 > Правила, которым подчиняется **каждый** домен. Если домен их нарушает — это баг
 > дизайна, а не исключение. Спеки доменов ссылаются сюда.
 Статус: **v1 (на ревью).**
 Связано с: [architecture.md](architecture.md) · [dev-environment.md](dev-environment.md) · [contracts/security-privacy.md](contracts/security-privacy.md)
 Формат: **принцип → почему → как держим/проверяем.**
 ---
 ## Красные линии (нерушимы)
 ### 1. Никогда не safety-critical
 - **Почему:** безопасность людей, юридическая ответственность, сертификационная яма функциональной безопасности.
 - **Как держим:** нет интеграций с управляющими ECU; в системе нет actuator-путей; каждая фича проходит ревью «не управляет ли узлом».
 ### 2. CAN только на чтение
 - **Почему:** тот же риск + юридическая чистота. Это то, что делает проект подъёмным для малой команды.
 - **Как держим:** в Vehicle-Data нет write-кода; он единственный владелец CAN; на шине D-Bus нет метода записи в CAN; в SDK нет capability вида `can_write` — её просто не существует.
 ---
 ## Сквозные принципы
 ### 3. Offline-first
 - **Почему:** салон часто без сети (тоннели, глушь); ассистент не должен умолкать, навигация — теряться.
 - **Как держим:** STT/TTS локальны; у ассистента офлайн-LLM фолбэк; карты офлайн; ключевые функции **деградируют, а не падают** без сети.
 ### 4. Изоляция и graceful degradation
 - **Почему:** устойчивость; падение одного компонента не должно ронять систему.
 - **Как держим:** процесс-на-компонент; App-Host рестартит упавшее; ап переживает недоступность зависимости (показывает «нет данных», а не крэшит).
 ### 5. Power-safe by design
 - **Почему:** машина рубит питание резко → corruption памяти (так умирают одноплатники).
 - **Как держим:** read-only rootfs + overlay **с дня 1**; graceful shutdown по ACC; запись только в журналируемый `/data`.
 ### 6. Driver-distraction discipline
 - **Почему:** безопасность вождения (и потенциальная регуляторика).
 - **Как держим:** на скорости выше порога — упрощённый UI, приоритет голосу, блокировка сложных взаимодействий; правило едино для всех апов через shell/SDK. Конкретика — в домене Shell.
 ### 7. Приватность / 152-ФЗ
 - **Почему:** закон + доверие пользователя.
 - **Как держим:** обработка локальна по умолчанию (голос → текст локально); в облако уходит **только текст запроса** при онлайн-LLM; RU-провайдеры, данные в РФ; телеметрия **opt-in**, по умолчанию выключена; память о водителе (`.md`) — локальная, не уходит в облако без явного согласия.
 ### 8. Provider-agnostic
 - **Почему:** не привязываемся к одному вендору; ИИ — коммодити; устойчивость к отвалу провайдера.
 - **Как держим:** LLM за единым интерфейсом-бэкендом с авто-fallback; то же для STT/TTS/карт, где разумно.
 ### 9. Расширяемость через API, не через правку ядра
 - **Почему:** суть платформы; даже свои апы — на SDK.
 - **Как держим:** ядро тонкое; новая функция = ап/плагин. Если «для фичи нужно лезть в ядро» — это сигнал, что **API недостаточен**: чиним API, а не хардкодим в ядро.
 ### 10. RU-first, i18n-ready
 - **Почему:** русский — наш моат и приоритет №1; но платформа (и автопроизводители) не должны быть заперты в одном языке.
 - **Как держим:** русский — первоклассный и дефолтный; **строки и локаль не хардкодим** — инфраструктура i18n заложена изначально.
 - ⚠️ *На подтверждение: оставляем i18n-ready, а не строго RU-only?*
 ### 11. Отзывчивость (no-lag) — требование, не пожелание
 - **Почему:** медленный лагучий UI — главный изъян китайских блоков и наш ключевой дифференциатор.
 - **Как держим:** бюджет на отклик (цель: мгновенный UI, boot < 10 c до интерактива); тяжёлое — фоном/лениво; не блокируем UI-поток. Регрессии производительности — это баги, а не «потом».
 ### 12. Лицензионная гигиена (MIT)
 - **Почему:** adoption, без AGPL-боли.
 - **Как держим:** зависимости — MIT/Apache/BSD-совместимые; заражающий дистрибуцию copyleft (GPL/AGPL) избегаем или изолируем как отдельный процесс; проверка лицензий в CI.
 ### 13. Разрабатываемо и тестируемо без машины
 - **Почему:** итерации малой командой с Mac; нельзя зависеть от наличия авто под рукой.
 - **Как держим:** симуляция CAN/OBD (vcan + дампы), моки LLM/STT/TTS; **каждый домен поставляет симулятор/мок**. Детали — [dev-environment.md](dev-environment.md).
 ---
 > Изменения этого списка — осознанные: принцип влияет на все домены, поэтому
 > правка здесь = ревизия их всех.
@@ -0,0 +1,18 @@
 # Роадмапа
 > Фазы реализации лестницей: каждая ступень — законченный, демонстрируемый
 > артефакт. Порядок диктуется зависимостями из [architecture.md](architecture.md)
 > и [capability-catalog.md](capability-catalog.md).
 Статус: **заготовка** (наполняем в конце, когда домены и связи ясны).
 ## Черновая лестница (из vision — уточним и развернём)
 - **v0 — Shell.** Быстрый красивый лаунчер на RK3588, день/ночь, быстрый boot.
 - **v1 — Ассистент онлайн.** wake-word → STT → RU-LLM (GigaChat/YandexGPT) → TTS.
 - **v2 — OBD read-only + контекст машины.** «Прочитай ошибки / что значит лампочка». **Killer-демо.**
 - **v3 — Офлайн-фолбэк + Plugin API.** Локальная модель без сети + расширяемость.
 - **v4 — Навигация (OSM) + образ + документированный ретрофит.** Первый «продукт».
 > TODO: развернуть каждую фазу в задачи с явными зависимостями после проработки
 > доменов. Учесть, что dev-environment проектируется рано (до v0-реализации).
@@ -0,0 +1,168 @@
 # Штурман — видение и позиционирование
 > Статус: черновик v0.2 (на ревью). Канонический рассказ о смысле проекта.
 > Технические решения — в [architecture.md](architecture.md) и доменах; здесь — зачем и что.
 ## В одном абзаце
 Штурман — открытый (MIT) русскоязычный программный слой для автомобиля. Он
 превращает дешёвый головной блок или одноплатник в быстрый, красивый и
 расширяемый бортовой интерфейс с голосовым ассистентом на русском — ассистентом,
 который не просто болтает, а **видит данные твоей машины и объясняет их
 по-человечески** (общение в духе Grok в Tesla). По смыслу имени штурман —
 со-пилот, который ведёт по маршруту и держит руку на пульсе машины: проект делает
 ровно это. По сути это **операционная система для автомобиля на базе Linux** (экран,
 мультируль и т.д.) со всей стандартной мультимедией и потенциалом расширений.
 Ничего, что управляет двигателем, тормозами или другими критичными узлами.
 ## Проблема, из которой всё растёт
 - **Фрагментация «мозгов».** Софт и электроника машин различаются чуть ли не под
  каждый рестайлинг даже у одного производителя. Боль OEM, владельцев и особенно
  механиков.
 - **Афтемаркет.** Миллионы машин без нормального экрана или с дешёвым китайским
  Android-блоком: медленным, лагучим, уродливым, без кастомизации, с языковым
  барьером и плохой поддержкой.
 - **Взрыв голосовых ИИ в машинах.** Mercedes (ChatGPT → Gemini-агент), Tesla
  (Grok), VW (IDA на ChatGPT), Hyundai (Naver), BMW в Китае (Alibaba/DeepSeek),
  китайцы агрессивнее всех. Но всё — проприетарное, западное или китайское.
  **Ни одного — ни в российском авто, ни в открытом коде.**
 - **Российский контекст.** После 2022 АвтоВАЗ потерял западных поставщиков и
  просел по электронике (ЭБУ двигателя, ABS, ESP, приборки). Латается китайским
  и отечественным, но язык, цена и поддержка китайских решений — заноза. Нужна
  локализованная, поддерживаемая альтернатива — её нет.
 ## Пустая клетка
 Наложив всё друг на друга, видим незанятое место: **открытый, русскоязычный,
 поддерживаемый, кастомизируемый** слой для авто. Пусто не случайно, а структурно:
 на уровне OEM всё закрыто стандартами (AUTOSAR — 20-летний отраслевой стандарт
 для ECU с сотнями компаний-членов); полноценные открытые автомобильные ОС
 существуют, но тяжёлые и заточены под автопроизводителей (Automotive Grade Linux);
 а safety-critical упирается в сертификацию функциональной безопасности и
 ответственность. Клетка пуста не потому что её легко занять, а потому что
 **некому — кроме того, кто сидит ровно на этом пересечении.**
 ## Что Штурман делает на самом деле
 1. **Интерфейс.** Быстрый, красивый, не-лагучий головной экран: навигация, медиа,
   телефон, ассистент, экран машины, настройки. Прямой ответ на главный изъян
   китайских блоков. Дифференциация — в качестве опыта, не в наличии экрана.
 2. **Голосовой ассистент на русском.** Лаконично интегрирован в интерфейс (как в
   Tesla). Пайплайн гибридный: распознавание и синтез речи — локально (Vosk,
   Silero); «мозг» — через сменный бэкенд. Онлайн — российские LLM (GigaChat,
   YandexGPT; работают в РФ, 152-ФЗ, данные в России). Офлайн — небольшая
   локальная модель на устройстве, чтобы ассистент не умолкал в тоннеле или без
   сети. Бэкенд провайдер-независим: один отвалился — автоматически переключились
   на другой. Ассистент **запоминает информацию о водителе в контекстные `.md`
   файлы** — персонализация со временем.
 3. **Контекст машины (главное).** Через OBD-II/CAN (**строго на чтение**) Штурман
   видит реальные данные: скорость, обороты, температуры, напряжение бортсети,
   активные ошибки — и подаёт их ассистенту в контекст. На «почему горит чек?» он
   читает реальный код ошибки из ЭТОЙ машины и объясняет простым русским. Этого
   нет ни у кого в связке «открытое + русское» — мост к боли механиков и
   владельцев.
 Поверх всего — **открытый расширяемый API**: сообщество и интеграторы добавляют
 плагины, экраны, интенты ассистента, не трогая ядро.
 ## Чем Штурман сознательно НЕ является (и почему)
 Границы держат проект жизнеспособным и юридически чистым.
 - **Никогда не пишет в шину и не управляет критичными узлами. Только чтение.**
  Архитектурная гарантия, не настройка: write-пути в системе просто нет. Так
  снимается вся сертификационная и юридическая яма функциональной безопасности —
  единственное, что делает проект подъёмным для маленькой команды.
 - **Не строит свою ОС** — живёт поверх обычного Linux. Ядро решено; ценность — в
  слое опыта и локализации над ним.
 - **Не претендует на индустриальный стандарт** — это место AUTOSAR; ценность
  стандарта определяется принятием, которым владеют консорциумы, а не разработчик.
 - **Не обещает работать на любом заводском железе.** Универсальность — ловушка
  масштаба AGL (тачскрины, тюнеры, камеры, питание у всех свои). Вместо этого —
  **один хорошо выбранный таргет, доведённый до конца.** НО заложен грамотный
  **API для автопроизводителей/автолюбителей**, чтобы адаптировать всё под
  конкретное железо/авто. Портируемость — через API силами других, а не
  «универсально из коробки». Это разница между соло-проектом, который заканчивается,
  и платформой, которая не заканчивается.
 ## Где настоящий моат
 ИИ сам по себе — **не** преимущество: ассистенты коммодитизируются, китайские
 блоки получат их быстро. Защищённость — в трудноповторимом сочетании: **русская
 локализация** (язык + RU-LLM-провайдеры + 152-ФЗ) + **открытость** (MIT, без
 AGPL-боли) + **трюк с контекстом машины** + **по-настоящему хороший UX** + **фокус
 на нише афтемаркета/ретрофита**. Западное проприетарное не зайдёт на этот рынок,
 китайское не станет локализовать и открывать, OEM строят закрыто.
 ## Как это устроено технически (кратко; детали — в [architecture.md](architecture.md))
 Голый Linux на одноплатнике класса RK3588 (хватает на красивый UI и локальную
 небольшую модель, приличная mainline-поддержка). Независимые процессы общаются
 через шину **D-Bus**: интерфейс, ассистент, сервис данных машины, питание, связь.
 Падение ассистента не роняет UI; плагины цепляются к той же шине. Два решения —
 **с первого дня**: (1) read-only rootfs с записью только в отдельный раздел
 (резкое обесточивание корраптит память — так умирают одноплатники от forced
 power-off); (2) управляемое питание и graceful shutdown по сигналу зажигания. Без
 них красивый интерфейс однажды просто не загрузится. Навигация, медиа, телефон —
 наращиваются слоями.
 ## Стратегия: открытость как фундамент, продажа как апсайд
 Проект **открыт в любом случае**; его ценность не зависит от продажи. Открытый
 Штурман сам по себе — актив: репутация, доверие, сообщество, портфолио, «построил
 настоящее и довёл до конца». Коммерция — апсайд сверху, а не точка, без которой
 проект мёртв: сервис интеграции/локализации/поддержки для афтемаркета или Tier-1;
 демо для АвтоВАЗа строго на несейфти-companion-слое; своя «коробка» для ретрофита.
 Не выйдет продать — остаётся сильный открытый проект; выйдет — ещё и бизнес.
 **Проигрышного исхода нет.**
 ## Для кого
 - **Энтузиаст-ретрофитчик** — красивый, быстрый, кастомный блок вместо китайского.
 - **Механик / владелец** — ассистент впервые объясняет ошибки и поведение машины
  по-русски на основе её реальных данных.
 - **(Апсайд) OEM / Tier-1 / афтемаркет-интеграторы и автопроизводители в РФ** —
  локализованная открытая альтернатива без зависимости от китайцев и без языкового
  барьера.
 ## Как проект растёт (лестница; детали — в [roadmap.md](roadmap.md))
 Каждая ступень — законченная, демонстрируемая вещь: интерфейс → ассистент онлайн →
 контекст машины (**killer-демо**) → офлайн + Plugin API (маховик сообщества) →
 навигация + образ + документированный ретрофит (первый «продукт»). Остановиться
 можно на любой ступени — каждая самоценна.
 ## Суть
 Поставить флаг там, где пусто: первый открытый, русскоязычный, по-настоящему
 хороший бортовой companion. Глубокий настолько, чтобы его уважали инженеры
 (Linux-bring-up, голосовой пайплайн, работа с CAN, архитектура из независимых
 сервисов), красивый и осязаемый настолько, чтобы хотелось показывать, и
 ограниченный в скоупе настолько, чтобы реально закончить. А повезёт — фундамент
 для бизнеса.
 ---
 ## Рамки — решено (2026-06-15)
 Выбран **вариант B**: Штурман — это полноценная расширяемая платформа («ОС
 поверх Linux» в широком смысле), и мы сознательно шире, чем §2 спеки. При этом
 две красные линии остаются абсолютными.
 **Нерушимые красные линии (не обсуждаются — безопасность + 152-ФЗ/юр. чистота):**
 - **Никогда не safety-critical** — не управляем двигателем, тормозами, ABS/ESP,
  рулём, подушками.
 - **CAN только на чтение** — никакой записи в шину, никаких actuator-команд.
  Write-пути нет в системе в принципе (архитектурная гарантия).
 **Открыто к пересмотру (закладываем в каталог как возможное; решаем по фазам):**
 - **Несколько HW-таргетов.** Спека требовала один (RK3588). Для платформенной
  амбиции мульти-железо допустимо — но не ценой bring-up-боли на старте: первый
  таргет всё равно один, остальное — позже (через HAL/board-support API).
 - **Глубже стокового Linux.** Допускаем собственный образ/ядро/дистрибутив и
  более глубокую системную интеграцию, если это реально нужно платформе. Не
  самоцель — каждое углубление обосновывается потребностью.
 > §2 исходной спеки (жёсткие «НЕ полноценная ОС» и «один таргет») этим решением
 > переопределяется. Две safety/legal-линии из §2 остаются в силе.