docs: rewrite README, add user guide, sync CONFIG.md with code

- README.md: 324 -> 106 lines, clickable TOC, quick start, formats
  table, full check suite + CI; flags/env/YAML reference moved to docs
- docs/USER_GUIDE.md: new user guide (install, periods, users, export,
  email, monthly --commit cycle, 21-flag reference, troubleshooting)
- docs/CONFIG.md: clickable TOC + accuracy fixes verified against code
  (dedup logic was described backwards, missing report section in
  --init-config, conditional STARTTLS, full --config-path role,
  datetime --date ranges, --config override nuance, comment loss on
  --commit, default_to without default_from is ignored)
- client.py: dedup docstring/comment now match actual behavior

docs/CONFIG.md

@@ -1,5 +1,33 @@
 # Настройка redmine-reporter
 
+## Оглавление
+
+- [Источники конфигурации](#источники-конфигурации)
+- [YAML-конфиг](#yaml-конфиг)
+  - [Структура](#структура)
+  - [`redmine.verify_ssl` — проверка TLS-сертификата](#redmineverify_ssl--проверка-tls-сертификата)
+  - [`period.precision` — точность периода](#periodprecision--точность-периода)
+  - [`period.default_to` — необязательное окончание периода](#perioddefault_to--необязательное-окончание-периода)
+  - [Период по умолчанию — текущий месяц](#период-по-умолчанию--текущий-месяц)
+  - [`--date` — формат диапазона](#--date--формат-диапазона)
+  - [`--commit` — автофиксация периода](#--commit--автофиксация-периода)
+  - [`email` — настройка отправки по почте](#email--настройка-отправки-по-почте)
+  - [`--send` — отправка отчёта по email](#--send--отправка-отчёта-по-email)
+  - [`output` — путь и имя файла по умолчанию](#output--путь-и-имя-файла-по-умолчанию)
+  - [Подстановка переменных окружения](#подстановка-переменных-окружения)
+  - [`report` — настройки содержимого отчёта](#report--настройки-содержимого-отчёта)
+  - [`report.status_translation` — перевод статусов](#reportstatus_translation--перевод-статусов)
+- [Разрешение выходного пути](#разрешение-выходного-пути)
+- [Миграция с `.env` на YAML](#миграция-с-env-на-yaml)
+  - [Быстрый старт](#быстрый-старт)
+  - [Что делает `--init-config`](#что-делает---init-config)
+  - [Флаги миграции](#флаги-миграции)
+  - [Проверка после миграции](#проверка-после-миграции)
+  - [Сосуществование `.env` и YAML](#сосуществование-env-и-yaml)
+  - [Откат](#откат)
+- [`.env` (legacy)](#env-legacy)
+- [Безопасность](#безопасность)
+
 ## Источники конфигурации
 
 Приоритет, от высшего к низшему:
@@ -8,6 +36,9 @@
 CLI-флаги  >  переменные окружения  >  .env  >  YAML  >  кодовые дефолты
 ```
 
+Нюанс с `override` при автозагрузке `.env` и `--config` — см.
+[Сосуществование `.env` и YAML](#сосуществование-env-и-yaml).
+
 Если значение не задано на верхнем уровне, берётся уровень ниже. `.env` и YAML
 работают одновременно — можно оставить оба, можно удалить `.env` после миграции.
 
@@ -86,7 +117,7 @@ email:
 Определяет, как вычисляется следующий период после фиксации:
 
 - `date` (по умолчанию) — период с точностью до дня. Следующий запуск (после `--commit`) начинается со следующего дня.
-- `datetime` — период с точностью до секунды. При повторном запуске time entries с `created_on` и `updated_on` ранее `last_used.to` исключаются (AND-логика: запись исключается только если **оба** поля раньше cutoff). Это предотвращает дублирование при отправке отчёта внутри рабочего дня.
+- `datetime` — период с точностью до секунды. При повторном запуске time entries, у которых `created_on` или `updated_on` раньше `last_used.to`, исключаются: запись сохраняется, только если **оба** поля не раньше cutoff (AND-логика). Записи без дат (оба поля отсутствуют) сохраняются; если задано только одно поле, проверяется оно. Это предотвращает дублирование при отправке отчёта внутри рабочего дня. Cutoff применяется всегда, когда вычислен (`precision: datetime` и задан `last_used.to`) — в том числе при явном `--date`.
 
 `last_used.from` / `last_used.to` записываются автоматически при `--commit`. Вручную редактировать не требуется.
 
@@ -107,6 +138,10 @@ period:
 Аналогично работает `DEFAULT_TO_DATE`: если переменная не задана, а
 `DEFAULT_FROM_DATE` задана, конец периода = сегодня.
 
+Обратное не работает: `period.default_to` без `period.default_from` (и
+`DEFAULT_TO_DATE` без `DEFAULT_FROM_DATE`) игнорируется — период определяется
+остальными источниками.
+
 ### Период по умолчанию — текущий месяц
 
 Если период не задан ни одним из источников (`--date`, `DEFAULT_FROM_DATE`,
@@ -114,6 +149,17 @@ period:
 1-е число текущего месяца, конец — сегодняшняя дата. Период вычисляется
 на момент запуска и не хранится в коде или конфиге.
 
+### `--date` — формат диапазона
+
+Флаг `--date` принимает два формата:
+
+- Даты: `YYYY-MM-DD--YYYY-MM-DD` (например, `2026-06-01--2026-06-30`).
+- Datetime с секундами: `YYYY-MM-DDTHH:MM:SS--YYYY-MM-DDTHH:MM:SS`
+  (например, `2026-06-30T09:00:00--2026-06-30T12:00:00`).
+
+Обе границы должны быть в одном формате — смешанная точность отвергается.
+Начало позже конца (`start > end`) — ошибка.
+
 ### `--commit` — автофиксация периода
 
 Флаг `--commit` сохраняет использованный период в YAML-конфиг, чтобы следующий запуск автоматически начинался с нового периода.
@@ -135,6 +181,9 @@ period:
   - Произвольный диапазон → та же длительность, начиная со дня после `last_used.to`.
 - `dynamic: false` — `--commit` перезаписывает `default_from`/`default_to` на использованный период.
 
+**Нюанс:** при `--commit` YAML-файл перезаписывается целиком через `yaml.dump` —
+пользовательские комментарии и ручное форматирование в файле теряются.
+
 **Примеры:**
 
 ```bash
@@ -228,7 +277,8 @@ email:
 3. Формирует MIME-письмо:
    - Тема, plain-text тело и вложение (если `attach: true`).
    - При `email.html: true` — дополнительно HTML-версия тела (`multipart/alternative`), сгенерированная из таблицы отчёта.
-4. Отправляет через SMTP с TLS (таймаут 30 секунд).
+4. Отправляет через SMTP (таймаут 30 секунд). STARTTLS включается только при
+   `email.smtp.tls: true`; аутентификация — только если задан `email.smtp.user`.
 
 **Файл отчёта сохраняется до попытки отправки** — при ошибке SMTP файл остаётся
 на диске, данные не теряются.
@@ -398,7 +448,8 @@ vim ~/.config/redmine-reporter/config.yml
 ### Что делает `--init-config`
 
 - Читает текущие значения из `.env` и переменных окружения.
-- Формирует YAML со всеми секциями (`redmine`, `period`, `output`, `email`).
+- Формирует YAML со всеми секциями (`redmine`, `period`, `output`, `report`, `email`).
+- В конец файла дописывает закомментированный пример `report.status_translation`.
 - Секреты (`REDMINE_API_KEY`, `SMTP_PASSWORD`) записывает как `${VAR}`, если
   переменная существует, иначе — пустая строка.
 - Создаёт файл с правами `0600`, директорию — с `0700`.
@@ -409,7 +460,7 @@ vim ~/.config/redmine-reporter/config.yml
 |---|---|
 | `--init-config` | Создать YAML и выйти |
 | `--init-config --force` | Перезаписать существующий YAML |
-| `--config-path PATH` | Сохранить YAML по указанному пути (по умолчанию `~/.config/redmine-reporter/config.yml`) |
+| `--config-path PATH` | Путь к YAML-конфигу: загрузка при запуске, запись при `--init-config` и `--commit` (по умолчанию `~/.config/redmine-reporter/config.yml`) |
 
 Если `DEFAULT_TO_DATE` не задана, а `DEFAULT_FROM_DATE` задана, сгенерированный
 YAML будет содержать пустое `default_to`, и при запуске инструмент использует
@@ -441,6 +492,10 @@ ls -la ~/.config/redmine-reporter/
 YAML работает как базовый слой для всего, что не в .env
 ```
 
+Автозагрузка `.env` (без `--config`) не перебивает реальные переменные
+окружения (`override=False`). Исключение — `--config FILE`: указанный `.env`
+загружается с `override=True` и перебивает переменные окружения (но не CLI-флаги).
+
 Это safe — если с YAML что-то пойдёт не так, просто положи `.env` обратно.
 
 ### Откат