diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a3f44e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# templates
+
+Общий репозиторий переносимых библиотек. Одно место, откуда прошивки и
+инструменты забирают код, который не привязан к плате и повторяется из
+проекта в проект.
+
+Правило отбора одно: **ядро не знает о платформе**. Ни HAL, ни ОС, ни
+динамической памяти, ни глобального состояния — всё аппаратное живёт в порте,
+который приносит с собой проект. Библиотеки не зависят друг от друга и
+подключаются поодиночке.
+
+```
+templates/
+  c/        библиотеки на C99: заголовок, реализация, README, где есть — порт и тесты
+  python/   модули на чистом Python 3.9+, только stdlib
+```
+
+## Что лежит
+
+### C
+
+| Библиотека | Что делает | Зависимости | Что нужно от платформы |
+|---|---|---|---|
+| [`c/st7789`](c/st7789) | TFT ST7789V по SPI, RGB565, текст без кадрового буфера | `stdint.h` | SPI-запись, линия DC, задержка |
+| [`c/keypad`](c/keypad) | шесть кнопок: антидребезг, автоповтор, удержание, очередь событий | `stdint.h` | чтение уровня кнопки, время в мс |
+| [`c/menu`](c/menu) | экранное меню: стек экранов, курсор, прокрутка, тема | `stdint.h` | заливка прямоугольника, вывод строки |
+| [`c/eeprom-ft24c256`](c/eeprom-ft24c256) | EEPROM 24Cxx по I²C с нарезкой записи по страницам | `stdint.h` | две I²C-транзакции, задержка |
+| [`c/can-sensor`](c/can-sensor) | передача 64-битных ROM датчиков парой CAN-кадров | `stdint.h` | отправка и приём CAN-кадра |
+| [`c/ds18b20`](c/ds18b20) | термометры DS18B20 поверх программной 1-Wire | `stdint.h` | Init, DelayUs, Reset, WriteBit, ReadBit — **порт STM32F1 в комплекте** |
+| [`c/protocan-transport`](c/protocan-transport) | транспорт ProtoCAN: кадр, канал, CRC, общее адресное пространство, каталог GUI | `stdint.h` | запись в поток и запрос свободного места — **порт STM32F4 в комплекте** |
+| [`c/rtc-service`](c/rtc-service) | RTC с резервированным backup-томом | `stdint.h` | доступ к RTC и backup-памяти — **порт K1921VK028 в комплекте** |
+
+### Python
+
+| Модуль | Что делает | Зависимости |
+|---|---|---|
+| [`python/protocan`](python/protocan) | разбор ProtoCAN, транспортный кадр моста, кадр SETGUI, кодеки каталога | stdlib, Python 3.9+ |
+
+Кодировщики `c/protocan-transport` и `python/protocan` дают побайтово
+одинаковый результат — это зафиксировано эталонами в тестах на C.
+
+## Как подключить к проекту
+
+**Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
+
+```
+git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
+git submodule update --init --recursive
+```
+
+Дальше в сборку добавляются только нужные каталоги:
+
+```
+lib/templates/c/st7789/st7789.c
+lib/templates/c/menu/menu.c
+```
+
+**Subtree** — когда правки чаще идут из проекта в библиотеку:
+
+```
+git subtree add  --prefix lib/templates https://git.rd12.ru/Andrey/templates.git master --squash
+git subtree pull --prefix lib/templates https://git.rd12.ru/Andrey/templates.git master --squash
+```
+
+Копировать файлы руками не нужно: копия расходится с оригиналом за пару
+недель, и потом непонятно, какая версия правильная.
+
+## Где эти библиотеки уже работают
+
+| Проект | Что берёт |
+|---|---|
+| `KONOR_ds18b20` | st7789, keypad, menu, eeprom-ft24c256, can-sensor, ds18b20 |
+| `OpticalTester` | st7789, keypad, menu, eeprom-ft24c256 |
+| `CAN_to_RS485` | protocan-transport, python/protocan |
+| `SETGUI` | python/protocan |
+| `k1921vk028` | rtc-service |
+
+## Что сюда не попало и почему
+
+| Код | Почему не переносится | Что можно вытащить |
+|---|---|---|
+| `SETCAN/Src/protocan.c` | 59 вызовов `HAL_*`, привязка к `CAN_HandleTypeDef`, `RTC_HandleTypeDef`, `NVIC_SystemReset()` | разбиение длинных посылок на кадры и проверка даты — чистая логика, нужны два интерфейса: «отправить кадр» и «часы». Раскладка идентификатора уже вынесена в `pcan_id` |
+| `1921vk028/drivers/user/src/one_wire_user.c` | аппаратный 1-Wire `OWI_*` из `plib028`, мигание светодиодом прямо внутри опроса датчика | логика DS18B20 уже есть в `c/ds18b20` — переносится порт, а не алгоритм |
+| `1921vk028/drivers/GPIO`, `uart`, `optical`, `Interrupt` | целиком на регистрах `plib028` | переносить стоит не код, а приём: таблица описаний портов вместо `#define`, разбросанных по файлу |
+| `Drivers/` внутри прошивок | вендорный HAL и CMSIS | ничего, приходит со своим SDK |
+
+Строчку в этой таблице стоит завести, когда очередной драйвер решили не
+переносить: следующий человек не будет разбираться заново.
+
+## Правила
+
+[CONTRIBUTING.md](CONTRIBUTING.md) — что считается переносимой библиотекой,
+как оформлять порт, как называть коммиты.