Update documentation for v1.5.2

- Version bumped to 1.5.2 in CLAUDE.md, readme.md, and .po files
- Added v1.5.2 changelog: Remove Not Assigned Media feature + media
  deletion physical file fix
- Updated manipulator class docs, views docs, JS docs, AJAX handlers,
  admin menu structure, and testing notes
- Added usage section for Remove Not Assigned Media with criteria list
- Added 11 new translation strings (EN + CZ) for the new feature

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

studiou-wc-product-cat-manage/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **QDR - Studiou WC Export/Import Product Categories** is a WordPress plugin that extends WooCommerce to provide batch export/import functionality for both product categories and products, along with category manipulation tools.
 
-**Current Version:** 1.5.1
+**Current Version:** 1.5.2
 
 ## Requirements
 
@@ -52,9 +52,11 @@ The plugin follows a modular class-based architecture:
   - Batch description updates for multiple categories
   - Delete products in category (permanently deletes products and variants)
   - Clear Media Categories (permanently deletes media files from media categories) (NEW in v1.5)
+  - Remove Not Assigned Media (deletes unused uncategorized media) (NEW in v1.5.2)
   - Uses direct database queries for reliable product detection
-  - Batch processing for delete operations (10 products per batch)
+  - Batch processing for delete operations (10 items per batch)
   - Auto-detects media category taxonomy (any custom taxonomy registered for attachments)
+  - Robust media deletion with post-deletion verification and manual fallback cleanup
   - Always-on error logging for media operations (prefix: "STUDIOU WC MEDIA:")
 
 - **class-studiou-wc-product-manage-product-db.php** - Product database operations (NEW in v1.4)
@@ -95,6 +97,7 @@ The plugin follows a modular class-based architecture:
   - Batch description between categories (checkbox list + textarea + "Do" button)
   - Delete products in category (checkbox list + "Delete" button + progress bar)
   - Clear Media Categories (checkbox list + "Delete" button + progress bar) (NEW in v1.5)
+  - Remove Not Assigned Media ("Delete unused uncategorized media (N)" button + progress bar) (NEW in v1.5.2)
 - **product-import.php** - Product import page UI (NEW in v1.4)
   - File upload for CSV import
   - Progress bar for import operations
@@ -118,6 +121,7 @@ The plugin follows a modular class-based architecture:
   - AJAX handlers for all category operations
   - AJAX handlers for product import/export operations (NEW in v1.4)
   - AJAX handlers for clear media categories operations (NEW in v1.5)
+  - AJAX handlers for remove unassigned media operations (NEW in v1.5.2)
   - Batch processing logic for delete and media deletion operations
   - Real-time progress bar updates
   - Confirmation dialogs for destructive operations
@@ -205,6 +209,7 @@ All pages are added under **Products** menu:
   - Batch description between categories
   - Delete products in category
   - Clear Media Categories (NEW in v1.5)
+  - Remove Not Assigned Media (NEW in v1.5.2)
 - **Product Import (slug: `studiou-product-import`)** - NEW in v1.4
 - **Product Export (slug: `studiou-product-export`)** - NEW in v1.4
 
@@ -280,6 +285,22 @@ All pages are added under **Products** menu:
 - Verify media files are actually removed from disk
 - Verify deletion statistics are accurate
 - Test with media files used as product images (verify WooCommerce product references are handled)
+- Verify physical files are deleted from disk (check wp-content/uploads/)
+- Verify attachment posts are removed from Media Library
+
+### Remove Not Assigned Media Operations (NEW in v1.5.2)
+- Verify button count matches actual unused uncategorized media
+- Test deletion with:
+  - Media not in any category and not used anywhere
+  - Media used as featured image (should NOT be deleted)
+  - Media used in WooCommerce product galleries (should NOT be deleted)
+  - Media attached to a post (post_parent > 0, should NOT be deleted)
+  - Media in a media category (should NOT be deleted)
+  - Large numbers of unused media (test batch processing)
+- Verify confirmation dialog appears before deletion
+- Verify progress bar updates correctly
+- Verify physical files and attachment posts are both deleted
+- Verify button count updates after page reload
 
 ### General
 - Verify translations are properly loaded (English/Czech)
@@ -300,11 +321,13 @@ The plugin registers the following AJAX actions:
 6. **studiou_wcpcm_delete_products_batch** - Processes product deletion in batches
 7. **studiou_wcpcm_clear_media** - Initial request to get media IDs for deletion (NEW in v1.5)
 8. **studiou_wcpcm_clear_media_batch** - Processes media deletion in batches (NEW in v1.5)
+9. **studiou_wcpcm_remove_unassigned_media** - Gets IDs of unused uncategorized media (NEW in v1.5.2)
+10. **studiou_wcpcm_remove_unassigned_media_batch** - Processes unassigned media deletion in batches (NEW in v1.5.2)
 
 ### Product Operations (NEW in v1.4)
-7. **studiou_wcpcm_product_import_parse** - Parses CSV file and stores in transient (Step 1)
-8. **studiou_wcpcm_product_import_batch** - Processes batch of 5 products (Step 2, called recursively)
-9. **studiou_wcpcm_product_export** - Generates product CSV export by category selection
+11. **studiou_wcpcm_product_import_parse** - Parses CSV file and stores in transient (Step 1)
+12. **studiou_wcpcm_product_import_batch** - Processes batch of 5 products (Step 2, called recursively)
+13. **studiou_wcpcm_product_export** - Generates product CSV export by category selection
 
 All AJAX handlers include:
 - Nonce verification (`studiou-wcpcm-nonce`)

studiou-wc-product-cat-manage/languages/studiou-wc-product-cat-manage-cs_CZ.po

@@ -3,7 +3,7 @@
 # This file is distributed under the same license as the QDR - Studiou WC Export/Import Product Categories package.
 msgid ""
 msgstr ""
-"Project-Id-Version: QDR - Studiou WC Export/Import Product Categories 1.5.1\n"
+"Project-Id-Version: QDR - Studiou WC Export/Import Product Categories 1.5.2\n"
 "Report-Msgid-Bugs-To: https://www.quadarax.com/plugins/studiou-wc-product-"
 "cat-manage\n"
 "POT-Creation-Date: 2026-04-01 12:00+0000\n"
@@ -947,4 +947,48 @@ msgstr "Chyba během operace vyčištění médií: %s"
 
 #: includes/class-studiou-wc-product-cat-manage-manipulator.php
 msgid "Error during clear media batch operation: %s"
-msgstr "Chyba během dávkové operace vyčištění médií: %s"
+msgstr "Chyba během dávkové operace vyčištění médií: %s"
+
+#. ==========================================
+#. Remove Not Assigned Media (v1.5.2)
+#. ==========================================
+
+#: studiou-wc-product-cat-manage.php
+msgid "Are you sure you want to permanently delete ALL unused uncategorized media files? This action cannot be undone!"
+msgstr "Opravdu chcete trvale smazat VŠECHNY nepoužívané nekategorizované mediální soubory? Tuto akci nelze vrátit zpět!"
+
+#: studiou-wc-product-cat-manage.php
+msgid "Remove unassigned media operation successful"
+msgstr "Operace odstranění nepřiřazených médií úspěšná"
+
+#: studiou-wc-product-cat-manage.php
+msgid "Remove unassigned media operation error"
+msgstr "Chyba operace odstranění nepřiřazených médií"
+
+#: studiou-wc-product-cat-manage.php
+msgid "No unused uncategorized media files found"
+msgstr "Nebyly nalezeny žádné nepoužívané nekategorizované mediální soubory"
+
+#: views/manipulations.php
+msgid "Remove Not Assigned Media"
+msgstr "Odstranit nepřiřazená média"
+
+#: views/manipulations.php
+msgid "This operation permanently deletes all media files that are not assigned to any media category and are not used as featured image, product gallery image, or attached to any post."
+msgstr "Tato operace trvale smaže všechny mediální soubory, které nejsou přiřazeny k žádné kategorii médií a nejsou použity jako náhledový obrázek, obrázek galerie produktu nebo připojeny k žádnému příspěvku."
+
+#: views/manipulations.php
+msgid "WARNING: This operation will permanently delete all unused uncategorized media files from the server. This action cannot be undone!"
+msgstr "VAROVÁNÍ: Tato operace trvale smaže všechny nepoužívané nekategorizované mediální soubory ze serveru. Tuto akci nelze vrátit zpět!"
+
+#: views/manipulations.php
+msgid "Delete unused uncategorized media (%d)"
+msgstr "Smazat nepoužívaná nekategorizovaná média (%d)"
+
+#: views/manipulations.php
+msgid "The remove not assigned media operation will permanently delete all media files that are not categorized and not used anywhere. This action cannot be undone!"
+msgstr "Operace odstranění nepřiřazených médií trvale smaže všechny mediální soubory, které nejsou kategorizovány a nejsou nikde použity. Tuto akci nelze vrátit zpět!"
+
+#: includes/class-studiou-wc-product-cat-manage-manipulator.php
+msgid "Found %d unused uncategorized media files to delete"
+msgstr "Nalezeno %d nepoužívaných nekategorizovaných mediálních souborů ke smazání"

studiou-wc-product-cat-manage/languages/studiou-wc-product-cat-manage.po

@@ -2,7 +2,7 @@
 # This file is distributed under the same license as the QDR - Studiou WC Export/Import Product Categories package.
 msgid ""
 msgstr ""
-"Project-Id-Version: QDR - Studiou WC Export/Import Product Categories 1.5.1\n"
+"Project-Id-Version: QDR - Studiou WC Export/Import Product Categories 1.5.2\n"
 "Report-Msgid-Bugs-To: https://www.quadarax.com/plugins/studiou-wc-product-cat-manage\n"
 "POT-Creation-Date: 2026-04-01 12:00+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
@@ -913,4 +913,48 @@ msgstr ""
 
 #: includes/class-studiou-wc-product-cat-manage-manipulator.php
 msgid "Error during clear media batch operation: %s"
+msgstr ""
+
+#. ==========================================
+#. Remove Not Assigned Media (v1.5.2)
+#. ==========================================
+
+#: studiou-wc-product-cat-manage.php
+msgid "Are you sure you want to permanently delete ALL unused uncategorized media files? This action cannot be undone!"
+msgstr ""
+
+#: studiou-wc-product-cat-manage.php
+msgid "Remove unassigned media operation successful"
+msgstr ""
+
+#: studiou-wc-product-cat-manage.php
+msgid "Remove unassigned media operation error"
+msgstr ""
+
+#: studiou-wc-product-cat-manage.php
+msgid "No unused uncategorized media files found"
+msgstr ""
+
+#: views/manipulations.php
+msgid "Remove Not Assigned Media"
+msgstr ""
+
+#: views/manipulations.php
+msgid "This operation permanently deletes all media files that are not assigned to any media category and are not used as featured image, product gallery image, or attached to any post."
+msgstr ""
+
+#: views/manipulations.php
+msgid "WARNING: This operation will permanently delete all unused uncategorized media files from the server. This action cannot be undone!"
+msgstr ""
+
+#: views/manipulations.php
+msgid "Delete unused uncategorized media (%d)"
+msgstr ""
+
+#: views/manipulations.php
+msgid "The remove not assigned media operation will permanently delete all media files that are not categorized and not used anywhere. This action cannot be undone!"
+msgstr ""
+
+#: includes/class-studiou-wc-product-cat-manage-manipulator.php
+msgid "Found %d unused uncategorized media files to delete"
 msgstr ""

studiou-wc-product-cat-manage/readme.md

@@ -1,6 +1,6 @@
 # QDR - Studiou WC Export/Import Product Categories
 
-**Version: 1.5.1**
+**Version: 1.5.2**
 
 A WordPress plugin that extends WooCommerce to provide batch export and import functionality for both product categories and products, along with category manipulation tools.
 
@@ -26,6 +26,7 @@ The plugin provides a complete solution for bulk product and category management
 - **Batch description update** for multiple categories
 - **Delete products in category** - permanently delete all products and variants from selected categories
 - **Clear Media Categories** - permanently delete all media files from selected media categories (NEW in v1.5)
+- **Remove Not Assigned Media** - permanently delete all unused uncategorized media files (NEW in v1.5.2)
 
 ### Product Management (NEW in v1.4)
 - **Export products to CSV** - Export variable products and variations by category selection
@@ -241,6 +242,29 @@ The plugin uses CSV files with the following columns for products:
 - A real-time progress bar shows the deletion progress
 - The page will automatically reload after successful deletion to update category counts
 
+#### Remove Not Assigned Media (NEW in v1.5.2)
+
+1. Go to Products > Category Manipulations
+2. Scroll to the "Remove Not Assigned Media" section
+3. The button shows the count of unused uncategorized media files
+4. Click "Delete unused uncategorized media (N)" button (you will be asked to confirm)
+5. Watch the progress bar as media files are being deleted in batches
+6. Review the deletion statistics
+
+**What counts as "unused uncategorized media":**
+- Not assigned to any media category
+- Not used as a featured image for any post or product
+- Not used in any WooCommerce product image gallery
+- Not attached to any post (post_parent = 0)
+
+**Important Notes about Remove Not Assigned Media:**
+- **THIS OPERATION PERMANENTLY DELETES MEDIA FILES** that meet all criteria above
+- **The files will be removed from the server. THIS ACTION CANNOT BE UNDONE!**
+- Media files are processed in batches of 10 to prevent timeouts
+- Both the WordPress attachment post and the physical files (including thumbnails) are deleted
+- A real-time progress bar shows the deletion progress
+- The page will automatically reload after successful deletion to update the count
+
 ## Sample CSVs
 
 ### Sample Product Category CSV
@@ -280,6 +304,7 @@ After activation, the plugin adds the following menu items under **Products** in
   - Batch description between categories
   - Delete products in category
   - Clear Media Categories (NEW in v1.5)
+  - Remove Not Assigned Media (NEW in v1.5.2)
 
 ### Product Management (NEW in v1.4)
 - **Product Import** - Batch import variable products and variations
@@ -300,6 +325,19 @@ For support, please visit [https://www.quadarax.com/plugins/studiou-wc-product-c
 
 ## Changelog
 
+### Version 1.5.2
+- **NEW: Remove Not Assigned Media** - permanently delete all unused uncategorized media files
+  - Button with count of unused uncategorized media
+  - Detects media not in any category, not used as featured image, not in product galleries, not attached to any post
+  - Confirmation dialog before deletion
+  - Real-time progress bar with batch processing (10 files at a time)
+  - Comprehensive deletion statistics and error reporting
+- **Fix: Media deletion now properly deletes physical files and attachment posts**
+  - After `wp_delete_attachment()`, verifies post was actually deleted via direct DB check
+  - If post still exists, forces manual cleanup (term relationships, postmeta, post row)
+  - Explicitly deletes physical files (main file + thumbnails) from disk
+- 2 new AJAX handlers: `studiou_wcpcm_remove_unassigned_media`, `studiou_wcpcm_remove_unassigned_media_batch`
+
 ### Version 1.5.1
 - Fix: Clear Media Categories JS event handler not binding due to browser-cached old JS
 - Fix: Auto-detect any custom taxonomy registered for attachments (no longer limited to 3 hardcoded names)