=== Unused Media Usage Audit by CodeCaste ===
Contributors: codecaste
Tags: media, images, cleanup, audit, unused media
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Find potentially unused Media Library files and safely review them before deletion.

== Description ==

The plugin scans WordPress data, builds a reference index, and lists attachments for which no supported reference was found.

Supported sources include:
* Post content, blocks, shortcodes, lazy-load data, and `srcset`
* Post meta, custom fields, ACF, and SCF data
* Elementor data
* WooCommerce product images and galleries
* Options, widgets, term meta, and user meta
* Active/parent theme PHP, CSS, and JavaScript files
* Eligible custom database tables
* Developer-registered custom scanners

Dashboard: **Tools -> Unused Media**

== Safety ==

* No automatic deletion.
* Results are **Potentially Unused**, not guaranteed unused.
* A final reference check runs before deletion.
* Full scans run in background batches.
* Targeted re-scans can run after site changes.

== How It Works ==

After activation, a background scan starts automatically. The plugin indexes detected references and classifies attachments as **In Use** or **Potentially Unused**.

The dashboard shows scan status, logs, scan time, and results. Use **Run Full Scan** for a complete rescan.

If WP-Cron is unreliable, configure server cron for `wp-cron.php` or keep the dashboard open during scanning.

== Installation ==

1. Upload the plugin to `/wp-content/plugins/`.
2. Activate it from **Plugins**.
3. Open **Tools -> Unused Media**.
4. Review the results after the first scan.

== Results ==

The dashboard includes search, filtering, list/grid views, attachment details, and Media Library links.

You can delete individual files, selected files, or all files matching the current filters.

WordPress's standard attachment deletion API is used.

== FAQ ==

= Is a file guaranteed to be unused? =
No. Dynamic or unsupported references may not be detected.

= Does it support ACF, SCF, Elementor, and WooCommerce? =
Yes, supported media references from these systems are scanned.

= Does it scan theme files? =
Yes. The active theme and applicable parent theme are checked for literal uploads-path references.

= Does it scan custom database tables? =
Yes, when detectable local uploads-path references are present in supported tables.

= What if WP-Cron is disabled? =
Use a server cron job or keep the dashboard open during the scan.

= Can a used file appear as unused? =
Yes. This can happen with dynamic PHP/JavaScript URLs, external services, CDN/offloaded media, or unsupported database formats.

== Limitations ==

Detection is not guaranteed for:
* Dynamically generated URLs
* External APIs or remote services
* Some CDN/offloaded media
* Plugin source files and unsupported filesystem locations
* Unsupported custom database formats
* Some numeric attachment IDs
* WordPress Multisite, which is not currently verified

Always review files before deleting them, especially on sites using CDNs, offloaded media, or third-party integrations.

== Developer Extension ==

Developers can add custom scanners using the
`media_cleanup_scout_additional_reference_sources` filter.

== Data ==

The plugin stores its scan index, results, logs, settings, and scan state in plugin-managed data.

Deactivation clears scan data and scheduled jobs. Uninstalling removes plugin-managed data and settings.

== Screenshots ==

1. Dashboard showing scan status, media counts, and potentially unused files ready for review.

== Changelog ==

= 1.3.1 =
* Updated plugin URI, version, and documentation.

= 1.3.0 =
* Rebranded to **Unused Media Usage Audit by CodeCaste**.
* Updated slug/text domain and internal prefixes.
* Fresh scan/settings state after upgrade.

= 1.2.3 =
* Improved WordPress.org compliance and settings migration.
* Moved dashboard to **Tools -> Unused Media**.

= 1.2.2 =
* Added scan-recency and WP-Cron notices.
* Added WooCommerce gallery change detection.

= 1.2.0 =
* Improved security, performance, concurrency, and scan coverage.
* Added custom scanner support and cleanup improvements.

= 1.1.0 =
* Initial public release.