diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d51b1a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# Zivro
+
+Графическое приложение на Zig + DVUI/SDL3 для работы с документом фигур (линия, эллипс, ломаная) и CPU-рендерингом сцены.
+
+## Что умеет
+
+- Открывать и сохранять документ в JSON (`File -> Open`, `File -> Save As`).
+- Создавать новый документ и управлять несколькими открытыми вкладками.
+- Добавлять и удалять объекты в иерархическом дереве.
+- Отображать сцену в canvas и переключать параметры рендера (quality, stats, redraw).
+
+## Технологии
+
+- [Zig](https://ziglang.org/) `0.15.2+`
+- [DVUI](https://github.com/david-vanderson/dvui) (backend `sdl3`)
+- SDL3 (через зависимость DVUI)
+
+## Быстрый старт
+
+```bash
+git clone <your-fork-or-repo-url>
+cd Zivro
+zig build run
+```
+
+После запуска в окне приложения нажмите `New document`, чтобы создать первый документ.
+
+## Сборка и запуск
+
+```bash
+# Debug build
+zig build
+
+# Запуск приложения
+zig build run
+
+# Тесты
+zig build test
+```
+
+Передача аргументов в приложение:
+
+```bash
+zig build run -- <arg1> <arg2>
+```
+
+## Структура проекта
+
+- `src/main.zig` — точка входа и главный цикл окна/событий.
+- `src/ui/` — меню, панели, вкладки, canvas-представление.
+- `src/models/` — документ, объекты, shape-модели.
+- `src/render/` — абстракции рендера и CPU-реализация.
+- `src/persistence/` — JSON импорт/экспорт документов.
+- `build.zig` — описание шагов `build`, `run`, `test`.
+- `Report/` — материалы отчёта и диаграммы.
+
+## Формат данных
+
+Документы сохраняются как JSON. Операции чтения/записи реализованы в `src/persistence/json_io.zig`, а структура документа — в `src/models/Document.zig`.
+
+## Troubleshooting
+
+- **Ошибка линковки вида `R_X86_64_PC64 ... crt1.o:.sframe` при `zig build test`**  
+  Обычно связана с несовместимостью toolchain линкера/системных CRT на некоторых Linux-конфигурациях.  
+  Проверьте актуальность Zig и системного toolchain; при необходимости попробуйте другой Zig/toolchain пакет.
+
+## Разработка
+
+- Тестовый root: `src/tests.zig` (подключает модули с `test`-блоками).
+- Для добавления тестов в общий прогон подключайте модуль через `@import(...)` в `src/tests.zig`.
+