diff --git a/README.md b/README.md
index 892da5f..aee6b91 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,72 @@
-# livedigital-ios-sdk-binary
-LiveDigitalSDK public builds (binary XCFramework)
+# livedigital SDK
+
+Этот репозиторий содержит сборки нативной реализации livedigital SDK для iOS в формате толстого бинарного XCFramework.
+
+livedigital SDK — клиент сервиса livedigital (https://docs.livedigital.space). SDK реализует
+  * сигналинг (подключение, обмен командами с медиа-сервером)
+  * логику восстановления соединения при реконнекте
+  * анализ качества соединения
+  * работу с входящими и исходящими медиа-треками
+  * работу с видео-слоями
+  * размытие и замену фона для исходящего видео
+  * логику выделения активного спикера
+  * транспорт для передачи команд и мета-данных специфичных для приложения
+
+## Совместимость
+
+* устройства iOS / iPadOS 16+
+* симуляторы iOS / iPadOS 16+
+
+Поддержка iOS 15 есть, но находится в стадии deprecated. Стабильность работы на ней не тестируется и не гарантируется. Поддержка может быть прекращена в скором времени.
+
+SDK поддерживает работу на симуляторах, однако полноценное тестирование должно проводиться на реальном устройстве, т.к. имплементация работы с камерой, размытие фона, набор поддерживаемых кодеков и видео-форматов могут отличаться.
+
+## Подключение
+
+Доступны два способа подключения через менеджеры зависимостей — CocoaPods и SwiftPM. Мы рекомендуем использовать SwiftPM как более актуальное и современное решение.
+
+Мы рекомендуем фиксировать точную версию зависимости (SPM: `Exact Version: 2.12.3` / CP: `:tag => '2.12.3'`) и обновлять любые зависимости по мере необходимости только вручную. Как минимум необходимо зафиксировать мажорную версию (SPM: `Up to Next Major Version: 2.12.0 < 3.0.0` / CP: `~> 2.12`), т.к. выпуск мажорного релиза обычно связан с необходимостью изменений в коде приложения.
+
+Подключать зависимость нужно в таргет приложения, а также в таргеты расширений которые могут использовать SDK (например Broadcast Upload Extension для демонстрации экрана, если оно реулизуется).
+
+### Swift Package Manager
+
+* Подключить пакет `LiveDigitalSDK` из репозитория `https://github.com/VLprojects/livedigital-ios-sdk-binary.git`.
+* Из пакета добавить единственную публичную библиотеку `LiveDigitalSDK` в необходимые таргеты.
+
+### CocoaPods
+
+*Несмотря на то что livedigital SDK публикуется в CocoaPods Trunk репозиторий, мы рекомендуем подключать нашу и все остальные зависимости не из Trunk, а напрямую указывая репозиторий и конкретную версию или тег. CocoaPods Trunk будет закрыт в 2026 году, после чего там не будут публиковаться новые версии.*
+
+* Добавить под `LiveDigitalSDK` в необходимые таргеты
+  ```Ruby
+  pod 'LiveDigitalSDK',
+    :git => 'https://github.com/VLprojects/livedigital-ios-sdk-binary',
+    :tag => '2.12.3'
+  ```
+* Установить зависимости командой `pod install --repo-update`.
+
+## Пример интеграции и демо
+
+Этот репозиторий содержит папку Example с проектом демонстрирующим интеграцию и использование livedigital SDK. Example проект выполнен в минималистичном духе и не должен рассматриваться с точки зрения удобства UX, красоты кода и архитектуры, надёжности решений и т.д.
+
+Исходный код общий, но проектных файла два:
+
+* SPM_Example.xcodeproj — SDK подключено через SwiftPM. Для начала работы можно просто открыть проект.
+* CP_Example.xcworkspace — SDK подключено через CocoaPods. Перед открытием проекта (воркспейса) нужно установить зависимости выполнив команду `pod install --repo-update`.
+
+Для запуска на реальном устройстве нужно предварительно настроить подписывание приложения на вкладке Signing & Capabilities в настройках таргета `LiveDigitalSDKExample` используя свой Apple Developer Account.
+
+При запуске приложения показывается экран `StartVC` содержащий поля для ввода идентификатора спейса(группы) и комнаты.
+
+Основная работа сосредоточена в классе `SessionVC`, который отвечает за сессию "звонка" или "конференции". При первом запуске будут запрошены доступы к камере и микрофону. Для сохранения простоты Example проекта, он не реализует полноценной обработки ситуации когда разрешения не выданы. После выдачи разрешений происходит подключение к комнате. В верхней части экрана отображается локальный участник с кнопками включения микрофона и камеры. Основную часть экрана занимает сетка участников с горизонтальной прокруткой.
+
+Для простоты проверки работы SDK, в Example проекте в комнате участники видят не только друг друга, но и себя (с аудио и видео прошедшими до медиа-сервера и обратно). Таким образом можно протестировать работу SDK используюя всего одно устройство. При подключении нескольких участников к одной комнате это может мешать тестированию звука, так что можно отключить получение медиа-треков собственного участника удалив строку `channelSession.shouldShowLocalPeer = true`. Для удобства тестирования можно зайти в ту же комнату через веб-приложение livedigital. Сссылку на тестовую комнату можно получить у нашей команды.
+
+Горизонтальный свайп по своему превью переключает камеру между фронтальной и основной. Долгое нажатие на кнопку микрофона показывает меню выбора звукового устройства.
+
+Example приложение кроме базовой работы с SDK реализует две часто востребованные механики:
+
+* Обмен мета-данными участников. При старте сессии (`engine.connectToChannel(...)`) передаётся параметр `peerPayload: ["name": UIDevice.current.name]`. Передаваемое значение (словарь) может содержать набор произвольных ключей и значений, с которыми работает приложение — имя пользователя, userId в терминах приложения, версия приложения, статус пользователя и т.д.. Во время сессии пользователь может обновлять свои мета-данные через метод `self.channelSession?.updatePeerPayload(...)`. Другие участники находящиеся в комнате могут прочитать метаданные друг друга через свойство `peer.payload`, а также могут получать обновления метаданных в режиме реального времени в callback метод `gotPeerAppDataUpdates(_ updates:)`.
+
+* Пауза невидимых входящих видео-потоков. SDK позволяет сократить нагрзку на сеть и батарею пользователя ставя ненужные в данный момент входяшие медиа-потоки на паузу. Например если приложение свёрнуто — достаточно получать только аудио, а видео поток остановить. Если в комнате находятся 12 участников, но на экране видны только 2 — остальные 10 потоков можно поставить на паузу. Пример реализации этой механики находится в методе `updateVisiblePeersVideos`.