diff --git a/README.md b/README.md
index e5f71ab..0ba83a3 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
# Lightweight Cobot
-> **Тестовая версия документации — будет дополнена**
+
+ Русский · English
+
-ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7 R800**: связь с реальным роботом через библиотеку [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) и симуляция в среде [Webots](https://cyberbotics.com/).
+**Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR iiwa 7 R800** на базе ROS 2. Проект объединяет работу с физическим роботом через FRI и `ros2_control`, цифровой двойник в Webots, планирование движений MoveIt 2, визуализацию в RViz и Foxglove, а также REST API и MCP для внешних приложений и AI-агентов.
@@ -15,91 +17,138 @@ ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7
----
+## Какие задачи решает проект
-## Статус
+- Даёт единый программный стек для физического робота и симуляции без дублирования управляющего кода.
+- Подключает KUKA Sunrise Cabinet к ROS 2 через FRI и предоставляет стандартные интерфейсы `ros2_control`.
+- Выполняет суставные и декартовы движения с помощью MoveIt 2, OMPL и Pilz.
+- Упрощает установку, настройку, сборку и запуск через CLI `cobot`.
+- Хранит основные параметры робота, инструментов и сервисов в одном файле `cobot-setting.yaml`.
+- Предоставляет средства мониторинга и интеграции через RViz, Foxglove, HTTP/WebSocket API и MCP.
-| ОС | Дистрибутив ROS | Версия FRI |
-| :--- | :--- | :--- |
-| `Ubuntu 24.04` | `jazzy` | `1.16` |
+## Возможности
----
+| Компонент | Назначение |
+|---|---|
+| Физический робот | Управление KUKA LBR iiwa 7 R800 через FRI и `ServerFriRos2` |
+| Цифровой двойник | Симуляция робота, инструментов и окружения в Webots |
+| Планирование | Суставные и декартовы траектории через MoveIt 2 |
+| Управление | `ros2_control`, ROS 2 actions/services, REST API и MCP |
+| Наблюдение | RViz, Foxglove и состояние системы через веб-интерфейс |
+| Инфраструктура | Локальное окружение или Docker, единый CLI и централизованная конфигурация |
+
+## Совместимость
+
+| Компонент | Поддерживаемая версия |
+|---|---|
+| Операционная система | **Ubuntu 24.04 LTS** — подтверждённая ОС для нативной установки |
+| ROS 2 | Jazzy |
+| Webots | 2025a |
+| Python для CLI | 3.11 |
+| KUKA Sunrise OS | 1.16 |
+| KUKA FRI | 1.16 |
+
+Docker можно использовать как альтернативную среду на совместимом Linux-хосте. Полноценная работа проекта на Windows и macOS не заявлена. Sunrise Workbench используется отдельно для подготовки и синхронизации проекта контроллера KUKA.
+
+## Репозитории и документация
+
+| Ресурс | Ссылка |
+|---|---|
+| Основной репозиторий | [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) |
+| Зеркало | [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot) |
+| Онлайн-документация | [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/) |
+| Зеркало документации | [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) |
+
+Подробные инструкции начинаются со страницы [«Обзор»](doc/lwc-doc/docs/getting-started/index.md). Исходные тексты документации находятся в `doc/lwc-doc/docs`.
## Быстрый старт
-Для установки запустите скрипт одной командой:
+### Требования
+
+- Ubuntu 24.04 LTS;
+- доступ в интернет;
+- права `sudo`;
+- физический KUKA LBR iiwa 7 R800 либо компьютер для работы только с симулятором.
+
+### Установка CLI
+
+Запустите установщик:
```bash
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash
```
-Скрипт установит ROS 2 Jazzy, Webots, соберёт рабочее пространство и установит CLI `cobot`.
+Установщик проверит базовые инструменты, установит Docker, `uv` и Python 3.11 при необходимости, склонирует проект в `~/.lwc` и установит CLI `cobot`. Каталог можно изменить переменной `COBOT_INSTALL_DIR`.
----
+Откройте новый терминал или обновите окружение оболочки, затем запустите мастер первоначальной настройки:
-## Команды `cobot`
-
-После установки управляйте системой через CLI:
-
-```
-cobot <команда>
+```bash
+cobot setup
```
-### Настройка
+Мастер последовательно предложит запустить локальную документацию, настроить `cobot-setting.yaml` и выбрать среду сборки: нативный ROS 2 или Docker.
-| Команда | Описание |
-| :--- | :--- |
-| `cobot setup` | Первоначальная настройка: документация, среда сборки, конфигурация робота |
-| `cobot local-setup` | Установка ROS 2 Jazzy локально и сборка проекта через colcon |
-| `cobot docker-setup` | Сборка или загрузка Docker-образов |
-| `cobot doc-setup` | Запуск или остановка сервера документации MkDocs |
-| `cobot robot-setup` | Интерактивная настройка файла `cobot-setting.yaml` |
+### Только симуляция
-### Запуск
+Для работы в Webots физический робот и Sunrise Workbench не требуются. Выполните:
-| Команда | Описание |
-| :--- | :--- |
-| `cobot run` | Запуск контроллера робота или симулятора Webots (локально или через Docker) |
+```bash
+cobot run
+```
-### Сборка
+Выберите локальную или Docker-среду, а затем пункт **Симулятор Webots**.
-| Команда | Описание |
-| :--- | :--- |
-| `cobot rebuild` | Пересборка ROS 2 пакетов из `src/` с помощью colcon |
-| `cobot clean` | Удаление артефактов сборки (`build/` `install/` `log/`) |
+### Физический робот
-### Управление
+Перед первым запуском подготовьте контроллер и программу `ServerFriRos2` по инструкции [«Настройка SunriseWorkbench»](doc/lwc-doc/docs/getting-started/sunrise-setup.md). Проверьте сеть KONI/KLI, IP-адреса, период FRI, выбранный инструмент и его Load Data.
-| Команда | Описание |
-| :--- | :--- |
-| `cobot update` | Получение последних изменений из удалённой ветки и переустановка `cobot` |
-| `cobot delete` | Удаление проекта, Docker-образов, контейнеров и опционально ROS 2 |
+После настройки запустите:
----
+```bash
+cobot run
+```
-## Демонстрация
+Выберите локальную или Docker-среду, а затем пункт **Физический контроллер**. Подробное описание серверной программы приведено на странице [ServerFriRos2](doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.md).
-> GIF-анимации будут добавлены в следующих версиях
+## Основные команды
-
-
- | Симуляция в Webots |
- Управление по суставам |
- Декартово управление |
-
-
- | — скоро — |
- — скоро — |
- — скоро — |
-
-
+| Команда | Назначение |
+|---|---|
+| `cobot setup` | Первоначальная настройка документации, робота и среды сборки |
+| `cobot robot-setup` | Интерактивное изменение `cobot-setting.yaml` |
+| `cobot local-setup` | Установка ROS 2 Jazzy и локальная сборка workspace |
+| `cobot docker-setup` | Загрузка или сборка Docker-образов |
+| `cobot run` | Интерактивный выбор среды и запуск робота или Webots |
+| `cobot run local` | Запуск через нативный ROS 2 с последующим выбором робота или Webots |
+| `cobot run docker` | Запуск в Docker с последующим выбором робота или Webots |
+| `cobot rebuild` | Пересборка ROS 2 workspace |
+| `cobot clean` | Удаление артефактов `build`, `install` и `log` |
+| `cobot update` | Обновление проекта и переустановка CLI |
+| `cobot --help` | Полный список доступных команд |
----
+## Документация локально
+
+Для локального просмотра необходим Docker.
+
+```bash
+cobot doc-setup
+```
+
+По умолчанию сайт будет доступен по адресу [http://localhost:8000](http://localhost:8000). Исходные Markdown-файлы отслеживаются автоматически.
+
+| Команда | Назначение |
+|---|---|
+| `cobot doc-setup` | Запустить локальный сервер документации |
+| `cobot doc-setup build` | Собрать статический сайт и единый PDF в `doc/lwc-doc/site` |
+| `cobot doc-setup rebuild` | Пересобрать Docker-образ и перезапустить сервер |
+| `cobot doc-setup down` | Остановить локальный сервер |
+
+Онлайн-версия доступна на [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/), зеркало — на [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/).
## Пакеты
| Пакет | Описание |
-| :--- | :--- |
+|---|---|
| `iiwa_bringup` | Launch-файлы: симуляция Webots, реальный робот через FRI, MoveIt и RViz |
| `iiwa_config` | Конфигурационные файлы: MoveIt, контроллеры ros2_control, кинематика и общие параметры |
| `iiwa_controller` | Hardware interface: управление суставами в реальном времени через FRI |
@@ -107,13 +156,21 @@ cobot <команда>
| `iiwa_msgs` | ROS 2 интерфейсы: action-сообщения для движения по суставам и в декартовых координатах, сервисы именованных поз |
| `iiwa_planning` | Планирование движения: C++ и Python узлы на базе MoveIt 2 (OMPL, Pilz, moveit_py) |
| `iiwa_utils` | Утилиты системы: загрузка конфигурации, спавн объектов и камер в Webots, конвертация данных |
-| `iiwa_web` | Веб-интерфейс для мониторинга и дистанционного управления через браузер |
+| `iiwa_web` | REST API, WebSocket и MCP для мониторинга и внешнего управления |
----
+Java-программы для KUKA Sunrise Cabinet находятся отдельно в `src/iiwa_sunrise` и не входят в сборку colcon.
+
+## Безопасность
+
+Перед отправкой команд на физический робот проверьте рабочую область, ограничения суставов, активный инструмент, модель нагрузки и выбранный режим управления. LWC не заменяет штатные средства безопасности KUKA, оценку рисков роботизированной ячейки и контроль оператора.
+
+## Лицензия
+
+Проект распространяется по лицензии [Apache License 2.0](LICENSE).
## Цитирование
-Если вы используете этот проект в своей работе, пожалуйста, оставьте звёздочку ⭐ и укажите ссылку:
+Если вы используете проект в исследовании или разработке, укажите ссылку на репозиторий:
```bibtex
@software{lightweight_cobot_2026,
@@ -128,14 +185,10 @@ cobot <команда>
## Благодарности
-Выражаем благодарность следующим организациям и грантам:
-
| Организация | Примечание |
-| :--- | :--- |
+|---|---|
| [Комсомольский-на-Амуре государственный университет](https://knastu.ru/) | Исследования проводились на базе КнАГУ |
| [Российский научный фонд](https://rscf.ru/) | Работа выполнена при поддержке Российского научного фонда |
-| | |
-| | |
---
diff --git a/README_en.md b/README_en.md
index 4147b70..ee28a17 100644
--- a/README_en.md
+++ b/README_en.md
@@ -1,119 +1,176 @@
# Lightweight Cobot
-> **Draft documentation — work in progress**
+
+ Русский · English
+
-ROS 2 packages for controlling the **KUKA LBR IIWA 7 R800**: communication with the real robot via [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) and simulation in [Webots](https://cyberbotics.com/).
+**Lightweight Cobot (LWC)** is an open control system for the **KUKA LBR iiwa 7 R800** collaborative robot built on ROS 2. It combines physical robot control through FRI and `ros2_control`, a Webots digital twin, MoveIt 2 motion planning, RViz and Foxglove visualization, plus REST and MCP interfaces for external applications and AI agents.
- | LBR IIWA 7 R800 |
+ LBR iiwa 7 R800 |
- 
+
|
----
+## Problems solved by the project
-## Status
+- Provides one software stack for both the physical robot and simulation without duplicating control code.
+- Connects KUKA Sunrise Cabinet to ROS 2 through FRI and exposes standard `ros2_control` interfaces.
+- Executes joint-space and Cartesian motions using MoveIt 2, OMPL, and Pilz.
+- Simplifies installation, configuration, builds, and startup through the `cobot` CLI.
+- Keeps the main robot, tool, and service parameters in one `cobot-setting.yaml` file.
+- Provides monitoring and integration through RViz, Foxglove, HTTP/WebSocket APIs, and MCP.
-| OS | ROS Distribution | FRI Version |
-| :--- | :--- | :--- |
-| `Ubuntu 24.04` | `jazzy` | `1.16` |
+## Features
----
+| Component | Purpose |
+|---|---|
+| Physical robot | KUKA LBR iiwa 7 R800 control through FRI and `ServerFriRos2` |
+| Digital twin | Robot, tool, and environment simulation in Webots |
+| Motion planning | Joint-space and Cartesian trajectories through MoveIt 2 |
+| Control | `ros2_control`, ROS 2 actions/services, REST API, and MCP |
+| Monitoring | RViz, Foxglove, and system state through the web interface |
+| Infrastructure | Native or Docker environment, a unified CLI, and centralized configuration |
-## Quick Start
+## Compatibility
-Install everything with a single command:
+| Component | Supported version |
+|---|---|
+| Operating system | **Ubuntu 24.04 LTS** — verified for native installation |
+| ROS 2 | Jazzy |
+| Webots | 2025a |
+| CLI Python | 3.11 |
+| KUKA Sunrise OS | 1.16 |
+| KUKA FRI | 1.16 |
+
+Docker is available as an alternative environment on a compatible Linux host. Full Windows and macOS support is not claimed. Sunrise Workbench is used separately to prepare and synchronize the KUKA controller project.
+
+## Repositories and documentation
+
+| Resource | Link |
+|---|---|
+| Primary repository | [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) |
+| Mirror | [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot) |
+| Online documentation | [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/) |
+| Documentation mirror | [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) |
+
+The detailed guide starts on the [Overview](doc/lwc-doc/docs/getting-started/index.md) page. Documentation sources are stored under `doc/lwc-doc/docs`.
+
+## Quick start
+
+### Requirements
+
+- Ubuntu 24.04 LTS;
+- internet access;
+- `sudo` privileges;
+- a physical KUKA LBR iiwa 7 R800, or a computer if only the simulator will be used.
+
+### Install the CLI
+
+Run the installer:
```bash
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash
```
-The script installs ROS 2 Jazzy, Webots, builds the workspace, and installs the `cobot` CLI.
+The installer checks the basic tools, installs Docker, `uv`, and Python 3.11 when required, clones the project into `~/.lwc`, and installs the `cobot` CLI. Set `COBOT_INSTALL_DIR` to use a different location.
----
+Open a new terminal or reload the shell environment, then start the first-time setup wizard:
-## `cobot` Commands
-
-After installation, manage the system via CLI:
-
-```
-cobot
+```bash
+cobot setup
```
-### Setup
+The wizard offers to start the local documentation, configure `cobot-setting.yaml`, and prepare either a native ROS 2 or Docker build environment.
-| Command | Description |
-| :--- | :--- |
-| `cobot setup` | First-time setup: documentation server, build environment, robot config |
-| `cobot local-setup` | Install ROS 2 Jazzy natively and build the project with colcon |
-| `cobot docker-setup` | Build or pull Docker images |
-| `cobot doc-setup` | Deploy or stop the MkDocs documentation server |
-| `cobot robot-setup` | Configure `cobot-setting.yaml` interactively |
+### Simulation only
-### Run
+A physical robot and Sunrise Workbench are not required for Webots simulation. Run:
-| Command | Description |
-| :--- | :--- |
-| `cobot run` | Launch the robot controller or Webots simulator (local or Docker) |
+```bash
+cobot run
+```
-### Build
+Choose the native or Docker environment, then select **Webots simulator**.
-| Command | Description |
-| :--- | :--- |
-| `cobot rebuild` | Rebuild ROS 2 packages in `src/` with colcon |
-| `cobot clean` | Remove colcon build artifacts (`build/` `install/` `log/`) |
+### Physical robot
-### Management
+Before the first run, prepare the controller and `ServerFriRos2` as described in [Sunrise Workbench setup](doc/lwc-doc/docs/getting-started/sunrise-setup.md). Verify the KONI/KLI network, IP addresses, FRI period, selected tool, and its Load Data.
-| Command | Description |
-| :--- | :--- |
-| `cobot update` | Pull latest changes from the remote git branch and reinstall `cobot` |
-| `cobot delete` | Remove the project, Docker images, containers, and optionally ROS 2 |
+Then run:
----
+```bash
+cobot run
+```
-## Demo
+Choose the native or Docker environment, then select **Physical controller**. See the [ServerFriRos2](doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.md) page for details about the controller-side application.
-> GIF animations will be added in upcoming releases
+## Main commands
-
-
- | Webots Simulation |
- Joint-Space Control |
- Cartesian Control |
-
-
- | — coming soon — |
- — coming soon — |
- — coming soon — |
-
-
+| Command | Purpose |
+|---|---|
+| `cobot setup` | Configure documentation, robot parameters, and the build environment |
+| `cobot robot-setup` | Edit `cobot-setting.yaml` interactively |
+| `cobot local-setup` | Install ROS 2 Jazzy and build the workspace natively |
+| `cobot docker-setup` | Pull or build the Docker images |
+| `cobot run` | Select an environment and launch the physical robot or Webots interactively |
+| `cobot run local` | Use native ROS 2, then select the physical robot or Webots |
+| `cobot run docker` | Use Docker, then select the physical robot or Webots |
+| `cobot rebuild` | Rebuild the ROS 2 workspace |
+| `cobot clean` | Remove the `build`, `install`, and `log` artifacts |
+| `cobot update` | Update the project and reinstall the CLI |
+| `cobot --help` | Show every available command |
----
+## Local documentation
+
+Docker is required for the local documentation server.
+
+```bash
+cobot doc-setup
+```
+
+By default, the site is available at [http://localhost:8000](http://localhost:8000). Markdown source changes are watched automatically.
+
+| Command | Purpose |
+|---|---|
+| `cobot doc-setup` | Start the local documentation server |
+| `cobot doc-setup build` | Build the static site and combined PDF under `doc/lwc-doc/site` |
+| `cobot doc-setup rebuild` | Rebuild the Docker image and restart the server |
+| `cobot doc-setup down` | Stop the local server |
+
+The online documentation is hosted on [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/), with a mirror on [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/).
## Packages
| Package | Description |
-| :--- | :--- |
-| `iiwa_bringup` | Launch files: Webots simulation, real robot via FRI, MoveIt motion planning and RViz visualization |
-| `iiwa_config` | Configuration files: MoveIt, ros2_control controllers, kinematics and general system settings |
-| `iiwa_controller` | Hardware interface: real-time joint control via FRI within the ros2_control ecosystem |
-| `iiwa_description` | URDF/XACRO robot description and Webots world configuration |
-| `iiwa_msgs` | ROS 2 interfaces: action messages for joint-space and Cartesian motion, services for named poses |
-| `iiwa_planning` | Motion planning: C++ and Python nodes built on MoveIt 2 (OMPL, Pilz, moveit_py) |
-| `iiwa_utils` | System utilities: configuration loading, object and camera spawning in Webots, data conversion |
-| `iiwa_web` | Web interface for monitoring and remote control of the cobot via browser |
+|---|---|
+| `iiwa_bringup` | Launch files for Webots, the physical FRI robot, MoveIt, and RViz |
+| `iiwa_config` | MoveIt, `ros2_control`, kinematics, and shared configuration files |
+| `iiwa_controller` | Real-time FRI hardware interface for `ros2_control` |
+| `iiwa_description` | URDF/Xacro robot description, meshes, tools, and Webots worlds |
+| `iiwa_msgs` | ROS 2 actions and services for joint, Cartesian, and named-pose motions |
+| `iiwa_planning` | C++ and Python motion nodes based on MoveIt 2, OMPL, Pilz, and `moveit_py` |
+| `iiwa_utils` | Configuration loading, data conversion, and Webots object/camera utilities |
+| `iiwa_web` | REST API, WebSocket, and MCP interfaces for monitoring and external control |
----
+Java applications for KUKA Sunrise Cabinet live separately under `src/iiwa_sunrise` and are not part of the colcon build.
+
+## Safety
+
+Before commanding the physical robot, verify the work area, joint limits, active tool, load model, and selected control mode. LWC does not replace KUKA safety functions, a robotic-cell risk assessment, or operator supervision.
+
+## License
+
+This project is available under the [Apache License 2.0](LICENSE).
## Citation
-If you use this project in your work, please leave a star ⭐ and cite it:
+If you use the project in research or development, cite the repository:
```bibtex
@software{lightweight_cobot_2026,
@@ -124,15 +181,9 @@ If you use this project in your work, please leave a star ⭐ and cite it:
}
```
----
-
## Acknowledgements
-We gratefully acknowledge the support of the following organizations and grants:
-
| Organization | Notes |
-| :--- | :--- |
+|---|---|
| [Komsomolsk-on-Amur State University (KnAGU)](https://knastu.ru/) | Research was conducted at KnAGU |
| [Russian Science Foundation (RSF)](https://rscf.ru/) | Work supported by the Russian Science Foundation |
-| | |
-| | |