Документация: добавлен README.ru.md с шапкой

README.md

@@ -1,12 +1,24 @@
+<div align="center">
+
 # Verstak Plugin SDK
 
+### TypeScript API, JSON schemas and contract tests for Verstak plugins.
+
+**English** · [Русский](README.ru.md)
+
+[![Release](https://img.shields.io/github/v/release/mirivlad/verstak-sdk?include_prereleases\&label=release)](https://github.com/mirivlad/verstak-sdk/releases)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+[![License](https://img.shields.io/github/license/mirivlad/verstak-sdk)](LICENSE)
+
+</div>
+
+> **Alpha contract.** Keep SDK, Desktop and official-plugin versions in the
+> same release line while APIs are evolving.
+
 TypeScript API, JSON schemas and contract tests for plugins running in Verstak
 Desktop. The SDK is versioned independently so plugin authors can validate
 their manifests and compile against the public host API.
 
-> **Alpha contract.** This is the first public alpha. Keep SDK, Desktop and
-> official-plugin versions in the same release line while APIs are evolving.
-
 ## Install and verify
 
 ```bash

README.ru.md

@@ -0,0 +1,105 @@
+<div align="center">
+
+# Verstak Plugin SDK
+
+### TypeScript API, JSON-схемы и контрактные тесты для плагинов Верстака.
+
+[English](README.md) · **Русский**
+
+[![Release](https://img.shields.io/github/v/release/mirivlad/verstak-sdk?include_prereleases\&label=release)](https://github.com/mirivlad/verstak-sdk/releases)
+![Статус](https://img.shields.io/badge/status-alpha-orange)
+[![Лицензия](https://img.shields.io/github/license/mirivlad/verstak-sdk)](LICENSE)
+
+</div>
+
+> **Контракт alpha-версии.** Держите SDK, Desktop и официальные плагины
+> в одной релизной линейке, пока API развиваются.
+
+TypeScript API, JSON-схемы и контрактные тесты для плагинов в Verstak Desktop.
+SDK версионируется независимо, чтобы авторы плагинов могли валидировать
+свои manifest и компилироваться против публичного host API.
+
+## Установка и проверка
+
+```bash
+npm ci
+npm run lint
+npm test
+npm run build
+```
+
+Сборка создаёт `dist/`. Упакованный npm-артефакт можно сделать локально:
+
+```bash
+./scripts/release.sh v0.1.0
+```
+
+Скрипт проверяет версию на соответствие `package.json`, затем записывает
+npm-тарбол и `SHA256SUMS` в `release/`.
+
+## Публикация GitHub Release
+
+```bash
+./scripts/publish-github-release.sh v0.1.0
+```
+
+Выполняет локальную упаковку, затем требует чистый актуальный `main` и
+авторизованный [`gh`](https://cli.github.com/) CLI. Создаёт и отправляет
+аннотированный тег, затем загружает npm-тарбол и `SHA256SUMS` в GitHub Releases.
+Запрошенная версия должна совпадать с `package.json`.
+
+## Контракты, актуальные для alpha
+
+- Дела имеют постоянные UUID-идентификаторы; пути — это адреса, а не идентификаторы.
+- Активность может быть привязана к `workspaceId` или к явной области `unassigned`.
+- `hostname-normalization-v1.json` определяет общее каноническое представление
+  доменов браузера, используемое Desktop и расширением.
+- Пакеты активности браузера содержат только нормализованный домен и ограниченную
+  длительность. Ручные захваты используют отдельный протокол Inbox.
+
+## Контракт синхронизации
+
+`schemas/sync.json` описывает формат журнала операций, используемый Desktop core
+и sync-сервером. Сервер упорядочивает операции по `server_sequence`, не сливает
+содержимое файлов и не становится источником истины.
+
+- Операции с файлами и папками: `create`, `update`, `delete`, `move`. Небольшой
+  UTF-8 текст может быть встроенным; бинарные и большие файлы содержат ссылку
+  `blob` `{sha256,size}`.
+- Операции с делами (`Deal`) — это сущности `workspace`, принадлежащие core:
+  `create`, `rename`, `trash`, `restore` с постоянным `workspaceId`.
+- Pull использует `since_sequence` и `page_limit`; клиент сохраняет курсор
+  только после успешного применения каждой операции и останавливается на первой
+  неудачной.
+- Файл, превышающий лимит blob или иначе неподдерживаемый, не помечается
+  синхронизированным и повторяется при следующих сканированиях.
+
+## Контракт Frontend API
+
+Verstak Desktop создаёт реальный API через `createPluginAPI(pluginId)` и
+передаёт его компонентам плагинов при монтировании. SDK экспортирует
+TypeScript-типы для этого объекта:
+
+- `settings.read/write/writeAll`
+- `capabilities.list/get/has`
+- `commands.register/execute/executeFor`
+- `contributions.list`
+- `events.publish/subscribe`
+- `files.list/metadata/readText/readBytes/writeText/createFolder/move/trash/listTrash/restoreTrash/deleteTrash`
+- `workbench.openResource/editResource`
+- опциональный `dispose`
+
+Пути к файлам — канонические vault-относительные слеш-пути. Обратные слеши,
+абсолютные пути Windows/UNC, переходы по директориям, нулевые байты, варианты
+`.verstak` и операции через symlink отклоняются. Чтение/запись текста — только
+UTF-8; `readText` ограничен 2 МБ, `readBytes` возвращает base64 для обычных
+файлов до 8 МБ.
+
+Bundled frontend-плагины являются доверенными и выполняются в контексте JS
+рабочего стола. Текущие проверки прав — это контрактные проверки, а не граница
+безопасности; настоящая изоляция — в будущем milestone sidecar/sandbox.
+
+## Лицензия
+
+Copyright © 2026 Verstak contributors. Распространяется на условиях
+[GNU AGPLv3 или новее](LICENSE).