diff --git a/README.md b/README.md
index 0848870d..e711e4e8 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,56 @@ Gitmost follows the upstream Docmost setup. See the Docmost
 [documentation](https://docmost.com/docs) for self-hosting and development instructions; replace the
 `docmost/docmost` image with `ghcr.io/vvzvlad/gitmost` where applicable.
 
+## Migration from Docmost
+
+Gitmost's database schema is a **strict superset** of Docmost's. Every Gitmost-specific migration
+only **adds** new tables (`page_embeddings`, `ai_chats`, `ai_chat_messages`,
+`ai_provider_credentials`, `ai_mcp_servers`) and **nullable** columns — it never drops or rewrites
+existing Docmost data. Migrations run automatically on startup, so migrating an existing Docmost
+instance is essentially **two image swaps**.
+
+The only hard requirement is the database image: the AI agent's RAG storage needs the
+[pgvector](https://github.com/pgvector/pgvector) extension (`CREATE EXTENSION vector`), which the
+stock `postgres` image does not ship. Swap it for `pgvector/pgvector:pgNN` — the same vanilla
+Postgres plus pgvector bundled, built on the official `postgres` image and fully data-compatible
+with it.
+
+### From a current Docmost on Postgres 18
+
+If your Docmost already runs `postgres:18`, it's a clean **in-place** swap — no dump/restore needed,
+the existing data directory is reused as-is:
+
+```diff
+ services:
+   docmost:
+-    image: docmost/docmost:latest
++    image: ghcr.io/vvzvlad/gitmost:latest
+     ...
+   db:
+-    image: postgres:18
++    image: pgvector/pgvector:pg18
+```
+
+`APP_SECRET`, `DATABASE_URL`, `REDIS_URL` and the storage volume stay unchanged. On the first
+start the new migrations apply on top of your existing schema (`CREATE EXTENSION vector` plus the
+`page_embeddings` and AI tables); watch the logs for `Migration "..." executed successfully`.
+
+### Notes
+
+- **Back up first.** Take a `pg_dump` before swapping — migrations apply in place, and the
+  container exits if a migration fails.
+- **Volume layout is identical.** `pgvector/pgvector` is built on the official `postgres` image and
+  uses the same `PGDATA`, so keep your existing data volume and its mount path unchanged — the swap
+  reuses the directory as-is.
+- **Match the Postgres major.** A Postgres data directory is not compatible across major versions.
+  If your Docmost runs an older major (e.g. Postgres 16), use the matching `pgvector/pgvector:pg16`
+  to keep the in-place swap, or move the data with `pg_dump` / `pg_restore` into the new instance.
+- **Managed Postgres.** If you don't use the bundled `db` container, make sure pgvector is available
+  and your database role is allowed to run `CREATE EXTENSION vector`.
+- **AI is opt-in.** The `page_embeddings` table stays empty until you configure an AI provider;
+  existing pages are indexed on their next edit. pgvector is still required for the migration to
+  apply at all.
+
 ## Features
 
 - Real-time collaboration
diff --git a/README.ru.md b/README.ru.md
index 8add239e..e9e2c0aa 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -121,6 +121,41 @@ Gitmost повторяет процесс установки upstream-Docmost. 
 смотрите в [документации](https://docmost.com/docs) Docmost; где это применимо, заменяйте образ
 `docmost/docmost` на `ghcr.io/vvzvlad/gitmost`.
 
+## Миграция с Docmost
+
+Схема БД Gitmost — это **строгий superset** схемы Docmost. Все Gitmost-специфичные миграции только
+**добавляют** новые таблицы (`page_embeddings`, `ai_chats`, `ai_chat_messages`,
+`ai_provider_credentials`, `ai_mcp_servers`) и **nullable**-колонки — они никогда не удаляют и не
+переписывают существующие данные Docmost. Миграции применяются автоматически при старте, поэтому
+миграция существующего инстанса Docmost — это по сути **замена двух образов**.
+
+Единственное жёсткое требование — образ БД: RAG-хранилище AI-агента использует расширение
+[pgvector](https://github.com/pgvector/pgvector) (`CREATE EXTENSION vector`), которого нет в
+стоковом образе `postgres`. Замените его на `pgvector/pgvector:pgNN` — это тот же ванильный
+Postgres со встроенным pgvector, собранный на базе официального образа `postgres` и полностью
+data-совместимый с ним.
+
+### С текущего Docmost на Postgres 18
+
+Если ваш Docmost уже работает на `postgres:18`, это чистая замена in-place — без
+dump/restore, существующий каталог данных переиспользуется как есть:
+
+```diff
+ services:
+   docmost:
+-    image: docmost/docmost:latest
++    image: ghcr.io/vvzvlad/gitmost:latest
+     ...
+   db:
+-    image: postgres:18
++    image: pgvector/pgvector:pg18
+```
+
+`APP_SECRET`, `DATABASE_URL`, `REDIS_URL` и том сторейджа остаются прежними. При первом запуске
+новые миграции применяются поверх вашей схемы (`CREATE EXTENSION vector` плюс таблицы
+`page_embeddings` и AI-таблицы); следите в логах за строками `Migration "..." executed successfully`.
+
+
 ## Возможности
 
 - Совместная работа в реальном времени