diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a42b6ea
--- /dev/null
+++ b/README.md
@@ -0,0 +1,164 @@
+
+
+# LoVisual
+
+Open-source Minecraft utility client **and** the platform around it - website, cloud config sharing, and a Rust backend.
+
+Developed and maintained by [loki5512344](https://github.com/loki5512344).
+
+
+
+
+
+
+
+**[⬇ Download the mod](https://github.com/loki5512344/LoVisual-/releases/latest/download/lovisual.jar)** · [Releases](https://github.com/loki5512344/LoVisual-/releases)
+
+[English](#english) | [Русский](#русский)
+
+
+
+---
+
+## English
+
+### What is this?
+
+LoVisual is three things in one repository:
+
+| Component | What it is | Stack |
+|-----------|------------|-------|
+| [`mod/`](mod) | The Minecraft client itself - 60+ modules, ClickGUI, HUD editor, theme system, custom renderer | Java 25 · Fabric · OpenGL/Vulkan |
+| [`frontend/`](frontend) | The website - downloads, docs, live demos of the in-game GUI, account & config pages | React 19 · Vite · TypeScript · Tailwind · bun |
+| [`backend/`](backend) | The platform services - API gateway, accounts, cloud config slots with share codes | Rust · Axum · PostgreSQL · gRPC |
+
+The pieces talk to each other: link the mod to your platform account with `%link`, push a config
+to a cloud slot with `%config save <1-4>`, and a friend imports it by code with `%config load `.
+
+### Mod highlights
+
+- **Combat / Visuals / Player / Misc** - Reach, ESP, NameTags, Chams, FullBright, Freecam, AutoTool, FakePlayer and more (see [mod README](mod/README.md) for the full list)
+- **ClickGUI** on `RShift` - module browser, settings, theme editor, config profiles
+- **HUD editor** - draggable and static elements: TargetHUD, ModuleList, Watermark, Keystrokes…
+- **Cloud configs** - 4 slots per account, short share codes, public showcase
+- **`.lvcfg` profiles** - export/import modules, HUD and themes locally, no account needed
+- **Addon API** - versioned API for extending the client
+
+Requires Fabric Loader, Fabric API and Sodium; optional compatibility with Iris, ViaFabricPlus,
+Xaero's Minimap/World Map and more.
+
+### Repository layout
+
+```
+├── mod/ Fabric client (Gradle, Java) → mod/README.md
+├── frontend/ marketing + dashboard site (bun) → frontend/README.md
+├── backend/ gateway, accounts-, configs-service → backend/STRUCTURE.md
+├── docs/ cross-cutting docs → docs/README.md
+└── ref/ reference material (not shipped)
+```
+
+### Development
+
+Mod (from `mod/`):
+
+```bash
+./gradlew build # compile + remap jar into build/libs
+./gradlew runClient # launch a dev Minecraft client
+./gradlew test # unit tests
+```
+
+Frontend (from `frontend/`, requires bun):
+
+```bash
+bun install
+bun run dev # http://localhost:5173
+bun run test # vitest
+bun run build # type-check + production bundle
+```
+
+Backend (from `backend/`, requires Rust + PostgreSQL):
+
+```bash
+cargo build
+cargo test
+```
+
+Releases are cut by pushing a `v*` tag - GitHub Actions builds the mod jar and publishes it to
+[Releases](https://github.com/loki5512344/LoVisual-/releases) as both `lovisual-.jar`
+and a stable `lovisual.jar` link.
+
+### License
+
+GNU General Public License v3.0. See [LICENSE](mod/LICENSE).
+
+---
+
+## Русский
+
+### Что это?
+
+LoVisual - три проекта в одном репозитории:
+
+| Компонент | Что это | Стек |
+|-----------|---------|------|
+| [`mod/`](mod) | Сам клиент для Minecraft - 60+ модулей, ClickGUI, редактор HUD, темы, свой рендер | Java 25 · Fabric · OpenGL/Vulkan |
+| [`frontend/`](frontend) | Сайт - загрузки, документация, живые демо внутриигрового GUI, страницы аккаунта и конфигов | React 19 · Vite · TypeScript · Tailwind · bun |
+| [`backend/`](backend) | Сервисы платформы - API-шлюз, аккаунты, облачные слоты конфигов с кодами расшаривания | Rust · Axum · PostgreSQL · gRPC |
+
+Части связаны: привяжи мод к аккаунту командой `%link`, залей конфиг в облачный слот через
+`%config save <1-4>`, друг заберёт его по коду командой `%config load `.
+
+### Возможности мода
+
+- **Combat / Visuals / Player / Misc** - Reach, ESP, NameTags, Chams, FullBright, Freecam, AutoTool, FakePlayer и другие (полный список - в [README мода](mod/README.md))
+- **ClickGUI** на `RShift` - браузер модулей, настройки, редактор тем и профилей
+- **Редактор HUD** - перетаскиваемые и статические элементы: TargetHUD, ModuleList, Watermark, Keystrokes…
+- **Облачные конфиги** - 4 слота на аккаунт, короткие коды, публичный показ
+- **Профили `.lvcfg`** - локальный экспорт/импорт модулей, HUD и тем без аккаунта
+- **Addon API** - версионированное API для расширения клиента
+
+Нужны Fabric Loader, Fabric API и Sodium; опционально - Iris, ViaFabricPlus, Xaero's Minimap/World Map и др.
+
+### Структура репозитория
+
+```
+├── mod/ клиент Fabric (Gradle, Java) → mod/README.md
+├── frontend/ сайт-витрина и дашборд (bun) → frontend/README.md
+├── backend/ gateway, accounts-, configs-service → backend/STRUCTURE.md
+├── docs/ сквозная документация → docs/README.md
+└── ref/ референсы (не поставляется)
+```
+
+### Разработка
+
+Мод (из `mod/`):
+
+```bash
+./gradlew build # сборка и remap jar в build/libs
+./gradlew runClient # запуск dev-клиента Minecraft
+./gradlew test # модульные тесты
+```
+
+Фронтенд (из `frontend/`, нужен bun):
+
+```bash
+bun install
+bun run dev # http://localhost:5173
+bun run test # vitest
+bun run build # типы + production-сборка
+```
+
+Бэкенд (из `backend/`, нужны Rust и PostgreSQL):
+
+```bash
+cargo build
+cargo test
+```
+
+Релизы создаются пушем тега `v*` - GitHub Actions собирает jar мода и публикует в
+[Releases](https://github.com/loki5512344/LoVisual-/releases) как `lovisual-<версия>.jar`
+и по стабильной ссылке `lovisual.jar`.
+
+### Лицензия
+
+GNU General Public License v3.0. См. [LICENSE](mod/LICENSE).
diff --git a/frontend/README.md b/frontend/README.md
index d6af7e3..0c47ecb 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,32 +1,49 @@
-# React + TypeScript + Vite
+# LoVisual Website
-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+The frontend for [LoVisual](../README.md) - a marketing site with a live in-game GUI demo,
+download page, documentation, themes/showcase pages, and an account dashboard with a cloud
+config manager. UI is fully bilingual (Russian default, English toggle, persisted in the URL).
-Currently, two official plugins are available:
+## Stack
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+- **React 19 + TypeScript + Vite**, package manager: **bun**
+- **Tailwind CSS v4** with custom design tokens (radii, glass panels, control sizing)
+- **TanStack Query** for backend calls, **react-router** for pages
+- **react-i18next** - `ru`/`en` resources per feature, compile-time key parity via `satisfies`
+- **motion/react** for animation, **vitest + Testing Library** for tests
+- **oxlint** for linting
-## React Compiler
+## Layout
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the Oxlint configuration
-
-If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
-
-```json
-{
- "$schema": "./node_modules/oxlint/configuration_schema.json",
- "plugins": ["react", "typescript", "oxc"],
- "options": {
- "typeAware": true
- },
- "rules": {
- "react/rules-of-hooks": "error",
- "react/only-export-components": ["warn", { "allowConstantExport": true }]
- }
-}
+```
+src/
+├── app/ router, providers, App shell
+├── features/ one folder per domain (account, cloud, demo, themes, ...)
+│ └── / api.ts · i18n/{ru,en}.ts · components/ · tests/
+├── pages/ route-level pages composing features
+├── shared/ ui primitives, i18n bootstrap, easter eggs, helpers
+└── test/ vitest setup and utilities
```
-See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
+Feature-folder rules: API calls, translations and components live together; no cross-feature
+imports except through `shared/`.
+
+## Scripts
+
+```bash
+bun install # install dependencies
+bun run dev # dev server on http://localhost:5173 (proxies /api to the backend)
+bun run test # vitest run
+bun run build # tsc -b + vite build → dist/
+bun run lint # oxlint
+bun run gen:themes # regenerate theme tokens from the mod palette (scripts/extract-themes.ts)
+```
+
+The dev server expects the Rust gateway on `127.0.0.1:8080` (see [`backend/`](../backend));
+without it, API-backed pages degrade to demo/offline states by design.
+
+## Testing
+
+Unit and component tests are colocated in `features/*/tests/` and `shared/**/tests/`;
+run a single file with `bunx vitest run src/features/account/tests/account.test.tsx`.
+Translation parity (ru ↔ en key sets) is enforced at compile time and in tests.
diff --git a/mod/README.md b/mod/README.md
index 93964f2..6c6e8d9 100644
--- a/mod/README.md
+++ b/mod/README.md
@@ -135,7 +135,7 @@ LoVisual разрабатывается и поддерживается [loki551
### Docs
-- [Development guide](DEVELOPMENT.md) — project rules, how to add modules/HUD/events/config
+- [Development guide](DEV_GUIDE.md) — project rules, how to add modules/HUD/events/config
### License