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>

.gitignore

@@ -0,0 +1,20 @@
+# macOS
+.DS_Store
+
+# Rust
+/target/
+**/target/
+
+# Python (dev-инструменты / Vehicle Simulator / скрипты)
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+
+# Редакторы
+.idea/
+.vscode/
+*.swp
+
+# Локальные dev-артефакты
+*.log

docs/README.md

@@ -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) — фазы реализации с зависимостями.
+
+## Как мы работаем
+
+Сверху вниз, по одному документу за раз: **предложение → правки → фиксация →
+следующий.** Каждый домен потом получит отдельный цикл «спека → план → реализация»
+(но реализация — позже, не сейчас).

docs/architecture.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 |

docs/capability-catalog.md

@@ -0,0 +1,12 @@
+# Каталог возможностей (мастер-индекс)
+
+> Единый список **всех** функций платформы со сквозными тегами. Заполняется по
+> мере проработки доменов (Tier 2); служит источником для [roadmap.md](roadmap.md).
+
+Статус: **заготовка**. Колонки фиксированы:
+
+| ID | Функция | Домен | MVP / later | Фаза | Зависит от | Статус проработки |
+|----|---------|-------|-------------|------|------------|-------------------|
+| — | _TODO: наполняется по ходу проработки доменов_ | — | — | — | — | — |
+
+> Каждая строка домена-спеки должна иметь соответствие здесь — это сводный реестр.

docs/contracts/README.md

@@ -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)) — разные вещи, ссылаются друг на друга.

docs/dev-environment.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 |

docs/domains/README.md

@@ -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).

docs/glossary.md

@@ -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: дополнить список и заполнить определения по ходу проработки документов.

docs/principles.md

@@ -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).
+
+---
+
+> Изменения этого списка — осознанные: принцип влияет на все домены, поэтому
+> правка здесь = ревизия их всех.

docs/roadmap.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-реализации).

docs/vision.md

@@ -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 остаются в силе.