Merge pull request #605 from telemt/readme

Readme

CONTRIBUTING.md

@@ -1,19 +1,82 @@
-# Issues - Rules
+# Issues
+## Warnung
+Before opening Issue, if it is more question than problem or bug - ask about that [in our chat](https://t.me/telemtrs)
+
 ## What it is not
 - NOT Question and Answer
 - NOT Helpdesk
 
-# Pull Requests - Rules
+***Each of your Issues triggers attempts to reproduce problems and analyze them, which are done manually by people***
+
+---
+
+# Pull Requests
+
 ## General
 - ONLY signed and verified commits
 - ONLY from your name
-- DO NOT commit with `codex` or `claude` as author/commiter
+- DO NOT commit with `codex`, `claude`, or other AI tools as author/committer
 - PREFER `flow` branch for development, not `main`
 
-## AI
-We are not against modern tools, like AI, where you act as a principal or architect, but we consider it important:
+---
 
-- you really understand what you're doing
-- you understand the relationships and dependencies of the components being modified
-- you understand the architecture of Telegram MTProto, MTProxy, Middle-End KDF at least generically
-- you DO NOT commit for the sake of commits, but to help the community, core-developers and ordinary users
+## Definition of Ready (MANDATORY)
+
+A Pull Request WILL be ignored or closed if:
+
+- it does NOT build
+- it does NOT pass tests
+- it does NOT follow formatting rules
+- it contains unrelated or excessive changes
+- the author cannot clearly explain the change
+
+---
+
+## Blessed Principles
+- PR must build
+- PR must pass tests
+- PR must be understood by author
+
+---
+
+## AI Usage Policy
+
+AI tools (Claude, ChatGPT, Codex, DeepSeek, etc.) are allowed as **assistants**, NOT as decision-makers.
+
+By submitting a PR, you confirm that:
+
+- you fully understand the code you submit
+- you verified correctness manually
+- you reviewed architecture and dependencies
+- you take full responsibility for the change
+
+AI-generated code is treated as **draft** and must be validated like any other external contribution.
+
+PRs that look like unverified AI dumps WILL be closed
+
+---
+
+## Maintainer Policy
+
+Maintainers reserve the right to:
+
+- close PRs that do not meet basic quality requirements
+- request explanations before review
+- ignore low-effort contributions
+
+Respect the reviewers time
+
+---
+
+## Enforcement
+
+Pull Requests that violate project standards may be closed without review.
+
+This includes (but is not limited to):
+
+- non-building code
+- failing tests
+- unverified or low-effort changes
+- inability to explain the change
+
+These actions follow the Code of Conduct and are intended to preserve signal, quality, and Telemt's integrity

README.md

@@ -2,6 +2,8 @@
 
 ***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***
 
+[**Telemt Chat in Telegram**](https://t.me/telemtrs)
+
 **Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements such as:
 - [ME Pool + Reader/Writer + Registry + Refill + Adaptive Floor + Trio-State + Generation Lifecycle](https://github.com/telemt/telemt/blob/main/docs/model/MODEL.en.md)
 - [Full-covered API w/ management](https://github.com/telemt/telemt/blob/main/docs/API.md)
@@ -9,60 +11,6 @@
 - Prometheus-format Metrics
 - TLS-Fronting and TCP-Splicing for masking from "prying" eyes
 
-[**Telemt Chat in Telegram**](https://t.me/telemtrs)
-
-## NEWS and EMERGENCY
-### ✈️ Telemt 3 is released!
-<table>
-<tr>
-<td width="50%" valign="top">
-
-### 🇷🇺 RU
-
-#### О релизах
-
-[3.3.27](https://github.com/telemt/telemt/releases/tag/3.3.27) даёт баланс стабильности и передового функционала, а так же последние исправления по безопасности и багам
-
-Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **API**, **статистики**, **UX**
-
----
-
-Если у вас есть компетенции в:
-
-- Асинхронных сетевых приложениях  
-- Анализе трафика  
-- Реверс-инжиниринге  
-- Сетевых расследованиях  
-
-Мы открыты к архитектурным предложениям, идеям и pull requests
-</td>
-<td width="50%" valign="top">
-
-### 🇬🇧 EN
-
-#### About releases
-
-[3.3.27](https://github.com/telemt/telemt/releases/tag/3.3.27) provides a balance of stability and advanced functionality, as well as the latest security and bug fixes
-
-We are looking forward to your feedback and improvement proposals — especially regarding **API**, **statistics**, **UX**
-
----
-
-If you have expertise in:
-
-- Asynchronous network applications  
-- Traffic analysis  
-- Reverse engineering  
-- Network forensics  
-
-We welcome ideas, architectural feedback, and pull requests.
-</td>
-</tr>
-</table>
-
-# Features
-💥 The configuration structure has changed since version 1.1.0.0. change it in your environment!
-
 ⚓ Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](#recognizability-for-dpi-and-crawler)
 
 ⚓ Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual

docs/FAQ.en.md

@@ -1,113 +1,122 @@
-## How to set up "proxy sponsor" channel and statistics via @MTProxybot bot
+## How to set up a "proxy sponsor" channel and statistics via the @MTProxybot
 
-1. Go to @MTProxybot bot.
-2. Enter the command `/newproxy`
-3. Send the server IP and port. For example: 1.2.3.4:443
-4. Open the config `nano /etc/telemt/telemt.toml`.
-5. Copy and send the user secret from the [access.users] section to the bot.
-6. Copy the tag received from the bot. For example 1234567890abcdef1234567890abcdef.
+1. Go to the @MTProxybot.
+2. Enter the `/newproxy` command.
+3. Send your server's IP address and port. For example: `1.2.3.4:443`.
+4. Open the configuration file: `nano /etc/telemt/telemt.toml`.
+5. Copy and send the user secret from the `[access.users]` section to the bot.
+6. Copy the tag provided by the bot. For example: `1234567890abcdef1234567890abcdef`.
 > [!WARNING]
 > The link provided by the bot will not work. Do not copy or use it!
-7. Uncomment the ad_tag parameter and enter the tag received from the bot.
-8. Uncomment/add the parameter `use_middle_proxy = true`.
+7. Uncomment the `ad_tag` parameter and enter the tag received from the bot.
+8. Uncomment or add the `use_middle_proxy = true` parameter.
 
-Config example:
+Configuration example:
 ```toml
 [general]
 ad_tag = "1234567890abcdef1234567890abcdef"
 use_middle_proxy = true
 ```
-9. Save the config. Ctrl+S -> Ctrl+X.
-10. Restart telemt `systemctl restart telemt`.
-11. In the bot, send the command /myproxies and select the added server.
+9. Save the changes (in nano: Ctrl+S -> Ctrl+X).
+10. Restart the telemt service: `systemctl restart telemt`.
+11. Send the `/myproxies` command to the bot and select the added server.
 12. Click the "Set promotion" button.
 13. Send a **public link** to the channel. Private channels cannot be added!
-14. Wait approximately 1 hour for the information to update on Telegram servers.
+14. Wait for about 1 hour for the information to update on Telegram servers.
 > [!WARNING]
-> You will not see the "proxy sponsor" if you are already subscribed to the channel.
+> The sponsored channel will not be displayed to you if you are already subscribed to it.
 
-**You can also set up different channels for different users.**
+**You can also configure different sponsored channels for different users:**
 ```toml
 [access.user_ad_tags]
 hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
 
-## Why is middle proxy (ME) needed
+## Why do you need a middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167
 
-## How many people can use 1 link
 
-By default, 1 link can be used by any number of people.  
-You can limit the number of IPs using the proxy.
+## How many people can use one link
+
+By default, an unlimited number of people can use a single link.  
+However, you can limit the number of unique IP addresses for each user:
 ```toml
 [access.user_max_unique_ips]
 hello = 1
 ```
-This parameter limits how many unique IPs can use 1 link simultaneously. If one user disconnects, a second user can connect. Also, multiple users can sit behind the same IP.
+This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect. At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
 
 ## How to create multiple different links
 
-1. Generate the required number of secrets `openssl rand -hex 16`
-2. Open the config `nano /etc/telemt.toml`
-3. Add new users.
+1. Generate the required number of secrets using the command: `openssl rand -hex 16`.
+2. Open the configuration file: `nano /etc/telemt/telemt.toml`.
+3. Add new users to the `[access.users]` section:
 ```toml
 [access.users]
 user1 = "00000000000000000000000000000001"
 user2 = "00000000000000000000000000000002"
 user3 = "00000000000000000000000000000003"
 ```
-4. Save the config. Ctrl+S -> Ctrl+X. You don't need to restart telemt.
-5. Get the links via
+4. Save the configuration (Ctrl+S -> Ctrl+X). There is no need to restart the telemt service.
+5. Get the ready-to-use links using the command:
 ```bash
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
-## "Unknown TLS SNI" Error
-You probably updated tls_domain, but users are still connecting via old links with the previous domain.
+## "Unknown TLS SNI" error
+Usually, this error occurs if you have changed the `tls_domain` parameter, but users continue to connect using old links with the previous domain.
+
+If you need to allow connections with any domains (ignoring SNI mismatches), add the following parameters:
+```toml
+[censorship]
+unknown_sni_action = "mask"
+```
 
 ## How to view metrics
 
-1. Open the config `nano /etc/telemt/telemt.toml`
-2. Add the following parameters
+1. Open the configuration file: `nano /etc/telemt/telemt.toml`.
+2. Add the following parameters:
 ```toml
 [server]
 metrics_port = 9090
 metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 ```
-3. Save the config. Ctrl+S -> Ctrl+X.
-4. Metrics are available at SERVER_IP:9090/metrics.
+3. Save the changes (Ctrl+S -> Ctrl+X).
+4. After that, metrics will be available at: `SERVER_IP:9090/metrics`. 
 > [!WARNING]
-> "0.0.0.0/0" in metrics_whitelist opens access from any IP. Replace with your own IP. For example "1.2.3.4"
+> The value `"0.0.0.0/0"` in `metrics_whitelist` opens access to metrics from any IP address. It is recommended to replace it with your personal IP, for example: `"1.2.3.4/32"`.
 
 ## Additional parameters
 
-### Domain in link instead of IP
-To specify a domain in the links, add to the `[general.links]` section of the config file.
+### Domain in the link instead of IP
+To display a domain instead of an IP address in the connection links, add the following lines to the configuration file:
 ```toml
 [general.links]
 public_host = "proxy.example.com"
 ```
 
-### Server connection limit
-Limits the total number of open connections to the server:
+### Total server connection limit
+This parameter limits the total number of active connections to the server:
 ```toml
 [server]
 max_connections = 10000    # 0 - unlimited, 10000 - default
 ```
 
 ### Upstream Manager
-To specify an upstream, add to the `[[upstreams]]` section of the config.toml file:
-#### Binding to IP
+To configure outbound connections (upstreams), add the corresponding parameters to the `[[upstreams]]` section of the configuration file:
+
+#### Binding to an outbound IP address
 ```toml
 [[upstreams]]
 type = "direct"
 weight = 1
 enabled = true
-interface = "192.168.1.100" # Change to your outgoing IP
+interface = "192.168.1.100" # Replace with your outbound IP
 ```
-#### SOCKS4/5 as Upstream
-- Without authentication:
+
+#### Using SOCKS4/5 as an Upstream
+- Without authorization:
 ```toml
 [[upstreams]]
 type = "socks5"            # Specify SOCKS4 or SOCKS5
@@ -116,7 +125,7 @@ weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
 
-- With authentication:
+- With authorization:
 ```toml
 [[upstreams]]
 type = "socks5"            # Specify SOCKS4 or SOCKS5
@@ -127,8 +136,8 @@ weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
 
-#### Shadowsocks as Upstream
-Requires `use_middle_proxy = false`.
+#### Using Shadowsocks as an Upstream
+For this method to work, the `use_middle_proxy = false` parameter must be set.
 
 ```toml
 [general]

docs/FAQ.ru.md

@@ -1,32 +1,32 @@
 ## Как настроить канал "спонсор прокси" и статистику через бота @MTProxybot
 
-1. Зайти в бота @MTProxybot.
-2. Ввести команду `/newproxy`
-3. Отправить IP и порт сервера. Например: 1.2.3.4:443
-4. Открыть конфиг `nano /etc/telemt/telemt.toml`.
-5. Скопировать и отправить боту секрет пользователя из раздела [access.users].
-6. Скопировать полученный tag у бота. Например 1234567890abcdef1234567890abcdef.
+1. Зайдите в бота @MTProxybot.
+2. Введите команду `/newproxy`.
+3. Отправьте IP-адрес и порт сервера. Например: `1.2.3.4:443`.
+4. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
+5. Скопируйте и отправьте боту секрет пользователя из раздела `[access.users]`.
+6. Скопируйте тег (tag), который выдаст бот. Например: `1234567890abcdef1234567890abcdef`.
 > [!WARNING]
-> Ссылка, которую выдает бот, не будет работать. Не копируйте и не используйте её!
-7. Раскомментировать параметр ad_tag и вписать tag, полученный у бота.
-8. Раскомментировать/добавить параметр use_middle_proxy = true.
+> Ссылка, которую выдает бот, работать не будет. Не копируйте и не используйте её!
+7. Раскомментируйте параметр `ad_tag` и впишите тег, полученный от бота.
+8. Раскомментируйте или добавьте параметр `use_middle_proxy = true`.
 
-Пример конфига:
+Пример конфигурации:
 ```toml
 [general]
 ad_tag = "1234567890abcdef1234567890abcdef"
 use_middle_proxy = true
 ```
-9.  Сохранить конфиг. Ctrl+S -> Ctrl+X.
-10. Перезапустить telemt `systemctl restart telemt`.
-11. В боте отправить команду /myproxies и выбрать добавленный сервер.
-12. Нажать кнопку "Set promotion".
-13. Отправить **публичную ссылку** на канал. Приватный канал добавить нельзя!
-14. Подождать примерно 1 час, пока информация обновится на серверах Telegram.
+9. Сохраните изменения (в nano: Ctrl+S -> Ctrl+X).
+10. Перезапустите службу telemt: `systemctl restart telemt`.
+11. В боте отправьте команду `/myproxies` и выберите добавленный сервер.
+12. Нажмите кнопку «Set promotion».
+13. Отправьте **публичную ссылку** на канал. Приватные каналы добавлять нельзя!
+14. Подождите примерно 1 час, пока информация обновится на серверах Telegram.
 > [!WARNING]
-> У вас не будет отображаться "спонсор прокси" если вы уже подписаны на канал.
+> Спонсорский канал не будет у вас отображаться, если вы уже на него подписаны.
 
-**Также вы можете настроить разные каналы для разных пользователей.**
+**Вы также можете настроить разные спонсорские каналы для разных пользователей:**
 ```toml
 [access.user_ad_tags]
 hello = "ad_tag"
@@ -37,77 +37,85 @@ hello2 = "ad_tag2"
 https://github.com/telemt/telemt/discussions/167
 
 
-## Сколько человек может пользоваться 1 ссылкой
+## Сколько человек может пользоваться одной ссылкой
 
-По умолчанию 1 ссылкой может пользоваться сколько угодно человек.  
-Вы можете ограничить число IP, использующих прокси.
+По умолчанию одной ссылкой может пользоваться неограниченное число людей.  
+Однако вы можете ограничить количество уникальных IP-адресов для каждого пользователя:
 ```toml
 [access.user_max_unique_ips]
 hello = 1
 ```
-Этот параметр ограничивает, сколько уникальных IP может использовать 1 ссылку одновременно. Если один пользователь отключится, второй сможет подключиться. Также с одного IP может сидеть несколько пользователей.
+Этот параметр задает максимальное количество уникальных IP-адресов, с которых можно одновременно использовать одну ссылку. Если первый пользователь отключится, второй сможет подключиться. При этом с одного IP-адреса могут подключаться несколько пользователей одновременно (например, устройства в одной Wi-Fi сети).
 
-## Как сделать несколько разных ссылок
+## Как создать несколько разных ссылок
 
-1. Сгенерируйте нужное число секретов `openssl rand -hex 16`
-2. Открыть конфиг `nano /etc/telemt.toml`
-3. Добавить новых пользователей.
+1. Сгенерируйте необходимое количество секретов с помощью команды: `openssl rand -hex 16`.
+2. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
+3. Добавьте новых пользователей в секцию `[access.users]`:
 ```toml
 [access.users]
 user1 = "00000000000000000000000000000001"
 user2 = "00000000000000000000000000000002"
 user3 = "00000000000000000000000000000003"
 ```
-4. Сохранить конфиг. Ctrl+S -> Ctrl+X. Перезапускать telemt не нужно.
-5. Получить ссылки через
+4. Сохраните конфигурацию (Ctrl+S -> Ctrl+X). Перезапускать службу telemt не нужно.
+5. Получите готовые ссылки с помощью команды:
 ```bash
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
 ## Ошибка "Unknown TLS SNI"
-Возможно, вы обновили tls_domain, но пользователи всё ещё пытаются подключаться по старым ссылкам с прежним доменом.
+Обычно эта ошибка возникает, если вы изменили параметр `tls_domain`, но пользователи продолжают подключаться по старым ссылкам с прежним доменом.
+
+Если необходимо разрешить подключение с любыми доменами (игнорируя несовпадения SNI), добавьте следующие параметры:
+```toml
+[censorship]
+unknown_sni_action = "mask"
+```
 
 ## Как посмотреть метрики
 
-1. Открыть конфиг `nano /etc/telemt/telemt.toml`
-2. Добавить следующие параметры
+1. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
+2. Добавьте следующие параметры:
 ```toml
 [server]
 metrics_port = 9090
 metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 ```
-3. Сохранить конфиг. Ctrl+S -> Ctrl+X.
-4. Метрики доступны по адресу SERVER_IP:9090/metrics. 
+3. Сохраните изменения (Ctrl+S -> Ctrl+X).
+4. После этого метрики будут доступны по адресу: `SERVER_IP:9090/metrics`. 
 > [!WARNING]
-> "0.0.0.0/0" в metrics_whitelist открывает доступ с любого IP. Замените на свой ip. Например "1.2.3.4"
+> Значение `"0.0.0.0/0"` в `metrics_whitelist` открывает доступ к метрикам с любого IP-адреса. Рекомендуется заменить его на ваш личный IP, например: `"1.2.3.4/32"`.
 
 ## Дополнительные параметры
 
 ### Домен в ссылке вместо IP
-Чтобы указать домен в ссылках, добавьте в секцию `[general.links]` файла config.
+Чтобы в ссылках для подключения отображался домен вместо IP-адреса, добавьте следующие строки в файл конфигурации:
 ```toml
 [general.links]
 public_host = "proxy.example.com"
 ```
 
 ### Общий лимит подключений к серверу
-Ограничивает общее число открытых подключений к серверу:
+Этот параметр ограничивает общее количество активных подключений к серверу:
 ```toml
 [server]
-max_connections = 10000    # 0 - unlimited, 10000 - default
+max_connections = 10000    # 0 - без ограничений, 10000 - по умолчанию
 ```
 
 ### Upstream Manager
-Чтобы указать апстрим, добавьте в секцию `[[upstreams]]` файла config.toml:
-#### Привязка к IP
+Для настройки исходящих подключений (апстримов) добавьте соответствующие параметры в секцию `[[upstreams]]` файла конфигурации:
+
+#### Привязка к исходящему IP-адресу
 ```toml
 [[upstreams]]
 type = "direct"
 weight = 1
 enabled = true
-interface = "192.168.1.100" # Change to your outgoing IP
+interface = "192.168.1.100" # Замените на ваш исходящий IP
 ```
-#### SOCKS4/5 как Upstream
+
+#### Использование SOCKS4/5 в качестве Upstream
 - Без авторизации:
 ```toml
 [[upstreams]]
@@ -128,8 +136,8 @@ weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
 
-#### Shadowsocks как Upstream
-Требует `use_middle_proxy = false`.
+#### Использование Shadowsocks в качестве Upstream
+Для работы этого метода требуется установить параметр `use_middle_proxy = false`.
 
 ```toml
 [general]