=== FolderForge – AI-powered media library organizer for WordPress ===
Contributors: approidtech, punitpatel-1
Tags: media library, folders, media organizer, ai, alt text
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Organize the WordPress media library with folders, tags, AI auto-tagging, smart folders, per-folder permissions, and duplicate detection.

== Description ==

[youtube https://www.youtube.com/watch?v=WJeKc0T040E]

**FolderForge turns the WordPress media library into a proper asset manager.** Organize thousands of files with **drag-and-drop folders**, tag them **manually or automatically with an AI provider**, control **access per folder**, catch **duplicates** before they clutter your library, and **undo any change** from a full audit trail.

= Why FolderForge? =

Most media folder plugins stop at nested folders. **FolderForge goes further:**

* **AI auto-tagging and alt text** — vision models generate tags and alt text on upload
* **Tags alongside folders** — files can live in one folder but have many tags
* **Smart folders** — dynamic queries like "PDFs uploaded this month" or "images without alt text"
* **Per-folder permissions** — real ACLs by user or role
* **Duplicate detection with perceptual hashing** — catches near-duplicates, not just exact matches
* **Bulk operations that scale** — batch move, tag, and delete via a proper bulk API
* **Full audit log with undo** — never lose work to a mis-click
* **One-click import** from FileBird, HappyFiles, Real Media Library, WP Media Folder, Wicked Folders, Enhanced Media Library, and Folders (Premio)

= Core Features =

**Folders**

* **Unlimited nested folders** with drag-and-drop
* **Custom folder colors** — 10-color preset palette
* **Custom folder icons** — 22-icon grid picker
* **Right-click context menu** with keyboard shortcuts (F2 rename, Del delete, Ctrl+Shift+N new)
* **Breadcrumb trail** in the Media Library
* **Non-destructive** — files stay in place, permalinks never break

**Tags**

* Files can live in **one folder** but have **many tags**
* **Manual or AI-generated** tags with source + confidence tracking
* **Bulk tag** multiple attachments at once

**AI Features (optional)**

* **AI auto-tagging** on upload using WordPress core AI Client
* **Automatic alt text** for accessibility and SEO
* **Manual "Analyze with AI"** button on any attachment
* **Bulk AI Analyze** for existing media
* **No API keys stored** — credentials live in the official AI Provider connector plugins

**Smart Folders**

* **Saved dynamic queries** — filter by MIME type, upload date, author, size, missing alt text, tags
* **Live preview count** in the builder
* **Owner-only access** — creator or admin

**Permissions**

* **Read / Write / Delete / Admin** capability hierarchy
* **Grant to users OR roles**
* **Inherits from parent** folder unless overridden
* **Site admins bypass** all checks; folder creators always have admin on their own folders

**Bulk Operations**

* **Move**, **Tag**, **AI Analyze**, or **Delete** multiple files at once
* **Toolbar in the Media Library** with a live selected-count and folder dropdown

**Duplicate Detection**

* **SHA-256 exact hashing** — catches identical files
* **Perceptual (aHash)** on images — catches resized / re-saved / format-converted near-duplicates
* **Upload-time warning** — client-side scan before upload, shows existing matches
* **Admin dashboard** grouped by hash

**Audit Log + Undo**

* **Every mutation is logged** with user, timestamp, and undo payload
* **Undo toasts** on destructive actions
* **Server-side undo endpoint** for folder create / update / delete / move, bulk moves, auto-assigns

**Gutenberg Gallery Block**

* **FolderForge Gallery** block — pick a folder, set columns and limit, done
* **Live preview** in the editor
* **Responsive grid** with lazy-loaded images

**Coexistence and Migration**

* **Detects 9 competing plugins** and gracefully disables its own UI when they are active
* **One-click importers** for FileBird, Real Media Library, HappyFiles, WP Media Folder, Wicked Folders, Enhanced Media Library, and Folders (Premio)
* **Source data is never modified** — safe to keep the other plugin running until verified

**Developer Surface**

* **27 REST endpoints** under `folderforge/v1`
* **Object-level permission checks** on every endpoint
* **Filter and action hooks** for custom importers, AI byte limits, and bootstrap events

= AI Provider Integration =

FolderForge integrates with the **WordPress AI Client** (available in WordPress 7.0 and later). Install any **AI Provider connector plugin**, configure it once, and FolderForge will route requests through it automatically. **No API keys are stored** in FolderForge itself.

= Third-Party Services =

When AI features are enabled, image bytes and a fixed prompt are sent to the AI provider you have configured (for example Anthropic, OpenAI, or Google). **This transmission only happens when you enable auto-tagging, auto alt text, or click "Analyze with AI"** on an attachment. See each provider's terms of service and privacy policy for how they process image data.

Provider documentation and policies:

* **Anthropic** — https://www.anthropic.com/legal/consumer-terms
* **OpenAI** — https://openai.com/policies/terms-of-use
* **Google Gemini** — https://policies.google.com/terms/generative-ai

== Installation ==

1. Upload the `folderforge` folder to `/wp-content/plugins/`.
2. **Activate** the plugin through the Plugins menu in WordPress.
3. You will be taken to the **FolderForge welcome dashboard** automatically.
4. *(Optional)* Install and configure an AI Provider connector plugin, then go to **FolderForge → Settings**.
5. Start organizing from the **Media Library sidebar** or the FolderForge menu.

== Frequently Asked Questions ==

= Does FolderForge move my files on the server? =

**No.** Folders are virtual — files stay in `wp-content/uploads/YYYY/MM/`, so **permalinks never break**.

= Is an AI provider required? =

**No.** AI features are optional. Without an AI Provider connector plugin you still get **folders, tags, smart folders, permissions, duplicate detection, and the audit log**.

= Can I import folders from another media-folder plugin? =

**Yes.** Go to **FolderForge → Settings → Import from another plugin**. FolderForge reads data directly from the other plugin's tables or taxonomies and copies it in. **The source data is never modified**, so you can keep the other plugin running until you have verified the import.

Supported sources: **FileBird, Real Media Library, HappyFiles, WP Media Folder, Wicked Folders, Enhanced Media Library, Folders (Premio)**.

= What happens if another folder plugin is active on the same site? =

FolderForge **detects it and disables its own Media Library sidebar** to avoid overlap. All of FolderForge's own admin pages continue to work. Deactivate the other plugin (or use the override in Settings) to re-enable full mode.

= Does it work if my server has broken permalinks / mod_rewrite? =

**Yes.** FolderForge uses the query-string REST format internally, so it works even when `/wp-json/` URLs are broken by missing `.htaccess` or disabled `mod_rewrite`.

= Where can I report bugs or request features? =

Visit **https://approidtech.com/folderforge/support**, use the plugin's **support forum on WordPress.org**, or email **support@approidtech.com**.

== Screenshots ==

1. Media Library with the FolderForge folder tree in the sidebar.
2. Right-click context menu with keyboard shortcuts.
3. Smart Folders builder — filter by MIME type, upload date, alt-text status, size, and more.
4. Duplicate detection page showing exact and perceptually-similar image groups.
5. Permissions modal for granting per-folder access to users or roles.

== Changelog ==

= 1.0.1 =
* Fixed: Folder row stuck in yellow "loading" state after drag-and-drop image onto folder.
* Fixed: Full page reload after bulk-moving files, which reset scroll position and briefly zeroed folder counts.
* Fixed: Folder-to-folder drag now visually reparents the folder in the tree immediately.
* Fixed: Destination folder count now updates instantly on drag-drop and bulk move.
* Added: "Move to root" option in the right-click context menu — promotes any child folder to top level.
* Improved: Instant visual feedback (green flash + count bump) on successful moves; the media grid no longer forces a page reload if wp.media's re-query stalls.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.1 =
Drag-and-drop reliability fixes, no more page reload after bulk move, and a new "Move to root" context menu option.

= 1.0.0 =
Initial release.
