feat: transactional publish, composable hooks and simple safe defaults

README.md

@@ -13,6 +13,25 @@ Need the full rule-by-rule explanation? Read [Advanced configuration](./docs/ADV
 You have a private repo. You want a public one — without the secrets. This
 tool keeps them in sync. Automatically.
 
+## Project philosophy
+
+**Nothing to learn before it becomes useful.** Install it, run `init`, then use
+`scan` to check and `publish` to publish. The safe behavior is the default; the
+common path does not require memorizing flags, building pipelines, or learning
+Git internals.
+
+The same tool remains flexible when a project grows: `.gitpublic` lets you tune
+ignored files, replacements, allow-lists, branches, tags, hooks, CI output and
+remote layout without replacing the simple workflow.
+
+In practice:
+
+- easy to start;
+- safe by default;
+- one obvious command per action;
+- useful without configuration expertise;
+- universal enough for advanced private → public workflows.
+
 ## Quick start
 
 ```bash
@@ -254,3 +273,18 @@ git-private2public doctor
 the pre-push hook, and source/target remote access. Secret findings are always
 redacted and shown as type + location + safe prefix/suffix hint + length + short SHA-256 fingerprint; the
 matched credential itself is never printed.
+
+### Safe publication transactions
+
+`publish` records the current target branch SHA before sanitizing and uses an
+explicit `--force-with-lease` tied to that SHA. If somebody updates the public
+branch while the private history is being cleaned, publication stops instead
+of overwriting their work. After a successful push, the remote SHA is verified.
+Targets under 100 MiB are cloned and scanned again automatically; larger repos
+skip the extra clone but still receive SHA verification. Existing tags are
+never force-overwritten.
+
+For CI, `scan`, `publish --scan`, and `guard run` support `--format json`.
+
+The managed pre-push dispatcher can run both guard and auto-publish while
+preserving and chaining an existing user hook.

README.ru.md

@@ -13,6 +13,25 @@
 У тебя приватный репо. Нужен публичный — без секретов. Эта тулза держит их в
 синке. Автоматически.
 
+## Философия проекта
+
+**Чтобы получить пользу, не нужно сначала чему-то учиться.** Установил, запустил
+`init`, затем используешь `scan` для проверки и `publish` для публикации.
+Безопасное поведение включено по умолчанию: обычный сценарий не требует помнить
+кучу параметров, собирать конвейер или разбираться во внутренностях Git.
+
+Когда проект становится сложнее, тот же инструмент остаётся гибким: через
+`.gitpublic` можно настроить исключения, замены, allow-list, ветки, теги, hooks,
+CI-отчёты и схему remotes, не ломая простой основной сценарий.
+
+На практике это означает:
+
+- легко начать;
+- безопасно по умолчанию;
+- одна очевидная команда на одно действие;
+- полезно без экспертной настройки;
+- достаточно универсально для сложных private → public процессов.
+
 ## Быстрый старт
 
 ```bash
@@ -254,3 +273,18 @@ git-private2public doctor
 файлы правил, pre-push hook и доступ к source/target. Найденные секреты всегда
 редактируются: выводятся только тип, расположение, безопасная подсказка из префикса/последних 4 символов, длина и короткий SHA-256,
 само значение учётных данных в отчёт не попадает.
+
+### Безопасная транзакция публикации
+
+`publish` запоминает SHA целевой ветки до очистки и использует точный
+`--force-with-lease`. Если во время обработки кто-то обновил публичную ветку,
+публикация остановится и не затрёт чужие изменения. После push проверяется SHA
+на сервере. Репозитории меньше 100 МиБ автоматически клонируются и сканируются
+повторно; для больших выполняется проверка SHA без дополнительного клона.
+Существующие теги никогда не перезаписываются принудительно.
+
+Для CI команды `scan`, `publish --scan` и `guard run` поддерживают
+`--format json`.
+
+Управляемый pre-push dispatcher умеет одновременно запускать guard и
+автопубликацию, сохраняя и вызывая уже существующий пользовательский hook.