diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..be45d42
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to AstraDeploy are documented here.
+
+## [v0.1.0] - 2026-05-31
+
+### Added
+- Initial release architecture and installer core (`install.sh`) with:
+  - argument parsing and lifecycle orchestration;
+  - centralized preflight/install/post steps;
+  - root/sudo guardrails and safety checks;
+  - logs to `/var/log/astra-deploy/`;
+  - report callback with `started/step/success/failed` statuses.
+- Interactive beginner flow (`--easy`) and non-interactive automation flow (`--yes`, `--non-interactive`).
+- Service support for `systemd`, `tmux-systemd`, `screen`, and `none`.
+- Firewall wiring and port validation flow.
+- License and EULA acceptance flow:
+  - `--accept-license` (`--license`)
+  - `--accept-eula` (`--eula`).
+- Core support matrix with separate handlers for:
+  - `pmmp`, `paper`, `purpur`, `velocity`, `powernukkitx`.
+- Localization architecture with Russian and English locale files:
+  - `[locales/ru.sh](locales/ru.sh)`
+  - `[locales/en.sh](locales/en.sh)`.
+- `NetherGamesMC` core installer:
+  - PHP build selection (`--build`)
+  - PocketMine-MCPE source workflow (`--mc-version`)
+  - Composer/runtime preparation and source clone path.
+
+### Changed
+- Added explicit safety modes for existing directories:
+  - `--allow-existing`, `--backup-existing`, `--force-clean`.
+- Added dry-run simulation mode and debug mode.
+- Added versioned command aliases for compatibility (`--core-version`, legacy `--version`).
+
+### Fixed
+- Initial hardening for cleanup and service behavior across supported flows.
+
+### Known limitations
+- Support matrix for OS/package-manager is intentionally MVP-focused (mainly Debian/Ubuntu family first, with extension points for others).
+- `--update` path is implemented per-core where available.
+
diff --git a/README.md b/README.md
index bd0e30f..cf6796f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # AstraDeploy
 
+[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+[![Bash](https://img.shields.io/badge/Bash-4%2B-brightgreen)](https://www.gnu.org/software/bash/)
+[![Version](https://img.shields.io/badge/Version-v0.1.0-blue)](README.md)
+
 `AstraDeploy` is a Bash installer for Minecraft server cores (Java and Bedrock) with:
 
 - interactive beginner mode (`--easy`);
@@ -158,6 +162,28 @@ sudo bash install.sh \
 - `--locale en|ru` or `--lang en|ru`
 - script also reads `LANGUAGE` / `LANG` environment fallback
 
+## Troubleshooting
+
+- **Port is already in use**  
+  - Find the process by `lsof -i:<port>` and stop it, or choose a different `--port`.
+  - For non-standard setups, set `--port` to an available TCP/UDP port depending on the core.
+
+- **Installer stops on missing dependencies or package errors**  
+  - Re-run with `--debug` to inspect detected package manager and failed command.
+  - Ensure the host has internet access and package repositories are reachable.
+
+- **Permission denied while creating/changing files**  
+  - Run via `sudo`/`root` for privileged operations.
+  - Verify `--user` exists and has write permissions on `--dir`.
+
+- **Firewall was not configured automatically**  
+  - Installer prints a manual notice when `ufw`/`firewalld` is unavailable.
+  - Open ports manually in your system firewall before continuing.
+
+- **Report callback is not sent**  
+  - Callback failures are non-blocking.
+  - Validate URL/token and retry install with corrected `--report-url` and `--report-token`.
+
 ## Safety notes
 
 - Script is designed with guardrails but still executes privileged operations (packages/services/firewall/files).
@@ -175,3 +201,6 @@ See [`LICENSE`](LICENSE) for the full text and disclaimers.
 sudo bash install.sh --version
 ```
 
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md).
diff --git a/README.ru.md b/README.ru.md
index 4473613..7a77b32 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -1,5 +1,9 @@
 # AstraDeploy
 
+[![License](https://img.shields.io/badge/Лицензия-MIT-green)](LICENSE)
+[![Bash](https://img.shields.io/badge/Bash-4%2B-brightgreen)](https://www.gnu.org/software/bash/)
+[![Version](https://img.shields.io/badge/Version-v0.1.0-blue)](README.ru.md)
+
 `AstraDeploy` — это bash-инсталлятор для Minecraft ядер (Java и Bedrock) с акцентом на простую установку и автоматизацию:
 
 - режим для нубов (`--easy`);
@@ -158,6 +162,28 @@ sudo bash install.sh \
 - `--locale en|ru` или `--lang en|ru`
 - автоматический fallback из `LANGUAGE` / `LANG`
 
+## Устранение типовых проблем
+
+- **Порт уже занят**  
+  - Проверьте кто держит порт через `lsof -i:<порт>` и остановите процесс, или укажите другой `--port`.
+  - Убедитесь, что выбранный порт доступен по нужному протоколу (`tcp`/`udp`) для ядра.
+
+- **Ошибка установки зависимостей / пакетов**  
+  - Повторите запуск с `--debug`, это покажет обнаруженный пакетный менеджер и упавшую команду.
+  - Проверьте интернет и доступность репозиториев пакетов.
+
+- **Permission denied при создании/изменении файлов**  
+  - Запускайте как `root` (через `sudo`) для полномасштабной установки.
+  - Проверьте, что пользователь из `--user` существует и имеет права на директорию `--dir`.
+
+- **Firewall не открылся автоматически**  
+  - Если `ufw`/`firewalld` отсутствуют, скрипт сообщит про ручную настройку.
+  - Откройте порт вручную в вашей системе безопасности.
+
+- **Коллбэк репортов не отправляется**  
+  - Ошибки callback не останавливают установку.
+  - Проверьте URL/token и повторите с корректными `--report-url` и `--report-token`.
+
 ## Важные замечания
 
 - Скрипт работает с повышенными правами и может менять сервисы, firewall, пакеты, файлы.
@@ -175,3 +201,6 @@ sudo bash install.sh \
 sudo bash install.sh --version
 ```
 
+## Changelog
+
+См. [`CHANGELOG.md`](CHANGELOG.md).