Improved integration ability

README.md

@@ -68,21 +68,59 @@ python main.py
 
 ## Запуск
 
-TODO
+Контейнер рассчитан на один запрос. Для каждого задания создайте отдельную
+директорию, положите в неё один поддерживаемый файл с именем `input.*` и
+смонтируйте её в `/work`:
+
+```bash
+JOB_DIR=$(mktemp -d)
+cp input.mkv "$JOB_DIR/input.mkv"
+
+docker run --rm --name sumka-example --gpus all -e AI_API_KEY \
+  --mount type=bind,src="$JOB_DIR",dst=/work \
+  --mount type=volume,src=whisper-cache,dst=/tmp/sumka-cache/whisper \
+  --tmpfs /tmp:rw,size=8g sumka:nvidia
+```
+
+Не запускайте два контейнера с одной рабочей директорией. Повторный запуск с
+той же директорией продолжит работу по уже созданным промежуточным файлам.
+Кэш Whisper можно безопасно разделять между заданиями.
+
+### Статус и логирование
+
+Приложение дописывает в `JOB_DIR/report.txt` по одной JSON-записи на строку.
+Записи появляются при старте и завершении этапа, а во время долгой операции —
+каждые 30 секунд. Интервал меняется через `--report-interval`.
+
+```json
+{"timestamp":"2026-09-24T12:00:00Z","run_id":"...","status":"running","step":"voice_recognition","step_index":2,"steps_total":10}
+{"timestamp":"2026-09-24T12:00:30Z","run_id":"...","status":"heartbeat","elapsed_seconds":30,"step":"voice_recognition","step_index":2,"steps_total":10}
+{"timestamp":"2026-09-24T12:10:00Z","run_id":"...","status":"succeeded","elapsed_seconds":600,"outputs":["output.md","output.pdf"]}
+```
+
+`status` принимает значения `started`, `running`, `step_completed`,
+`heartbeat`, `succeeded`, `failed` или `cancelled`. Файл не перезаписывается:
+повторный запуск добавляет записи с новым `run_id`. Смотреть его вручную можно
+через `tail -f "$JOB_DIR/report.txt"`.
+
+Matrix-боту рекомендуется запускать `docker run --rm --name <job-id>` через
+`subprocess.Popen`/`asyncio.create_subprocess_exec`, параллельно читать новые
+строки `report.txt` и разбирать их через `json.loads`. Код возврата контейнера
+остаётся окончательным признаком успеха: `0` — успех, ненулевой — ошибка или
+отмена. Подробные диагностические логи идут в stdout/stderr контейнера; для
+отмены задания можно выполнить `docker stop <job-id>`.
 
 ## Архитектура
 
 Предполагается, что приложение будет запускаться сторонним приложением всякий
 раз, когда требуется произвести конвертацию медиафайла в конспект (например,
-Telegram ботом, которому отправили видео).
+Matrix-ботом, которому отправили видео).
 
-**Сервис не сохраняет никаких данных между перезапусками**. Всё, что
-сохраняется - это промежуточные результаты. Например, если сервис сгенерировал
-файл `asr_events.json`, а после этого его принудительно завершили, то при
-следующем запуске он будет использовать этот файл, чтобы не повторять дорогие
-операции. **Поэтому при автоматизации рекомендуется на каждый новый запрос
-создавать новую промежуточную директорию, а старые директории удалять, когда они
-становятся не нужны.**
+**Сервис не хранит состояние вне рабочей директории.** Если сервис сгенерировал
+промежуточный файл, а после этого его принудительно завершили, то при следующем
+запуске он использует этот файл, чтобы не повторять дорогую операцию. **Поэтому
+для каждого нового запроса нужна новая рабочая директория; старые директории
+можно удалять, когда результат больше не нужен.**
 
 Алгоритм работы сервиса следующий:
 1. **Проверить, является входной файл звуком или видео со звуком**