From a6e9947b904406ec5b49e88c77689d5c6ef6d04b Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Fri, 18 Jul 2025 14:00:13 +0300
Subject: feat: major refactor - APKG export support and subdirectory
 organization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Major Features:
- Added native .apkg (Anki package) export format with embedded media
- Reorganized file structure to use subdirectories per word
- Enhanced GUI export dialog with format selection (APKG/CSV)

APKG Export Implementation:
- Created apkg_generator.go with full SQLite-based Anki package generation
- Includes custom card templates with professional CSS styling
- Front side: Image + English word
- Back side: Image + Bulgarian word + Audio + Notes
- All media files automatically embedded in package
- Custom deck names supported via --deck-name flag

Directory Structure Changes:
- Each word now gets its own subdirectory (e.g., anki_cards/ябълка/)
- All related files (audio, images, translations, prompts) stored together
- Cleaner organization and easier management
- Prevents file naming conflicts

GUI Updates:
- Export dialog no longer shows file browser, exports directly to anki_cards
- Format selection between APKG (recommended) and CSV (legacy)
- Fixed navigation to properly load image prompts from subdirectories
- Delete function now moves entire word directory to trash

CLI Updates:
- --anki flag now generates APKG by default
- --anki-csv flag for legacy CSV format
- All file generation uses subdirectory structure

Bug Fixes:
- Fixed handling of multi-word entries (e.g., "картоф картофи")
- Fixed GenerateFromDirectory to properly handle words with underscores
- Fixed phonetic files being treated as separate cards
- Fixed image prompt preservation during navigation

Breaking Changes:
- File structure changed from flat to subdirectory-based
- Existing files need to be reorganized into subdirectories

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 59d88d2..583de85 100644
--- a/README.md
+++ b/README.md
@@ -71,9 +71,11 @@ export OPENAI_API_KEY="sk-..."
    totalrecall --batch words.txt
    ```
 
-4. Generate with Anki CSV:
+4. Generate with Anki package:
    ```bash
-   totalrecall ябълка --anki
+   totalrecall ябълка --anki                    # Creates APKG file (recommended)
+   totalrecall ябълка --anki --anki-csv        # Creates CSV file (legacy)
+   totalrecall ябълка --anki --deck-name "My Bulgarian Words"  # Custom deck name
    ```
 
 ### GUI Mode
@@ -150,15 +152,30 @@ For each word, the tool generates:
 - `word.mp3` - Audio pronunciation (random voice)
 - `word_translation.txt` - English translation
 - `word_1.jpg`, `word_2.jpg`, etc. - Generated images
-- `anki_import.csv` - Anki import file (when using --anki flag)
+- `bulgarian_vocabulary.apkg` - Anki package file (when using --anki flag)
+- `anki_import.csv` - Anki import file (when using --anki --anki-csv flags)
 
 With `--all-voices` flag:
 - `word_alloy.mp3`, `word_nova.mp3`, etc. - Audio in all 11 voices
 
 ## Anki Import
 
+### Method 1: APKG Format (Recommended)
 1. Generate materials with the `--anki` flag
 2. In Anki, go to File → Import
+3. Select the generated `.apkg` file
+4. All media files are included automatically
+5. Cards are ready to use with custom styling
+
+### Method 2: CSV Format (Legacy)
+1. Generate materials with `--anki --anki-csv` flags
+2. In Anki, go to File → Import
 3. Select the generated `anki_import.csv`
 4. Copy all media files to your Anki media folder
 5. Map fields appropriately during import
+
+### GUI Export
+The GUI mode offers an export dialog where you can:
+- Choose between APKG and CSV formats
+- Set a custom deck name
+- Export all generated cards at once
-- 
cgit v1.2.3