MediaPilot AI – Media Library Folders, Cleanup & AI Metadata

Stop scrolling through thousands of WordPress uploads. MediaPilot AI adds drag-and-drop folders to the native Media Library, then helps you find unused files, remove duplicates safely, replace attachments, optimize images and understand where your storage goes.

Organize, clean and optimize in one plugin

• Organize existing uploads in unlimited folders and subfolders
• Find files quickly with Smart Views, filters, search and media tags
• Review unused media and exact or visually similar duplicates before moving anything to a restorable Trash
• Replace an attachment, preserve its metadata and roll back to an earlier version
• Convert images locally to WebP or AVIF and measure the storage saved
• See storage, file-type, upload and media-usage analytics without visitor tracking
• Draft image metadata with optional, review-first AI using your own provider key

Already using FileBird, Real Media Library, Wicked Folders or HappyFiles? Import your existing folders and assignments without changing the other plugin’s data.

Folders are virtual by default, so organizing an attachment does not move the file on disk or change its URL. An opt-in Real Filesystem Mode moves files into matching directories instead.

All core media management runs on your own server — no account, no quota, no telemetry. The three optional integrations (AI, Google Drive, CDN) stay off until you configure them.

Media folders and smart views

Create unlimited folders and subfolders and move files by drag and drop, singly or in bulk. New uploads land in the folder you have open.

• Colours, A–Z sorting, a searchable tree, and ZIP download of a folder
• Seven structures to start from — Blog, E-commerce, Agency Client, Portfolio, Real Estate, LMS / Courses, Directory / Listing — or save your own as a template
• Global folders for the team, or a per-user mode giving each person a private tree
• Per-folder read and write rules by role or user, inherited down the tree
• Folders appear in Grid and List views and in the Featured Image and Insert Media pickers
• Smart Views for images, video, audio, PDFs, documents, archives, unused files, missing alt text, large files and duplicates
• Filter by filename, type, size, date and orientation, plus a synonym-aware mode matching related terms from a local tag index

Unused media cleanup, and how it protects you

MediaPilot indexes where each attachment is used: post content, featured images, shortcodes (including , WPBakery and Divi), every post meta value, widgets, term and user meta, site options, the Site Icon and the Custom Logo. Because it reads all post meta rather than a fixed list of keys, references stored by Elementor, Beaver Builder, Bricks, ACF and WooCommerce galleries are picked up too.

Indexing starts on activation and runs in background batches. Cleanup stays unavailable until the index reports ready, so no decision is made from a partial scan.

The workflow, in order:

1. The index proposes candidates that nothing appears to reference.
2. Each candidate is re-verified by a slower live scan immediately before removal. This is the load-bearing step: within the database sources MediaPilot supports, a stale or incomplete index can only cause a file to be skipped, never wrongly removed. That is a guarantee about the index, not about your whole site — a reference the scan cannot see at all (see below) is invisible to both stages.
3. Survivors move to a restorable Trash, and the files stay on disk.
4. Permanent deletion is a separate, explicit action — and it is irreversible.

No reference scanner can be exhaustive. A URL hard-coded in a theme template, built at runtime by custom PHP, or held only in an external system cannot be detected by any tool that reads the database. Review what is proposed, keep a current backup, and treat cleanup as assisted judgement rather than an authority.

The duplicate image finder uses the same restorable workflow, with two cancellable background scans: exact, by MD5 hash, and visually similar, comparing a 64-bit perceptual signature within an adjustable distance (this needs the GD extension). Configure the scan scope, batch size and image filters before starting. Images already in use are preferred as the primary copy, and you can choose another. Supported references are reassigned to the selected primary before duplicates move to Trash; files with unresolved references are retained.

Replace a file, keep its URL

Replace an image, PDF, video or any other attachment and the attachment ID always stays the same. Keep the same filename and the public URL is unchanged too — nothing anywhere needs updating, which is the safest way.

Change the filename and the URL necessarily changes with it. MediaPilot then rewrites the references it can reach: post content and post meta in your database. It cannot rewrite a URL that lives outside the database — hard-coded in a theme or plugin file, built at runtime by code, cached by a CDN, or held in an external system — so on a site with hard-coded media URLs, keep the filename.

Thumbnails are regenerated and attachment metadata preserved either way. Identical files are caught by SHA-256 and rejected rather than written twice. The previous file is archived under uploads/mediapilot-versions/ so you can roll back, and old versions can be pruned to a keep limit.

Image optimization

Local optimization on your own server, with no monthly allowance.

• Convert uploads to WebP, and to AVIF where the server has Imagick built with AVIF support
• Adjustable quality, with byte savings reported per file and overall coverage
• Convert existing media in bulk, not only new uploads; conversions are written as sidecars and the original file is always kept
• Optionally rewrite media URLs to a CDN base URL you supply, and add loading="lazy" to content images that lack it

WordPress media analytics

Total storage, and storage by folder and file type. Upload activity over time. Most-used and never-used attachments. Insert and download counts, recorded in your own database from the admin only — no front-end tracker, no visitor tracking. CSV export of the data.

For metadata and accessibility work: a Smart View listing every image with no alt text, bulk editing of alt text, title, caption and description across many attachments, and media tags backed by the same local index that powers the search.

AI image metadata, only when you configure it

Every feature above works without AI. The assistant stays dormant — no outbound request of any kind — until an administrator switches it on, records consent, and saves their own OpenAI or Google Gemini API key. There is no MediaPilot account and no credit system.

It drafts alt text, a title, a caption, a description and tags for one image at a time. You choose the fields, and the plugin shows you what will leave your server first: provider, model, whether the full image or a smaller copy is sent, and any context you opted in to.

Nothing is saved automatically. Suggestions arrive in editable fields; you accept, edit, regenerate or discard each one, and only what you approve is written. Existing metadata is never replaced without confirmation, and alt text that looks too long, too vague, keyword-stuffed or identical to the caption is flagged. Requests are rate-limited; the provider bills you directly.

A generated description is a draft, not an accessibility guarantee. A model describes what it sees; only you know what the image does on the page.

Import, migrate and extend

Import and export as CSV, build folder galleries and document libraries with blocks, shortcodes and page-builder modules, and drive it all from WP-CLI or the REST API. The FAQ covers this in detail.

Privacy

Nothing is sent to BrainStudioz: no account, no licence check, no usage reporting, no telemetry. The AI assistant contacts OpenAI or Google Gemini, Drive sync contacts Google, and CDN rewriting points visitors at your CDN — each only after you configure it. External services below states what each receives and when. Uninstalling removes the plugin’s tables, options, post meta, scheduled events and capabilities, on every site of a multisite network.

Free and Pro

MediaPilot AI Pro is a separate paid add-on requiring this plugin; everything above works without Pro. Pro adds cloud storage beyond Google Drive, offloading, backup and migration, cloud optimization, storage cost analytics, a brandable client portal, and approval and audit workflows. Full comparison in the FAQ; details at portal.brainstudioz.com.

External services

MediaPilot AI Free processes every core feature locally and sends nothing to BrainStudioz. Three optional integrations can contact a third party, and all three are inert until an administrator configures them — with nothing saved, no request is made at all.

OpenAI

Used only by the optional AI Metadata Assistant. Disabled until an administrator configures it: an administrator must enter their own OpenAI API key, enable the assistant, and accept the consent notice before any image can be sent.

What is sent: the image (by default a smaller generated copy, not the original), the instruction text built from your settings, and — only if you switch these options on — the file’s existing title, caption, description and alt text, and the title of the post it is attached to. Your API key travels as an authorization header.

When: only when a logged-in user with permission to edit that file presses Generate. Never on upload, never in the background, never on a schedule. Test connection also contacts the provider to verify the key, and sends none of your media.

Provided by OpenAI, L.L.C. Requests go to https://api.openai.com.
Terms of use: https://openai.com/policies/terms-of-use — Privacy policy: https://openai.com/policies/privacy-policy

Google Gemini

Used only by the optional AI Metadata Assistant, on the same terms as OpenAI above. Disabled until an administrator configures it: no key saved means no request is ever made, and the same steps apply — enter a key, enable the assistant, accept the consent notice.

What is sent: the same data described for OpenAI, with your API key as a request header. When: identical to OpenAI — only on an explicit, per-image request by a permitted user.

Provided by Google LLC. Requests go to https://generativelanguage.googleapis.com.
Terms of service: https://ai.google.dev/gemini-api/terms — Privacy policy: https://policies.google.com/privacy

Whichever provider you choose bills you directly. Generated text can be inaccurate, so nothing is saved automatically — every suggestion is shown for review first.

Google Drive

Used only by the optional Drive backup and synchronisation feature, and only after an administrator has created their own Google OAuth client, saved it, and connected an account.

What is sent: the media files you choose to back up or synchronise, with their filenames, MIME types and sizes; folder names when mirroring is enabled; and your OAuth credentials, to obtain and refresh access tokens.

What is not sent: your database, users, passwords, posts, settings, or any site data beyond those files and their attachment mapping.

When: during transfers you start — a synced upload, a bulk sync, a restore — and when refreshing an expired token. Never on a schedule you have not configured.

Access requested: the drive.file scope only, so MediaPilot sees just the files and folders it creates, not the rest of your Drive. Your site connects to Google directly with your own OAuth client — no relay, no proxy.

Provided by Google LLC. Requests go to https://accounts.google.com, https://oauth2.googleapis.com and https://www.googleapis.com.

• Google APIs Terms of Service: https://developers.google.com/terms
• Google Privacy Policy: https://policies.google.com/privacy
• Google API Services User Data Policy: https://developers.google.com/terms/api-services-user-data-policy

CDN URL rewriting (a CDN you supply)

Off by default. If you enter a CDN base URL in the optimization settings, MediaPilot rewrites eligible media URLs so visitors’ browsers request those files from your CDN. The rewrite happens locally: the plugin sends no data to the CDN and uploads nothing to it. That provider’s own terms and privacy policy govern the requests your visitors’ browsers make.

1. In your WordPress dashboard, go to Plugins > Add New.
2. Search for MediaPilot AI, then click Install Now.
3. Activate the plugin.
4. Open Media > Library to create folders and organize existing uploads.
5. Open Media > MediaPilot AI for cleanup, optimization, analytics and settings.

Nothing else is required. On an existing site MediaPilot starts indexing your content in the background as soon as it is activated; progress is shown under Media > MediaPilot AI > Unused media. Cleanup tools stay unavailable until that first index finishes, so they are never acting on a partial picture.

Optional: the AI assistant needs your own OpenAI or Google Gemini API key, and Google Drive needs your own Google OAuth client. Neither is required, and neither contacts anything until you configure it.

1. 

   Organize WordPress uploads with unlimited virtual media folders, nested subfolders, colours, and drag and drop.

2. 

   Find exact duplicates and visually similar images with a cancellable background scan.

3. 

   Review unused files and images with missing alt text through Smart Views.

4. 

   Understand storage, file types, upload trends and usage from the media analytics dashboard.

5. 

   Configure local WebP and AVIF conversion, your own CDN base URL, and optional content-image lazy loading.

6. 

   Replace an attachment while retaining its URL, then review or restore earlier versions.

7. 

   Import, export, or migrate folder structures and media assignments.

2.9.1

• New: choose what a duplicate scan looks at before it runs. A configuration step sets how many media items to work through in the first session and in each session after it, and narrows the scan by dimensions, file size and file format. The scan stops at the limit, shows what it found so you can act on it, and waits for you to continue. Your choices are saved for next time.
• Fixed: the copy your site was using was the one queued for deletion. Each group marked its oldest upload “Keeping” without ever looking at usage, so on a product catalogue the unused 2024 copy survived and the 2025 copy live on two product pages was the one moved to Trash. The copy referenced in the most places is now kept by default; where no copy is used, or several are used equally, the oldest upload is kept. You can still pick a different one in any group.
• New: references move to the copy you keep before anything is trashed. Featured images, product galleries, category images, gallery shortcodes, page content and image URLs are all repointed at the kept image first. Gallery order is preserved, and an image already in a gallery is not added to it twice.
• New: a review summary before anything is removed. It names the copy being kept, lists the references being moved onto it, and lists the duplicates going to Trash — for one group or for a bulk selection.
• New: remove specific copies rather than all of them. Each copy in a group now has its own control, so a group of four can lose two and keep two.
• Fixed: duplicates uploaded to a product could never be resolved. WordPress records which post a file was uploaded to, and that link counted as a reference the cleanup could not clear — so every product image failed with “still has references that could not be moved”. The file is now detached on its way to the Trash, and reattached if you restore it.
• Fixed: a rewrite gated only on the stored value could repoint a field that had nothing to do with media — a WooCommerce order’s customer ID that happened to match an attachment ID, for instance.
• Changed: duplicate cards show each copy’s dimensions alongside its file size, date and usage count.
• Fixed: other plugins’ notices appeared inside MediaPilot’s navigation. Warnings and prompts from your theme and other plugins were being placed between the sidebar’s first section heading and its links. They now appear under the page title, where WordPress shows notices everywhere else.
• Fixed: callouts and notices on MediaPilot screens rendered in broken pieces. A conflict inside the plugin’s own admin stylesheet turned every inline notice into a fragmented box — a stray coloured bar beside text with no visible container — most obviously on the Integrations screen.
• Fixed: panels that were meant to be hidden still took up space. The storage measurement banner on Analytics held open a gap that overlapped the heading and button beneath it, even while hidden.
• Fixed: the usage reference index looked stuck when it was working. A rebuild reported “Preparing the usage reference index…” at 0% from its first record to its last, no matter how far along it was. It now says which of its six sources it is reading and how many records it has checked.
• Changed: notices inside MediaPilot panels are tinted by severity rather than white on a white card, so a callout reads as one.
• Changed: more database queries — the upgrade migrations, uninstall, clearing the activity log and the storage scan history — now pass table and column names to the database as quoted identifiers rather than writing them into the query text, and connecting Google Drive now redirects through WordPress’s allow-list of redirect hosts.

2.9.0

• New: Reclaim orphaned version archives. Settings → Advanced can now find copies of replaced files that were left on disk with nothing pointing at them — unrestorable, invisible in history, but still using space. It reports what it found first and deletes nothing until you confirm.
• Fixed: the storage scan could restart itself in a loop. A finished scan that had measured fewer items than it started with reported outstanding work forever, and an older browser tab polling for progress kept launching fresh full-library scans, one history row each.
• Fixed: the storage scan skipped files when the library changed mid-scan. Progress is now tracked by attachment ID rather than by position, so deleting or uploading during a scan no longer shifts the window past unmeasured items.
• Fixed: a scan could act on stale state. Job state is now re-read after the run lock is taken, so two overlapping runs cannot both believe they own the scan.
• Fixed: replacing a file with one of the same name no longer risks two simultaneous replacements choosing the same filename.
• Fixed: a failed replacement no longer leaves a history entry pointing at a backup that was never written.
• Fixed: a Drive transfer batch could keep seeing “no job” for the rest of its request after one was cancelled and a new one started.
• Fixed: uninstall, deactivation and “Delete all data” left the storage scan’s cron job, lock and state behind, and “Delete all data” never removed the plugin’s post meta — roughly five rows per attachment.
• Fixed: the Scan History table put its numbers on the wrong side of the column in Arabic, Urdu and other right-to-left languages.
• Changed: the Analytics dashboard is much faster. Its figures are cached and refreshed when a scan finishes, an attachment is deleted or a file is replaced, instead of running eight full passes over the media table on every page load.
• Changed: the storage scan now reports its progress, stalls and failures to screen readers, and a failed scan explains why without needing a mouse.

2.8.1

• Consolidated entry for 2.6.0, 2.7.x, 2.8.0 and 2.8.1, which shipped without individual changelog entries. Per-release notes for that window were not recorded and are not reconstructed here.
• Changed: who can see Analytics. The analytics screen and its REST routes now accept either the MediaPilot settings capability or the core manage_options capability, rather than the plugin capability alone.
• Changed: media storage measurement was rebuilt. Storage totals are now produced by a background scan that walks the library in batches and records what each attachment occupies, writing a row per run to a new scan-history table.
• Changed: an irreversible database migration. Upgrading runs a one-way ALTER TABLE … DROP COLUMN on the version-history table, removing five columns that were never populated. See the upgrade notice below.

2.5.9

• New: Clear logs on the Activity log screen. It respects the active filter, so clearing while filtered to errors removes only those, and it asks for confirmation first.
• Fixed: the Activity log filter row overlapped the description above it, and used controls that did not match the rest of the interface.
• Fixed: pagination printed one link per page — up to 250 of them in a single row on a full log. It now shows the first, last and the pages either side of where you are.
• Changed: log statuses use the standard status badges, and the table scrolls horizontally on narrow screens without breaking the layout.

2.5.7

• Fixed: galleries rendered with no styling. The gallery stylesheet was registered under a filename that does not exist, so the browser received a 404 and every gallery fell back to unstyled markup — on the front end via both the block and the [mdpai_gallery] shortcode, inside the Gutenberg editor, and in the Shortcode Builder’s live preview.
• Fixed: the Shortcode Builder preview now loads the same gallery assets a visitor gets, by reusing the registered handles instead of repeating file paths that could drift apart.
• Fixed: lightbox behaviour is available in the builder preview, so switching to a lightbox layout shows what it will actually do.

2.5.6

• Changed: Folder templates and Shortcode builder are separate sidebar destinations under Build, instead of two sub-tabs inside one “Galleries & documents” screen. Existing links to the old screen redirect to the right one.

2.5.5

• Fixed: Upload Activity was always empty on “All time.” The query bound an empty date to a datetime column, which matches nothing — so the one range people pick when the shorter ones look empty was guaranteed to return no data.
• Fixed: date ranges were calculated in UTC but compared against upload times stored in your site’s timezone, so every range was offset by your UTC offset and uploads near the boundary fell on the wrong side of it.
• Fixed: the Analytics screen is available to anyone with the MediaPilot settings capability, but its data required the WordPress administrator capability — so a non-admin could open the page and watch every chart fail. Both now agree.
• Changed: an empty Upload Activity chart says uploads fall outside the selected dates and offers to switch to All time, instead of leaving a blank box that reads as a broken chart.

2.5.4

• Fixed: switches on the Optimization screen appeared in two different styles and colours, because some controls were plain checkboxes picking up styling from the active theme. All on/off controls now use one switch, and MediaPilot screens are insulated from other plugins’ and themes’ checkbox styling.

2.5.3

• Fixed: bulk image optimization never finished. Each batch re-selected the same images instead of moving on, so the counter climbed past the total (“1405 of 444”) and the run continued until stopped by hand. Batches now skip anything already attempted and stop when there is nothing left.
• Fixed: images that cannot be converted are counted separately instead of being offered for conversion forever. The screen says how many failed, why, and offers to retry them once the cause is fixed.
• New: the screen detects when the server’s image library has no WebP support at all — the case where every single conversion fails for a reason unrelated to the plugin — and says so rather than letting you retry hundreds of images that cannot succeed.
• New: redesigned admin. A grouped sidebar replaces the six tabs plus a “More” dropdown, so nothing is hidden behind an overflow menu. Sections are Library, Clean up, Performance, Build, Connect and Configure, and the sidebar collapses to icons if you want the width back.
• New: Trash is its own page under Clean up, instead of a collapsed card stacked beneath Duplicates. It opens with your trashed files already loaded, rather than showing a button that says “Review Trash”.
• New: a shared design system — one set of colours, spacing, type, buttons, form controls, tables and status badges across every screen, instead of each page inventing its own.
• New: reusable metric cards, empty states, loading skeletons, progress bars and help tooltips, so screens can stop hand-rolling markup.
• Changed: each screen now has exactly one page title, with a short description underneath explaining what it is for.
• Changed: settings sub-tabs restyled to match the rest of the interface rather than WordPress’ grey folder tabs.
• Accessibility: a skip-to-content link, visible keyboard focus rings throughout, aria-current on the active section, wide tables made keyboard-scrollable, status communicated by icon and text rather than colour alone, and support for the system “reduce motion” preference.
• Accessibility: the interface is built with logical CSS properties, so Arabic, Urdu and other right-to-left languages mirror correctly.

2.4.0

• New: Google Drive is now part of the Free plugin. Connect one Google account using your own OAuth client — no MediaPilot licence, no Pro badge, no locked controls, and no file or credential passing through BrainStudioz.
• New: OAuth tokens are stored encrypted, never rendered back to the browser, and sent only in request headers from your server. Disconnecting revokes MediaPilot’s access at Google before deleting the local copy.
• New: access is limited to the drive.file scope — files and folders MediaPilot creates. It cannot see the rest of your Drive.
• Changed: the Cloud Storage tab is a working Google Drive setup screen instead of a list of locked provider cards. The remaining providers are listed as Pro without fake connect buttons.
• Changed: == External services == now documents Google Drive, including exactly what is sent and when, and links to Google’s terms, privacy policy, API documentation and user-data policy.
• New: copy, backup and synchronisation to Google Drive — sync new uploads automatically, sync selected files, or sync your whole library. Transfers run in resumable background batches with pause, resume, cancel and retry, and continue after you close the page.
• New: restore a file from Google Drive back to your uploads directory.
• New: large files upload in chunks, so a video is no longer limited by your server’s PHP memory or request timeout, and an interrupted transfer resumes where it stopped rather than starting over.
• New: your MediaPilot folder structure can be mirrored in Drive, with folder renames followed automatically. Deleting a MediaPilot folder never deletes anything in Drive.
• New: a Google Drive settings screen — enable transfers, sync new uploads, follow replacements, mirror folders, choose originals and/or generated sizes, and set the batch size. Transfers show live progress with Pause, Resume, Cancel and Retry.
• Fixed: connection results are now shown. Success, cancellation and failure messages from the Google sign-in flow were being generated and then discarded, so connecting appeared to do nothing.
• Fixed: the Integrations screen now requires the MediaPilot settings capability. It displays your OAuth client ID and connected Google account, which any user who could upload files was previously able to read.
• Fixed: “Copy the whole library to Drive” reported the size of your library rather than the number of files actually queued, so a second run claimed to queue thousands of files that were already transferred.
• Fixed: Resume and Retry could be started while transfers were disabled, reporting success and then immediately pausing again.
• Security: folder permissions are now enforced on the Duplicates, Unused Media, Trash and File Usage screens, on tags and on file replacement and version history. Files in folders you cannot open no longer appear in those lists, counts or results, and cannot be replaced, rolled back or deleted through them.
• Security: WordPress’ own single-attachment REST route now honours folder permissions, closing a path that returned the filename, dimensions and URL of a restricted file directly by ID.
• Security: library-wide “Resolve all duplicates” and “Empty trash” are refused for users with restricted folders, rather than acting on files they cannot see.
• Security: admin notices on the Integrations screen are signed, so a crafted link can no longer display arbitrary text as a first-party WordPress notice.
• Note: optional offloading — removing the local copy after a verified upload — is built and verification-gated but not yet switched on. It arrives once the verification gate has real-world mileage, because it is the only irreversible operation in the feature.

2.3.0

• New: AI Metadata Assistant — generate alt text, title, caption, description and tags for one image at a time using your own OpenAI or Google Gemini API key. Free, permanent, and not a trial.
• New: every suggestion is shown for review in editable fields. Nothing is saved until you approve it, existing values are flagged before they are replaced, and the plugin warns when generated alt text is too long, too vague, keyword-stuffed, or identical to the caption.
• New: a pre-flight disclosure lists exactly what will be sent — provider, model, image treatment, and any metadata or post context you have opted to include — before the first request.
• New: AI Metadata settings tab with provider, model, language, tone, alt-text length limit, default fields, data-sharing choices, custom instructions, timeout, Test connection and Disconnect.
• New: front-end Document Library block and [mdpai_documents] shortcode for publishing a folder as a downloadable file list.
• New: folder locking, starred folders, sort by file count, and folder creation from inside media modals.
• Security: API keys are stored encrypted, never rendered back to the browser, and sent only in request headers from your server. A MDPAI_AI_API_KEY constant lets you keep the key in wp-config.php instead. The plugin refuses to store a key at all if the server cannot encrypt it.
• Security: uninstall now removes AI credentials and settings, and clears plugin post meta that begins with an underscore, which was previously left behind.
• Changed: the == External services == section now documents OpenAI and Google Gemini. The plugin still contacts nothing unless you configure a provider and request generation.

2.1.1

Security release. Updating is strongly recommended for any site that uses folder permissions.

• Security: folder permissions are now enforced on file listing, folder and bulk ZIP download, search, advanced search, gallery preview, bulk metadata lookup, and the GraphQL folder API. Previously these checked folder ownership only, which in the default “global” folder mode permitted access to every folder — so a user could read or download the contents of a folder that was hidden from them by passing its ID directly.
• Security: the media folder taxonomy is exposed through the WordPress core REST API. The core media collection, the folder collection, and single-folder requests are now filtered by folder permissions.
• Security: the GraphQL folder tree, single-folder lookup, child-folder traversal and file assignment now apply folder permissions. Previously the folder list was read straight from the database, bypassing permission filtering.
• Security: tag routes now require the upload_files capability instead of only requiring the visitor to be logged in.
• Security: assigning or moving attachments between folders now verifies permissions on both the source and the destination, so a restricted file cannot be relocated into a readable folder and then read.
• Security: renaming, re-parenting and deleting a folder now require write and delete permission respectively, rather than read permission.
• Fixed: a role permission that denied access was silently ignored. Setting a role to “Viewer” or “None” on a folder had no effect; those restrictions now apply as configured.
• Changed: permission resolution reads its rules in a single query and caches the result, instead of querying once per folder per level.
• Fixed: the Unused Assets panel now says “Results are still being prepared” while the usage index builds, and refreshes itself when the scan finishes. It previously reported “No unused assets found. Everything in your media library is referenced somewhere.” — the opposite of the truth — until the page was reloaded.
• Fixed: the usage index could be marked complete over a partial or empty scan, which made every attachment on the site appear unused. Indexing now verifies that every item was scanned before reporting completion.
• Fixed: a manual scan started through the REST API could clear the usage table while a background scan was running.
• Fixed: cancelling an index rebuild while a batch was in progress could leave the index permanently stuck at “building”, disabling unused-media features until it was rebuilt by hand.
• Fixed: automatic recovery from an interrupted scan was delayed by the site’s UTC offset, so on sites ahead of UTC it could take hours instead of minutes.
• Fixed: when scheduled tasks are unavailable on a site, indexing now reports that it has not progressed instead of showing a progress bar that never moves.
• Developer: new MediaPilotAI\Security\FolderAccessGate service; new mdpai_permissions_changed action; new mdpai_enforce_grid_permissions filter (see the upgrade notice).

2.1.0

• New: the media usage index now builds automatically in the background after activation, on a scheduled task. Setting up an existing site no longer requires finding and pressing a rebuild button.
• New: live indexing progress (“Scanning 1,240 of 3,800 files”) under Media > Analytics, with pause, resume, and cancel controls.
• New: indexing continues after you close the admin page. Previously the rebuild ran in the browser and was abandoned — leaving the index empty — if the tab was closed.
• Fixed: the Unused Media view, the Smart View counts, the Media list-view Usage column, the attachment details panel, and the unused-media REST endpoints could each report attachments as unused when the usage index had never been built or was mid-rebuild. Every one of them now returns no candidates until the index is complete.
• Fixed: unused-media cleanup is refused while the index is building, so a stale browser tab cannot submit a candidate list assembled before the index was ready.
• Fixed: a fatal error on right-to-left sites running without WPML or Polylang, caused by an undefined constant in the RTL stylesheet fallback.
• Changed: existing installations have their usage index rebuilt once on upgrade, which also clears indexes left permanently stuck at “building” by an interrupted browser rebuild.
• Developer: new mdpai_usage_index_build_complete action and mdpai_usage_index_batch_size filter; new REST routes GET /usage/index and POST /usage/index/{start|pause|resume|cancel}.
• Listing: named the supported migration sources (FileBird, Real Media Library, Wicked Folders, HappyFiles), documented upload-to-selected-folder, folder templates, folder context menus, and folder ZIP download, and added a Free versus Pro comparison.

2.0.1

• Improved the WordPress.org listing with clearer positioning around media organization, cleanup, usage tracking, replacement, optimization, and analytics.
• Refined the plugin title, short description, search tags, screenshots, and FAQs for clearer discovery and evaluation.
• Added clearer explanations for large-library processing, privacy, virtual folders, Free features, and the optional Pro add-on.
• Renamed screenshot assets to the WordPress.org lowercase filename convention and curated the listing to seven screenshots.
• No functional plugin-code changes in this release.

2.0.0

• Added an Upgrade to Pro page under Media and an Upgrade to Pro link on the Plugins screen.

1.6.0

• Added extensible media-usage detection for attachment IDs, lists, serialized data, JSON, upload URLs, custom fields, and supported page-builder data.
• Added developer hooks for custom usage sources, post references, and attachment protection.
• Applied the attachment-in-use protection check throughout unused-media and duplicate cleanup workflows.

1.5.5

• Added a restorable Trash for duplicate and unused-media cleanup candidates.
• Added configurable automatic purging after a retention period.
• Added a final usage check before moving a cleanup candidate to Trash.

1.5.4

• Fixed an HTTP 500 error that could affect the Unused Smart View on sites with large usage indexes.
• Reduced memory use for Smart View counts and large unused-media queries.

1.5.0

• Added hooks that allow add-ons to register and render tabs inside MediaPilot AI Settings.

1.4.0

• Added extension hooks for optimization settings and add-on control of local optimization.

1.1.0

• Added hooks for delivery URLs and attachment upload and deletion events.

1.0.0

• Initial release.
• Added hierarchical media folders with drag-and-drop and bulk assignment.
• Added usage tracking, analytics, duplicate detection, CDN URL rewriting, galleries, and developer integrations.