From 50262089e1b517663491c931070541599d049c83 Mon Sep 17 00:00:00 2001
From: Andrewkydev <grusha.belaev@gmail.com>
Date: Sun, 31 May 2026 13:45:11 +0300
Subject: [PATCH] docs: add core-specific usage guides (RU/EN)

---
 docs/USAGE.md    | 213 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/USAGE.ru.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 426 insertions(+)
 create mode 100644 docs/USAGE.md
 create mode 100644 docs/USAGE.ru.md

diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100644
index 0000000..3996ab8
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,213 @@
+# AstraDeploy Usage Guide
+
+Quick practical examples for each supported core.
+
+## Common rules
+
+- For interactive mode use:
+
+  ```bash
+  sudo bash install.sh --easy --core <core>
+  ```
+
+- For automation/bot mode always add:
+
+  ```bash
+  --yes --accept-license yes
+  ```
+
+- For Java cores also add:
+
+  ```bash
+  --accept-eula yes
+  ```
+
+- Always choose service mode explicitly for repeatable behaviour:
+
+  - `tmux-systemd` (recommended UX)
+  - `systemd`
+  - `screen`
+  - `none` (prepare only)
+
+## Java cores
+
+### Paper (`--core paper`)
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core paper --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core paper \
+    --dir /opt/minecraft/paper \
+    --service systemd \
+    --ram 4G \
+    --port 25565 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+### Purpur (`--core purpur`)
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core purpur --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core purpur \
+    --dir /opt/minecraft/purpur \
+    --service tmux-systemd \
+    --ram 4G \
+    --port 25565 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+### Velocity (`--core velocity`)
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core velocity --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core velocity \
+    --dir /opt/minecraft/velocity \
+    --service tmux-systemd \
+    --ram 2G \
+    --port 25577 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+### PowerNukkitX (`--core powernukkitx`)
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core powernukkitx --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core powernukkitx \
+    --dir /opt/minecraft/powernukkitx \
+    --service systemd \
+    --ram 2G \
+    --port 19132 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+## Bedrock PHP cores
+
+### PMMP (`--core pmmp`)
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core pmmp --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core pmmp \
+    --dir /opt/minecraft/pmmp \
+    --service tmux-systemd \
+    --port 19132 \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+### NetherGamesMC (`--core nethergamesmc`)
+
+Supports additional options:
+
+- `--build` — PHP build tag (`latest` or concrete tag).
+- `--mc-version` — PocketMine-MCPE tag (`latest` or specific).
+
+- Beginner:
+
+  ```bash
+  sudo bash install.sh --easy --core nethergamesmc --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core nethergamesmc \
+    --dir /opt/minecraft/nethergamesmc \
+    --service screen \
+    --build latest \
+    --mc-version latest \
+    --accept-license yes \
+    --firewall yes \
+    --locale en
+  ```
+
+### Recommended bot-facing step stream
+
+When reporting progress to users in a bot, send these checkpoints:
+
+1. "preflight"
+2. "package install"
+3. "core download/build"
+4. "service configured"
+5. "finished"
+
+You can use script output or report callback events:
+
+- `started`
+- `step`
+- `success`
+- `failed`
+
+## Update mode
+
+Use for replacing files on an existing server directory:
+
+```bash
+sudo bash install.sh \
+  --update \
+  --core <core> \
+  --dir /opt/minecraft/<core> \
+  --yes \
+  --accept-license yes
+```
+
+For Java cores add `--accept-eula yes`.
+
diff --git a/docs/USAGE.ru.md b/docs/USAGE.ru.md
new file mode 100644
index 0000000..945d89f
--- /dev/null
+++ b/docs/USAGE.ru.md
@@ -0,0 +1,213 @@
+# Руководство по использованию AstraDeploy
+
+Мини-гайды по каждому поддерживаемому ядру.
+
+## Общие правила
+
+- Для интерактива удобно:
+
+  ```bash
+  sudo bash install.sh --easy --core <core>
+  ```
+
+- Для автоматизации/бота обязательно добавляйте:
+
+  ```bash
+  --yes --accept-license yes
+  ```
+
+- Для Java-ядер ещё:
+
+  ```bash
+  --accept-eula yes
+  ```
+
+- Рекомендуется явно задавать режим сервиса:
+
+  - `tmux-systemd` (рекомендованный UX)
+  - `systemd`
+  - `screen`
+  - `none` (только подготовка)
+
+## Java-ядерные
+
+### Paper (`--core paper`)
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core paper --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core paper \
+    --dir /opt/minecraft/paper \
+    --service systemd \
+    --ram 4G \
+    --port 25565 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+### Purpur (`--core purpur`)
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core purpur --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core purpur \
+    --dir /opt/minecraft/purpur \
+    --service tmux-systemd \
+    --ram 4G \
+    --port 25565 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+### Velocity (`--core velocity`)
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core velocity --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core velocity \
+    --dir /opt/minecraft/velocity \
+    --service tmux-systemd \
+    --ram 2G \
+    --port 25577 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+### PowerNukkitX (`--core powernukkitx`)
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core powernukkitx --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core powernukkitx \
+    --dir /opt/minecraft/powernukkitx \
+    --service systemd \
+    --ram 2G \
+    --port 19132 \
+    --accept-eula yes \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+## Bedrock PHP-ядра
+
+### PMMP (`--core pmmp`)
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core pmmp --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core pmmp \
+    --dir /opt/minecraft/pmmp \
+    --service tmux-systemd \
+    --port 19132 \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+### NetherGamesMC (`--core nethergamesmc`)
+
+Доп. опции:
+
+- `--build` — тег PHP-билда (`latest` или конкретный).
+- `--mc-version` — версия/тег PocketMine-MCPE (`latest` или конкретный).
+
+- Easy:
+
+  ```bash
+  sudo bash install.sh --easy --core nethergamesmc --service tmux-systemd
+  ```
+
+- Non-interactive:
+
+  ```bash
+  sudo bash install.sh \
+    --yes \
+    --core nethergamesmc \
+    --dir /opt/minecraft/nethergamesmc \
+    --service screen \
+    --build latest \
+    --mc-version latest \
+    --accept-license yes \
+    --firewall yes \
+    --locale ru
+  ```
+
+### Рекомендуемый порядок статусов для бота
+
+Удобно отправлять пользователю:
+
+1. "preflight"
+2. "package install"
+3. "core download/build"
+4. "service configured"
+5. "finished"
+
+Или использовать callback:
+
+- `started`
+- `step`
+- `success`
+- `failed`
+
+## Режим обновления
+
+Для обновления уже установленного каталога:
+
+```bash
+sudo bash install.sh \
+  --update \
+  --core <core> \
+  --dir /opt/minecraft/<core> \
+  --yes \
+  --accept-license yes
+```
+
+Для Java-ядер добавляйте `--accept-eula yes`.
+