diff --git a/manuals/content_publish.md b/manuals/content_publish.md
new file mode 100644
index 0000000..3015145
--- /dev/null
+++ b/manuals/content_publish.md
@@ -0,0 +1,77 @@
+# content_publish
+
+## Что делает
+
+Публикует файл из директории сессии для просмотра пользователем прямо в чате. Поддерживаются интерактивные viewer'ы для 3D-моделей (STL), HTML-страниц, SVG, PDF, изображений и видео.
+
+## Как работает внутри
+
+1. **Файл уже должен быть в директории сессии** (`uploads/sessions/{session_id}/`).
+2. Инструмент **не копирует** файл — он только регистрирует метаданные в базе данных.
+3. Пользователь видит файл по URL `/sessions/{session_id}/files/{filename}`.
+4. Если вы отредактируете файл после публикации, пользователь увидит изменения **сразу** (перезагружать страницу не нужно).
+
+## Формат вызова
+
+```python
+content_publish(
+    filename="мой_файл.svg",      # обязательно — имя файла в директории сессии
+    title="Моя диаграмма",        # опционально — заголовок карточки
+    content_type="svg"            # опционально — тип для viewer (автоопределение по расширению)
+)
+```
+
+## Где находится директория сессии
+
+Директория сессии — это `uploads/sessions/{session_id}/`. Полный путь зависит от настроек сервера.
+
+**Как узнать путь:**
+```
+filesystem info uploads/sessions/{session_id}
+```
+
+Или просто пишите файлы относительно текущей директории — если вы уже в рабочей директории, используйте полный путь через `filesystem write`.
+
+## Типичный workflow
+
+### 1. Создание и публикация
+
+```
+# Создать SVG в директории сессии
+filesystem write uploads/sessions/sess-abc/chart.svg "<svg>...</svg>"
+
+# Опубликовать
+content_publish(filename="chart.svg", title="Диаграмма продаж")
+```
+
+### 2. Редактирование после публикации
+
+```
+# Прочитать текущий файл
+filesystem read uploads/sessions/sess-abc/chart.svg
+
+# Отредактировать
+filesystem write uploads/sessions/sess-abc/chart.svg "<svg>...исправлено...</svg>"
+```
+
+Пользователь увидит изменения мгновенно — URL не меняется.
+
+## Поддерживаемые типы
+
+| Расширение | Тип | Viewer |
+|---|---|---|
+| `.stl` | 3D-модель | Three.js 3D viewer |
+| `.html`, `.htm` | HTML | iframe |
+| `.svg` | SVG | iframe |
+| `.pdf` | PDF | iframe |
+| `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | Изображение | img |
+| `.mp4`, `.webm` | Видео | video |
+
+Для неизвестных типов показывается карточка со ссылкой на скачивание.
+
+## Важные правила
+
+1. **Файл должен существовать ДО вызова** — `content_publish` не создаёт файлы, только регистрирует.
+2. **Проверяйте коллизии** — если файл с таким именем уже есть, он будет перезаписан при публикации.
+3. **Используйте понятные имена** — `chart.svg` лучше чем `file_1.svg`.
+4. **Для редактирования используйте тот же путь** — не создавайте новые копии, правьте оригинал.
diff --git a/navi/tools/content_publish.py b/navi/tools/content_publish.py
index 927e3c5..cfc258a 100644
--- a/navi/tools/content_publish.py
+++ b/navi/tools/content_publish.py
@@ -24,7 +24,12 @@
         "Before publishing, write or move the file into the session folder. "
         "To find the session directory path, use `filesystem info <path>` or write directly to it. "
         "If a file with the same name already exists in the session directory, choose a different name "
-        "or check the directory contents first with `filesystem list <session_dir>`."
+        "or check the directory contents first with `filesystem list <session_dir>`.\n\n"
+        "Best practices:\n"
+        "- Always create files in the session directory (uploads/sessions/{session_id}/)\n"
+        "- Use descriptive filenames (e.g., 'sales_chart.svg' not 'file.svg')\n"
+        "- After publishing, you can edit the file directly and the user will see changes immediately\n"
+        "- For images, use PNG or JPEG; for interactive content, use HTML or SVG"
     )
     parameters = {
         "type": "object",