diff --git a/readme.txt b/readme.txt
new file mode 100644
index 0000000..4cec38f
--- /dev/null
+++ b/readme.txt
@@ -0,0 +1,32 @@
+=== WP Multi City ===
+Contributors: vbryzgalov
+Tags: multisite, multi-city, taxonomy, acf, shortcode
+Requires at least: 6.0
+Tested up to: 6.9
+Requires PHP: 8.0
+Stable tag: 1.0.0
+License: GPLv2 or later
+
+Мультигородская подсистема: одна WP-инсталляция обслуживает несколько городов по схеме /{city}/{path}/ с подстановками контента и URL.
+
+== Description ==
+
+Решает задачу мультигородского сайта без WordPress Multisite. Один WP, единая БД, города представлены термами `town` таксономии. URL формы `/{city}/{path}/` патчат `$wp_query`, чтобы загрузить нужную страницу. Контент по городу подставляется через `[shortcode_dmr id=N]` (ACF repeater `list_shortcode`).
+
+Требует Advanced Custom Fields Pro.
+
+== Installation ==
+
+1. Загрузите архив wp-multi-city в `/wp-content/plugins/`.
+2. Активируйте плагин в WP admin → Plugins.
+3. Если ACF Pro не активен — увидите admin notice об ошибке зависимости.
+
+== Changelog ==
+
+= 1.0.0 =
+* Первый релиз. MVP-ядро завершено (S1–S7 эпика cp-cw4).
+* taxonomy town + CPT shortcode-town + ACF list_shortcode repeater.
+* [shortcode_dmr id=N] для подстановок по городу.
+* URL-роутер /{city}/{path}/ с поддержкой page_unic / main_page_alt / page_no_rep.
+* Глобальные фильтры the_title, home_url, post_link, acf/load_value, rest_url.
+* Self-hosted updates через Gitea + plugin-update-checker v5.6.