=== MediaFlow ===
Contributors: at-rank
Tags: media library, folders, media organization, attachments, media cleanup
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.5.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The media library that knows what your site actually uses. Free unlimited folders, plus a Pro tier that tells you where every file is used.

== Description ==

Every media folder plugin gives you folders. MediaFlow also reads your pages,
your Elementor layouts, your ACF fields and your WooCommerce products, and tells
you **what each file is actually for** — which content uses it, and which files
nothing on your site references at all.

It does that without touching a single file on disk.

Folders are organizational only. Moving an attachment into a folder changes
where it appears in the library and nothing else: the file stays exactly where
WordPress put it, the attachment ID does not change, and every URL, thumbnail,
image size, gallery, featured image and page builder reference keeps working.

= Free and Pro =

**Free, and unlimited.** Folders and subfolders, no cap on either. Drag and drop,
keyboard-accessible controls, a bulk action, the folder sidebar in grid and list
view, and the folder picker inside the media modal so your folders are still
there when you go to insert an image.

**Pro.** Everything built on the content scan: folders created automatically
from your pages and products, "where is this file used" on every attachment, the
no-known-usage list with the disk space behind it, duplicate detection,
importers from other folder plugins, folder colours and icons, ZIP download and
per-role folder visibility.

Pro is sold yearly rather than once. Elementor, WooCommerce, ACF and the block
editor keep changing how they store media, and a scan that stops keeping up
does not stop working — it quietly starts giving wrong answers. The yearly
price is what pays for it to keep being right.

= Two ways to organize =

**Manually.** Create folders and subfolders, drag media into them, or use the
keyboard-accessible controls and the "Move to folder" bulk action. An attachment
has one manual folder, the way a file has one place in a filing cabinet.

**Automatically.** Switch on automatic organization and the plugin builds a
folder structure out of your own content:

* `pages/about-us` for each page, named after its slug
* `posts/software-development/my-guide` for posts, under their category
* one folder per selected post type, including custom ones

Media then appears in the folder of every page and post that uses it. Because
these are usage relationships rather than ownership, one logo can appear under
`pages/home`, `pages/about-us` and `pages/contact` at once - and it is still one
attachment.

= What it detects =

* Featured images
* Gutenberg image, gallery, cover, media & text, video, audio and file blocks
* Blocks nested inside groups, columns and reusable blocks
* Classic editor content: `[gallery]`, `[caption]` and `wp-image-NN` markup
* Images in content that carry no ID, resolved by their upload URL
* Elementor documents, when Elementor is installed
* WooCommerce product galleries and variation images, when WooCommerce is installed
* ACF image, file, gallery and repeater fields, when ACF is installed
* Divi, Bricks, Beaver Builder and Breakdance layouts, when they are installed
* Your theme's logo, site icon, header, background and image options

Every integration is optional. None is required and none is loaded by this
plugin — the data is read structurally, so a version bump on their side cannot
break this one.

= What "no known usage" means, exactly =

MediaFlow can tell you which files nothing it scanned refers to. It calls that
**no known usage** rather than making a claim about your whole site, and the
difference matters.

The scan reads a lot, and it still cannot read everything: a file referenced
from a stylesheet, hard-coded into a theme template, or linked from outside your
site is invisible to it. So the interface always shows you what was checked and
what was not, and the only action offered is to **collect the candidates into a
folder for you to review**.

MediaFlow will not delete a file. Not one, not in bulk, not ever. Deleting stays
where it belongs — your Media Library, one informed decision at a time.

= What it will never do =

* Move, rename, copy or delete a file in your uploads folder
* Change an attachment URL, an image size or a thumbnail
* Edit your posts, pages, categories or slugs
* Delete an attachment, under any setting, including from the no-known-usage list
* Delete or rename a folder you made yourself
* Stop working when a license lapses — your folders are free and stay editable

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate it through the Plugins screen.
3. Open **Media → Library** to use folders, and **Media → MediaFlow** to run the
   first-run scan. The scan changes nothing — it reads your content and reports
   what it found, so you can see what the plugin knows before deciding anything.

== Frequently Asked Questions ==

= Will this break my media URLs? =

No. The plugin never moves a file and never rewrites a URL. Folders are stored
as a hierarchical taxonomy on the attachment, which is the same mechanism
WordPress uses for categories.

= What happens when the license expires? =

Nothing is deleted and nothing is hidden. Your folders stay exactly as they
are, the Media Library still filters by them, and every file is untouched. What
stops is changing things: no new folders, no renaming, no moving media, no
automatic organization, and no plugin updates. Activate a license again and all
of it resumes immediately, with your structure intact.

If the license server itself cannot be reached, the plugin keeps working
normally for three days rather than switching itself off over an outage.

= What happens if I deactivate or uninstall the plugin? =

Deactivating changes nothing: your media and your content are untouched, and
your folders are still there when you activate it again. Uninstalling the plugin
also leaves everything alone unless you tick "Delete all folders and settings"
on the settings screen first. Your media files are never deleted either way.

= Can I rename an automatic folder? =

No, and that is on purpose. An automatic folder mirrors a page, a post or a
category, so renaming it by hand would put it out of step with its source at
the next refresh. Change the slug of the page, post or category instead and the
folder follows.

= Why can I not drag media into an automatic folder? =

An automatic folder answers the question "where is this file used?". Dropping a
file into it would state something that is not true, and the next refresh would
remove it again. Manual folders accept drops; automatic ones do not.

= What happens to a post in several categories? =

You choose on the settings screen: its primary category (a primary category set
by Yoast SEO or Rank Math is used when present), its first category, or a folder
under every category it is in.

= Does it slow down a large site? =

Editing one page rescans one page. A full sweep of the site only happens when
you press "Refresh now", and it runs in small batches so it cannot time out.
The folder tree loads folder names and counts, never the attachments themselves.

== Screenshots ==

1. The folder tree beside the Media Library grid.
2. Automatic folders built from pages, posts and categories.
3. Media → MediaFlow, with the batched refresh.

== Changelog ==

Note: this file's version numbers jump from 1.5.1 (matching the plugin
header / MEDIAFLOW_VERSION, the number WordPress actually compares for
updates) straight to 1.3.3 entries that predate the working copy this
changelog now ships with. That jump is a pre-existing inconsistency, not a
gap in the history below 1.5.1.

= 1.5.1 =
* Fixed: "Check Again" on the WordPress Updates screen could silently do nothing, even right after a new version was published on the license server. Update metadata was refreshed at most every 6 hours regardless of what WordPress itself was asked to do, and asking WordPress to recheck did not reset that interval - so a recheck soon after the last one kept quietly showing "This site is up to date" with no new request ever reaching the license server. "Check Again" now always reaches the server.

= 1.3.3 =
* Fixed: WordPress's blue "Drop files to upload" screen appeared when dragging
  media to a folder, covered the folder list and swallowed the drop. It is now
  out of the way while you drag, and back to normal the moment you finish.
  Uploading files by dragging them in from your desktop is unchanged.

= 1.3.2 =
* Fixed: dragging media onto a folder did nothing in grid view. It worked in
  list view, which made it look like a display problem rather than a broken
  feature.
* Fixed: the folder name was centred in its row instead of sitting on the left.
* Changed: the upgrade link now opens the pricing table directly.
* Changed: a new Settings tab icon.

= 1.3.1 =
* Dragging media onto a folder now works properly. Dropping on a folder's name
  did nothing in Firefox; the sidebar scrolled away as you scrolled the library;
  folders below the fold could not be reached; folders inside a collapsed parent
  could not be dropped into; and the drop target blinked while you aimed at it.
  All fixed.
* Every folder you can drop into now lights up as soon as you start dragging.
* The folder list stays on screen while you scroll your media.

= 1.3.0 =
* MediaFlow now has a free tier. Folders, subfolders, drag and drop and the
  media modal picker work with no license at all, and a license that lapses no
  longer takes them away.
* New: "Used on" — every attachment shows which pages, posts and products use
  it, in the media modal, on the attachment screen and as a list view column.
* New: a "No known usage" view with the disk space behind it. It states what was
  checked and what was not, and the only action is to collect the files into a
  folder for review. MediaFlow never deletes a file.
* New: the resolver reads ACF fields, Divi, Bricks, Beaver Builder and
  Breakdance layouts, and your theme's logo, site icon and image options.
* New: folder search, remembered collapse state, folder colours and icons, and
  download a folder as a ZIP.
* New: duplicate file detection, confirmed by hashing rather than by file size.
* New: import folders from FileBird, Real Media Library, HappyFiles, Enhanced
  Media Library, Folders and Wicked Folders. Importing twice is safe.
* New: a first-run scan that reads your content and reports what it found
  without changing anything.
* New: per-role folder visibility.

= 1.2.0 =
* Renamed from Media Library Organization to MediaFlow. Behaviour is unchanged;
  the plugin slug, text domain, classes, options, hooks, term meta, the folder
  taxonomy and the CSS class names all carry the new name.
* The license client now asks the license server for the mediaflow-license/v1
  namespace, so the server must be up to date before a license will activate.
* No migration is shipped and none is needed — 1.1.0 was never deployed.

= 1.1.0 =
* Media → MediaFlow is now two tabs: Settings and License.
* License activation, validation and licensed updates, against the central
  license server. Responses are Ed25519-signed and verified before they are
  trusted.
* Without an active license the plugin makes no changes and offers no updates.
  Nothing is deleted or hidden: existing folders stay visible and the Media
  Library still filters by them.

= 1.0.0 =
* First release: manual folders, automatic organization, the media usage
  resolver, incremental synchronization and the batched full refresh.
