Make 'both files' the default; rename suffix convention

sedelev · sedelev · commit a5f32eed333d · 2026-05-07T12:40:43.000+03:00
Behaviour change: 'claude-backup export &lt;id&gt;' now writes two files by default:
  &lt;date&gt;--&lt;id&gt;.md       — clean dialogue (was previously .minimal.md)
  &lt;date&gt;--&lt;id&gt;.full.md  — audit copy with tool calls (was previously the unsuffixed .md)

The default is dual-output because that's what users actually want: an
unsuffixed .md they can open and re-read like a chat log, and a .full.md
sitting next to it as the safety net for debugging or auditing the agent.

Old --minimal boolean is replaced by --mode {both,minimal,full}; default is
'both'. This is a clean break — the prior --minimal flag shipped less than
24 hours ago and had no users beyond the author.

Filename convention rationale: the version a user usually wants is the one
with no suffix (it's the 90% case). The audit copy carries the .full.md
suffix because it's the opt-in detail view. This reverses what the previous
release did, where .minimal.md was the suffixed special case.

CLI:
- export and export-all now accept --mode {both,minimal,full} (default both)
- both subcommands list each written path (so 'both' prints two lines)
- removed --minimal entirely

API:
- export_session() returns list[Path] (was Path)
- export_session(mode='both'|'minimal'|'full'); raises ValueError otherwise
- render_markdown() unchanged

Tests: 68/68 pass, 91% coverage. Updated existing tests for new filenames
and added new tests for each of the three --mode values, plus invalid mode
handling.

Docs: README, README.ru, QUICKSTART all updated. QUICKSTART now leads with
'two files by default' and a small table contrasting their use cases.
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -76,9 +76,17 @@ You'll see:
 
 ```
 Exported: backups/2026-05-07--abc12345-...md
+Exported: backups/2026-05-07--abc12345-...full.md
 ```
 
-Open that `.md` file in any text editor. It looks like this:
+**Two files** are written by default:
+
+| File | What's inside | When to use |
+|------|---------------|-------------|
+| `2026-05-07--abc12345-….md` | The conversation: your prompts + Claude's text replies, nothing else | Re-reading later, archiving, sharing |
+| `2026-05-07--abc12345-….full.md` | Everything: every tool call, every shell command, every internal reasoning step | Debugging or auditing what the agent actually did |
+
+Open the `.md` file in any text editor — that's the readable one. It looks like this:
 
 ```markdown
 ---
@@ -88,6 +96,7 @@ branch: main
 model: claude-sonnet-4-6
 messages: 42
 exported_at: 2026-05-07T15:30:00Z
+mode: dialogue-only
 title: Fix the login bug
 ---
 
@@ -102,29 +111,32 @@ fix the login bug
 Here's the fix...
 ```
 
+The `.full.md` file looks similar but includes lines like `## Assistant (10:42:51)\n[tool_use: Edit]` followed by `## User (10:42:52)\nFile updated.` — the agent's tool plumbing.
+
 ---
 
-## Step 5 — Export the mini-log version (just the dialogue)
+## Step 5 — Want only one of the two files?
 
-The default export captures **everything** — your prompts, Claude's replies, and every tool call (file reads, shell commands, etc.) plus their outputs. Useful for an audit trail, but noisy if you just want to read the conversation later.
+```bash
+# Only the clean conversation
+claude-backup export abc12345 --output ./backups/ --mode minimal
 
-For a clean transcript with only your messages and Claude's text replies, add `--minimal`:
+# Only the audit copy
+claude-backup export abc12345 --output ./backups/ --mode full
 
-```bash
-claude-backup export abc12345 --output ./backups/ --minimal
+# Both (default — same as no flag)
+claude-backup export abc12345 --output ./backups/ --mode both
 ```
 
-This writes a separate file with `.minimal.md` suffix. Tool calls, tool results, and Claude's internal reasoning are dropped. Typically the mini-log is **30–50% the size** of the full export and reads like a normal chat log.
-
-You can have both versions of the same session — they don't overwrite each other.
+The clean version is typically **half the size** of the audit copy and is what you'll usually want.
 
 ---
 
 ## Step 6 — Export everything at once
 
 ```bash
-claude-backup export-all --output ./backups/                # full mode
-claude-backup export-all --output ./backups/ --minimal      # mini-log of every session
+claude-backup export-all --output ./backups/                    # both files per session
+claude-backup export-all --output ./backups/ --mode minimal     # only the clean .md files
 ```
 
 Each project gets its own subfolder under `./backups/`. You now have a complete Markdown archive of your Claude Code history.
diff --git a/README.md b/README.md
@@ -50,11 +50,14 @@ claude-backup export f7a07eec --output ~/claude-backups/
 
 # Export everything (each project gets its own subfolder)
 claude-backup export-all --output ~/claude-backups/
-
-# Mini-log: only your messages and Claude's text replies, no tool calls
-claude-backup export f7a07eec --output ~/claude-backups/ --minimal
 ```
 
+By default each export produces **two files** side-by-side:
+- `<date>--<id>.md` — clean dialogue (your prompts + Claude's text replies)
+- `<date>--<id>.full.md` — full audit copy with tool calls, tool results, and reasoning
+
+If you only want one of them, pass `--mode minimal` or `--mode full`.
+
 New users: see [QUICKSTART.md](./QUICKSTART.md) for the full step-by-step guide (macOS, Linux, Windows/WSL).
 
 ---
@@ -96,23 +99,31 @@ Documents/Claude  f7a07eec  Build claude-backup CLI tool with export      296
 claude-backup export f7a07eec --output ./backups/
 ```
 
-Writes `./backups/2026-05-07--f7a07eec-<full-uuid>.md`. **You only need the first 8 characters of the session ID** — the tool resolves the prefix.
+By default writes two files into `./backups/`:
+
+```
+2026-05-07--f7a07eec-<full-uuid>.md       ← clean dialogue, the one you'd open to re-read
+2026-05-07--f7a07eec-<full-uuid>.full.md  ← audit copy with every tool call and result
+```
 
-### Mini-log mode (`--minimal`)
+**You only need the first 8 characters of the session ID** — the tool resolves the prefix.
 
-When you just want a clean transcript of the conversation — your prompts and Claude's text replies — without tool calls, tool results, or extended-thinking blocks:
+### Choosing one or both files (`--mode`)
 
-```bash
-claude-backup export f7a07eec --output ./backups/ --minimal
-```
+| Flag | Output |
+|------|--------|
+| _(default)_ | both `<id>.md` and `<id>.full.md` |
+| `--mode minimal` | only `<id>.md` (clean dialogue) |
+| `--mode full` | only `<id>.full.md` (audit copy) |
 
-Writes a separate file with a `.minimal.md` suffix, so the full and minimal exports can coexist for the same session. Frontmatter records `mode: dialogue-only` and an adjusted `messages` count. Typically the minimal file is 30–50% the size of the full one.
+The `.md` file is the version you'll usually open — typically half the size of the audit copy and reads like a normal chat log. The `.full.md` is the safety net: every tool call, every shell output, every internal reasoning step — useful when you actually need to debug what the agent did.
 
 ### Export everything
 
 ```bash
-claude-backup export-all --output ./backups/
-claude-backup export-all --output ./backups/ --minimal   # mini-log version of all sessions
+claude-backup export-all --output ./backups/                    # both files per session
+claude-backup export-all --output ./backups/ --mode minimal     # only the clean .md files
+claude-backup export-all --output ./backups/ --mode full        # only the .full.md audit copies
 ```
 
 Each project gets its own subdirectory under `--output`.
@@ -163,7 +174,7 @@ I'll create the utility according to the spec...
 ...
 ```
 
-`--minimal` mode produces the same frontmatter (with `mode: dialogue-only` added) but the body contains only `## User` and `## Assistant` text turns — no `[tool_use: ...]` markers, no tool-result echoes, no thinking blocks.
+The `<id>.md` file (default and `--mode minimal`) shares the same frontmatter — plus `mode: dialogue-only` — but the body contains only `## User` and `## Assistant` text turns. No `[tool_use: ...]` markers, no tool-result echoes, no extended-thinking blocks.
 
 ---
 
@@ -190,7 +201,7 @@ pytest -v --cov=claude_backup
 
 CI runs on Python 3.10, 3.11, and 3.12 — see [.github/workflows/test.yml](.github/workflows/test.yml).
 
-**Test coverage: 91%** (64/64 tests passing) — covers the real Claude Code format, the legacy spec format, edge cases (empty/corrupt JSONL, unicode, missing index), the `--minimal` mode, and CLI integration.
+**Test coverage: 91%** (68/68 tests passing) — covers the real Claude Code format, the legacy spec format, edge cases (empty/corrupt JSONL, unicode, missing index), `--mode` selection (both / minimal / full), and CLI integration.
 
 ### Project layout
 
diff --git a/README.ru.md b/README.ru.md
@@ -50,11 +50,14 @@ claude-backup export f7a07eec --output ~/claude-backups/
 
 # Экспортировать всё (каждый проект — в отдельную папку)
 claude-backup export-all --output ~/claude-backups/
-
-# Mini-лог: только ваши сообщения и текстовые ответы Claude, без tool-вызовов
-claude-backup export f7a07eec --output ~/claude-backups/ --minimal
 ```
 
+По умолчанию каждый экспорт создаёт **два файла** рядом:
+- `<date>--<id>.md` — чистый диалог (ваши промпты + текстовые ответы Claude)
+- `<date>--<id>.full.md` — полная audit-копия с tool-вызовами, tool-результатами и блоками рассуждений
+
+Если нужен только один из них — `--mode minimal` или `--mode full`.
+
 Новым пользователям: см. [QUICKSTART.md](./QUICKSTART.md) — полная пошаговая инструкция (macOS, Linux, Windows/WSL).
 
 ---
@@ -96,23 +99,31 @@ Documents/Claude  f7a07eec  Build claude-backup CLI tool with export      296
 claude-backup export f7a07eec --output ./backups/
 ```
 
-Создаёт `./backups/2026-05-07--f7a07eec-<полный-uuid>.md`. **Достаточно первых 8 символов session ID** — утилита сама находит сессию по префиксу.
+По умолчанию создаёт два файла в `./backups/`:
+
+```
+2026-05-07--f7a07eec-<полный-uuid>.md       ← чистый диалог, тот что хочется открыть
+2026-05-07--f7a07eec-<полный-uuid>.full.md  ← полная audit-копия со всеми tool-вызовами
+```
 
-### Mini-лог (`--minimal`)
+**Достаточно первых 8 символов session ID** — утилита сама находит сессию по префиксу.
 
-Когда нужен чистый транскрипт диалога — только ваши промпты и текстовые ответы Claude, без tool-вызовов, tool-результатов и блоков extended thinking:
+### Выбор файлов (`--mode`)
 
-```bash
-claude-backup export f7a07eec --output ./backups/ --minimal
-```
+| Флаг | Что записывает |
+|------|----------------|
+| _(по умолчанию)_ | оба файла: `<id>.md` и `<id>.full.md` |
+| `--mode minimal` | только `<id>.md` (чистый диалог) |
+| `--mode full` | только `<id>.full.md` (audit-копия) |
 
-Создаётся отдельный файл с суффиксом `.minimal.md`, чтобы полный и mini-экспорты могли существовать одновременно для одной сессии. В frontmatter — `mode: dialogue-only` и пересчитанный `messages`. Обычно mini-лог занимает 30–50% от объёма полного экспорта.
+`.md` файл — тот, что обычно хочется открыть: как правило в 2 раза меньше audit-копии и читается как обычный чат-лог. `.full.md` — это страховка: каждый tool-вызов, каждый shell-вывод, каждый блок reasoning. Полезно когда реально нужно отдебажить что делал агент.
 
 ### Экспорт всего
 
 ```bash
-claude-backup export-all --output ./backups/
-claude-backup export-all --output ./backups/ --minimal   # mini-версия всех сессий
+claude-backup export-all --output ./backups/                    # оба файла на каждую сессию
+claude-backup export-all --output ./backups/ --mode minimal     # только чистые .md
+claude-backup export-all --output ./backups/ --mode full        # только .full.md audit-копии
 ```
 
 Каждый проект получает свою поддиректорию в `--output`.
@@ -160,7 +171,7 @@ I'll create the utility according to the spec...
 ...
 ```
 
-В режиме `--minimal` frontmatter тот же (плюс поле `mode: dialogue-only`), но в теле остаются только турны `## User` и `## Assistant` с реальным текстом — без `[tool_use: ...]`, без эхо tool-результатов, без блоков thinking.
+В файле `<id>.md` (по умолчанию и при `--mode minimal`) frontmatter тот же — плюс поле `mode: dialogue-only`, — но в теле остаются только турны `## User` и `## Assistant` с реальным текстом. Без `[tool_use: ...]`, без эхо tool-результатов, без блоков extended thinking.
 
 ---
 
@@ -187,7 +198,7 @@ pytest -v --cov=claude_backup
 
 CI запускается на Python 3.10, 3.11 и 3.12 — см. [.github/workflows/test.yml](.github/workflows/test.yml).
 
-**Покрытие тестами: 91%** (64/64 тестов проходят) — реальный формат Claude Code, legacy-формат из спеки, edge-кейсы (пустой/битый JSONL, unicode, отсутствующий индекс), режим `--minimal` и интеграционные тесты CLI.
+**Покрытие тестами: 91%** (68/68 тестов проходят) — реальный формат Claude Code, legacy-формат из спеки, edge-кейсы (пустой/битый JSONL, unicode, отсутствующий индекс), выбор `--mode` (both / minimal / full), и интеграционные тесты CLI.
 
 ### Структура проекта
 
diff --git a/claude_backup/cli.py b/claude_backup/cli.py
@@ -60,15 +60,20 @@ def list_cmd(ctx: click.Context) -> None:
     help="Output directory (default: ./backups/).",
 )
 @click.option(
-    "--minimal",
-    is_flag=True,
-    default=False,
-    help="Mini-log: only user/assistant dialogue, no tool calls or reasoning. "
-    "Filename gets a .minimal.md suffix so it doesn't overwrite the full export.",
+    "--mode",
+    type=click.Choice(["both", "minimal", "full"], case_sensitive=False),
+    default="both",
+    show_default=True,
+    help=(
+        "Which file(s) to write. "
+        "'both' writes the clean dialogue (<id>.md) AND the audit copy with tool "
+        "calls (<id>.full.md). 'minimal' writes only the clean dialogue. "
+        "'full' writes only the audit copy."
+    ),
 )
 @click.pass_context
 def export_cmd(
-    ctx: click.Context, session_id: str, output: Path, minimal: bool
+    ctx: click.Context, session_id: str, output: Path, mode: str
 ) -> None:
     projects = _safe_scan(ctx.obj.get("claude_home"))
     matches = []
@@ -96,8 +101,9 @@ def export_cmd(
         )
         sys.exit(2)
 
-    out = export_session(target, output, minimal=minimal)
-    click.echo(f"Exported: {out}")
+    paths = export_session(target, output, mode=mode)
+    for p in paths:
+        click.echo(f"Exported: {p}")
 
 
 @main.command("export-all", help="Export every discovered session.")
@@ -109,13 +115,14 @@ def export_cmd(
     help="Output directory (default: ./backups/).",
 )
 @click.option(
-    "--minimal",
-    is_flag=True,
-    default=False,
-    help="Mini-log mode: only user/assistant dialogue, no tools or reasoning.",
+    "--mode",
+    type=click.Choice(["both", "minimal", "full"], case_sensitive=False),
+    default="both",
+    show_default=True,
+    help="Which file(s) to write per session — see `claude-backup export --help`.",
 )
 @click.pass_context
-def export_all_cmd(ctx: click.Context, output: Path, minimal: bool) -> None:
+def export_all_cmd(ctx: click.Context, output: Path, mode: str) -> None:
     projects = _safe_scan(ctx.obj.get("claude_home"))
     exported = 0
     skipped = 0
@@ -131,8 +138,9 @@ def export_all_cmd(ctx: click.Context, output: Path, minimal: bool) -> None:
                 skipped += 1
                 continue
             try:
-                path = export_session(session, project_out, minimal=minimal)
-                click.echo(f"Exported: {path}")
+                paths = export_session(session, project_out, mode=mode)
+                for p in paths:
+                    click.echo(f"Exported: {p}")
                 exported += 1
             except Exception as e:  # pragma: no cover - defensive
                 click.echo(
diff --git a/claude_backup/exporter.py b/claude_backup/exporter.py
@@ -17,33 +17,58 @@
 }
 
 
+EXPORT_MODES = ("both", "minimal", "full")
+
+
 def export_session(
     session: SessionInfo,
     output_dir: Path,
     now: datetime | None = None,
-    minimal: bool = False,
-) -> Path:
-    """Export a single session to Markdown. Returns path to the written file.
-
-    When `minimal=True`, drops tool calls, tool results, and reasoning blocks —
-    keeps only the user/assistant dialogue. Filename gets a `.minimal.md` suffix.
+    mode: str = "both",
+) -> list[Path]:
+    """Export a session to Markdown. Returns the list of written file paths.
+
+    Two output flavours, controlled by `mode`:
+      - `<date>--<session_id>.md`       — clean dialogue: only user prompts and
+                                          Claude's text replies.
+      - `<date>--<session_id>.full.md`  — everything: tool calls, tool results,
+                                          and any visible thinking text.
+
+    `mode` values:
+      - `"both"`    (default) — write both files
+      - `"minimal"`           — write only the clean `.md` file
+      - `"full"`              — write only the `.full.md` file
     """
+    if mode not in EXPORT_MODES:
+        raise ValueError(
+            f"mode must be one of {EXPORT_MODES}; got {mode!r}"
+        )
     if session.jsonl_path is None or not session.jsonl_path.exists():
         raise FileNotFoundError(
             f"Session JSONL not found for {session.session_id}"
         )
 
     output_dir.mkdir(parents=True, exist_ok=True)
     messages = parse_session(session.jsonl_path)
-
     date_prefix = _date_prefix(session, messages)
-    suffix = ".minimal.md" if minimal else ".md"
-    filename = f"{date_prefix}--{session.session_id}{suffix}"
-    out_path = output_dir / filename
-
-    md = render_markdown(session, messages, now=now, minimal=minimal)
-    out_path.write_text(md, encoding="utf-8")
-    return out_path
+    base = f"{date_prefix}--{session.session_id}"
+
+    written: list[Path] = []
+    if mode in ("both", "minimal"):
+        path = output_dir / f"{base}.md"
+        path.write_text(
+            render_markdown(session, messages, now=now, minimal=True),
+            encoding="utf-8",
+        )
+        written.append(path)
+    if mode in ("both", "full"):
+        path = output_dir / f"{base}.full.md"
+        path.write_text(
+            render_markdown(session, messages, now=now, minimal=False),
+            encoding="utf-8",
+        )
+        written.append(path)
+    return written
 
 
 def render_markdown(
diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -27,17 +27,21 @@ def test_list_handles_missing_claude_home(tmp_path: Path) -> None:
     assert "not found" in result.output.lower()
 
 
-def test_export_command_writes_file(claude_home: Path, tmp_path: Path) -> None:
+def test_export_command_writes_both_files_by_default(
+    claude_home: Path, tmp_path: Path
+) -> None:
     runner = CliRunner()
     out = tmp_path / "backups"
     result = runner.invoke(
         main,
         ["--claude-home", str(claude_home), "export", "abc-123", "--output", str(out)],
     )
     assert result.exit_code == 0, result.output
-    written = list(out.glob("*.md"))
-    assert len(written) == 1
-    assert "abc-123" in written[0].name
+    written = sorted(p.name for p in out.glob("*.md"))
+    assert written == [
+        "2026-05-07--abc-123.full.md",
+        "2026-05-07--abc-123.md",
+    ]
 
 
 def test_export_unknown_session_returns_error(claude_home: Path, tmp_path: Path) -> None:
diff --git a/tests/test_exporter.py b/tests/test_exporter.py
diff --git a/tests/test_minimal.py b/tests/test_minimal.py
