FolderForge Documentation

1. Getting Started

Installation

In your WordPress admin go to Plugins → Add New, search “FolderForge”, click Install Now, then Activate. Or upload the zip from wordpress.org via Plugins → Add New → Upload Plugin.

wp plugin install folderforge --activate

Activating FolderForge

Activation creates 9 tables under the wp_ff_ prefix and adds a FolderForge menu with Settings, Duplicates, Import and Audit Log pages. No files are moved or renamed. If another folder plugin is active, FolderForge starts in coexistence mode.

The welcome tour

On first visit to the Media Library, a four-step tour points out the folder sidebar, the “New folder” button, drag-and-drop onto folders, and the bulk toolbar. Dismiss it any time; re-run it from FolderForge → Settings → Show tour again.

Creating your first folder

1. Open Media → Library. The FolderForge sidebar appears on the left.
2. Click + New folder, type a name, press Enter.
3. Select files in the grid and drag them onto the folder — or use Move to in the bulk toolbar.
4. Click the folder to filter the library. The breadcrumb shows All Media › Your folder.

2. Working with Folders

Nesting folders

There is no depth limit. Right-click a folder → New subfolder, or drag one folder onto another to nest it. Loop prevention runs server-side, so a parent can never be dropped into its own child. Folders are virtual: files stay in wp-content/uploads/YYYY/MM/ and permalinks never change.

Colors and icons

Right-click → Rename opens the folder editor with a 10-color palette (blue, green, red, amber, purple, teal, pink, brown, ink, default) and a 22-icon grid (portfolio, images, video, audio, users, cart, star, heart, flag, calendar, and more).

Drag and drop

Drag a single file or a multi-selection from the grid onto any folder. Drag folders to reorder siblings or to change parents. Every drop creates one undo entry.

Keyboard shortcuts

The right-click context menu

Open · New subfolder · Rename · Manage access · Delete. The same actions are available from the “⋯” button on each row for touch devices.

3. Tags

When to use tags vs folders

A file lives in exactly one folder but can carry many tags. Use folders for where a file belongs (client, project) and tags for what it is (logo, hero, screenshot). Tags are cross-cutting; folders are hierarchical.

Creating tags manually

Open any attachment → Tags field → type and press Enter. Existing tags autocomplete. Manually created tags carry source: user; AI tags carry source: ai plus a confidence score.

Bulk tagging

Select multiple items in the grid → bulk toolbar → Tag. One undo entry reverses the whole batch.

Filtering by tag

Use the Tag dropdown above the grid, or add ?folderforge_tag=slug to the Media Library URL. Tags can also drive smart folders.

4. AI Features

What the AI does

A vision model looks at an image and returns tags, alt text, a caption and a description. FolderForge stores them per attachment (wp_ff_ai_meta) along with the provider, model and timestamp, and writes alt text to _wp_attachment_image_alt.

Setting up an AI Provider

1. Update to WordPress 7.0 or newer (the core AI Client ships there).
2. Install one official AI Provider plugin: Anthropic, OpenAI or Google. Enter your API key in that plugin — FolderForge never stores keys.
3. In FolderForge → Settings → AI, pick Auto (best available) or lock a specific provider.

Auto-tag & auto alt text on upload

Two separate toggles. When on, every new image is analyzed after upload finishes. Existing alt text is never overwritten.

Manually analyzing an image

Every image edit screen has an Analyze with AI button. Results appear in the Tags and Alt Text fields for review before you save.

Bulk AI analyze

Select files → AI Analyze. Jobs queue through WP-Cron so the UI stays responsive; progress shows in a toast. Images over 20 MB are skipped (filter folderforge_ai_max_bytes).

Third-party services & privacy

When enabled, image data is sent to the provider you installed. Review that provider's terms and privacy policy. FolderForge adds a disclosure to its readme and to the Settings screen.

5. Smart Folders

What's a smart folder

A saved query that behaves like a folder. It updates itself as the library changes and appears under Smart Folders in the sidebar.

The query builder

A live preview count updates as you change filters.

Examples

• Missing alt text — File type: Images · Missing alt text: on
• Recent PDFs — File type: PDF · Uploaded within 30 days
• Large images — File type: Images · Min size 2048 KB · Order by size desc

Ownership

Smart folders are private to their creator. Administrators see all of them. There is no sharing in 1.0.

6. Permissions

The 4 capability levels

Each level includes the ones before it: read sees the folder, write adds and moves files, delete removes them, admin manages the folder itself and its permissions.

Granting to users vs roles

Right-click → Manage access. Search users by name/email with autocomplete, or pick a role from the dropdown. A user's effective level is the highest of their direct grant and any role grants.

Inheritance

A folder with no rules inherits its parent's. Add a rule to a child to override.

Default behavior

No ACL means the folder is open to everyone who can access the Media Library — backward-compatible with sites that never touch permissions.

Bypass rules

Site administrators bypass all checks. A folder's creator always has admin on their own folder.

7. Duplicate Detection

How detection works

Every upload gets a SHA-256 hash (exact matches). Images also get a perceptual aHash — an 8×8 average hash that survives resizing, re-saving and format conversion. Near-duplicates are grouped by Hamming distance.

Upload-time warnings

Before a file leaves the browser, FolderForge hashes it with crypto.subtle and checks the server. If a match exists you see a modal with the existing files and can cancel the upload.

The Duplicates page

FolderForge → Duplicates has two tabs: Exact matches and Similar images. Each group shows thumbnails and edit links so you can decide what to keep.

Thresholds

The similarity threshold (default 5 bits) is adjustable on the Similar images tab. Lower is stricter. Re-hash any file from its edit screen or via POST /duplicates/rehash/{id}.

8. Bulk Operations

Select one or more items in the Media Library grid and a toolbar appears above it with a live selected-count pill.

• Move to — dropdown of the full folder tree
• Tag — add one or more tags to everything selected
• Delete — WordPress's own delete, with FolderForge assignments cleaned up
• AI Analyze — queued via WP-Cron

Undo: every bulk action produces a single audit entry. The toast's Undo button reverses the whole batch within 5 seconds; after that use the Audit Log.

9. Importing from Other Plugins

Go to FolderForge → Import. Every detected source shows a card with folder, file and assignment counts and an Import from X button. Tick Nest under “X Import” root to avoid collisions with folders you already have.

What happens to the source data

Nothing. Importers are read-only — they query the other plugin's tables or taxonomies and never write to them. You can run an import, compare, and deactivate the old plugin when satisfied.

10. Coexistence Mode

FolderForge detects 9 folder plugins: FileBird, HappyFiles, Real Media Library, WP Media Folder, Wicked Folders, Enhanced Media Library, Folders (Premio), Media Library Folders and PixelVault.

• Active — the other plugin is running its hooks. FolderForge hides its sidebar and shows an admin notice, so two sidebars never fight.
• Residual data only — the plugin is deactivated but its tables/taxonomies remain. FolderForge runs in full mode and offers an import.

The override setting

Settings → Sidebar: Auto (default), Always show, or Never show. The detector checks for registered hooks, taxonomies and tables on each admin load; results are cached for one hour.

11. The Audit Log

What gets logged

Every folder, tag and permission mutation — with user, timestamp, action and an undo payload. FolderForge → Audit Log shows the latest 100 entries.

Undoing a change

Click Undo on a toast (5-second window) or on any row in the Audit Log. Undo is supported for folder.create, folder.update, folder.delete, folder.move, folder.assign, bulk.move and upload.auto_assign.

Clearing old entries

The daily folderforge_maintenance_tick cron prunes entries older than the retention period set in Settings (default 90 days).

12. Gutenberg Gallery Block

Adding the block

In the block inserter search “gallery” or “folder” and choose FolderForge Gallery. It renders a live preview in the editor.

Configuration options

• Folder — any folder from the dropdown
• Columns — 1 to 8
• Limit — 1 to 200 images
• Show captions
• Link to — Media file, Attachment page, or None

Frontend styling

Responsive CSS grid, lazy-loaded images, subtle hover zoom, 2 columns on mobile. Override with the .wp-block-folderforge-gallery class in your theme.

13. Developers

REST API reference — 27 endpoints under folderforge/v1

Authenticate with a cookie + nonce (X-WP-Nonce) or Application Passwords. Every endpoint performs object-level permission checks — per-folder ACLs, per-attachment edit_post, and ownership for smart folders — not just capability checks.

Folders     GET/POST         /folders
            GET              /folders/tree
            GET/PATCH/DELETE /folders/{id}
            POST             /folders/{id}/assign
            POST             /folders/{id}/move
            POST             /folders/reorder
            POST             /active-folder

Tags        GET/POST         /tags
            DELETE           /tags/{id}
            GET/POST         /attachments/{id}/tags

Bulk        POST             /bulk/move
            POST             /bulk/tag
            POST             /bulk/delete

AI          GET              /ai/status
            POST             /ai/analyze/{id}
            POST             /ai/bulk-analyze

Audit       GET              /audit
            POST             /audit/{id}/undo

Duplicates  GET              /duplicates/exact
            GET              /duplicates/similar
            POST             /duplicates/rehash/{id}
            POST             /duplicates/check

Permissions GET/POST/DELETE  /folders/{id}/permissions
            GET              /permissions/roles
            GET              /permissions/users

Smart       GET/POST         /smart-folders
            GET/PATCH/DELETE /smart-folders/{id}
            GET              /smart-folders/{id}/attachments
            POST             /smart-folders/preview

Import      GET              /import/status
            POST             /import/{source}

Example — create a folder and assign two attachments:

curl -X POST https://example.com/wp-json/folderforge/v1/folders \
  -u admin:APPLICATION_PASSWORD \
  -H "Content-Type: application/json" \
  -d '{"name":"Brand assets","color":"blue","parent":0}'

curl -X POST https://example.com/wp-json/folderforge/v1/folders/12/assign \
  -u admin:APPLICATION_PASSWORD \
  -H "Content-Type: application/json" \
  -d '{"attachments":[401,402]}'

PHP hooks

JavaScript API

window.FolderForge.api wraps wp.apiFetch with the nonce and base path preset:

const tree = await FolderForge.api.get('/folders/tree');
await FolderForge.api.post('/bulk/move', { attachments: [401, 402], folder: 12 });

Adding a custom importer

add_filter( 'folderforge_importers', function ( $importers ) {
    $importers['acme'] = new Acme_Importer(); // implements FolderForge\Import\ImporterInterface
    return $importers;
} );

The interface requires detect(), counts(), folders() and assignments().

Object-level permission model

Folder operations resolve the caller's effective capability (read < write < delete < admin) by walking the ACL chain up to the root. Attachment operations additionally require current_user_can('edit_post', $id). Smart folders are owner-or-admin only.

14. Troubleshooting

“Something went wrong” in the sidebar

Usually a REST request failing. Open the browser console, look for a 4xx/5xx on /wp-json/folderforge/v1/… and match it against the items below.

“Plugin file does not exist”

A server rewrite is blocking wp-content/plugins/folderforge/. Check .htaccess / nginx rules and any security plugin that hides the plugins directory.

REST endpoints return 404

Re-save Settings → Permalinks to flush rewrite rules. Confirm /wp-json/ works at all — some hosts and security plugins disable the REST API.

AI features not working

Check GET /ai/status. It reports whether WordPress 7.0's AI Client is present, which provider plugins are installed, and whether they have credentials. Bulk jobs need WP-Cron; if it's disabled, run a system cron hitting wp-cron.php.

Slow page loads with thousands of folders

The tree is cached in a transient and invalidated on change. If a host disables object caching, enable a persistent cache (Redis/Memcached). Counts can be switched to lazy mode in Settings → Performance.

15. FAQ

Is FolderForge really free?

Yes. Every feature is in the free plugin. No Pro tier, no locked features, no upsells.

Does it move files on my server?

No. Folders are virtual. Files stay in wp-content/uploads/YYYY/MM/; permalinks never break.

Do I need to configure an AI provider?

No. AI is optional and off by default. Everything else works without it.

Which WordPress version do I need for AI?

7.0+, because FolderForge uses the core AI Client. Folders, tags, smart folders, permissions and duplicates work on 5.8+.

What happens if I already have FileBird (or another folder plugin)?

FolderForge detects it, hides its own sidebar, and offers a one-click import. See Coexistence and Importing.

Does it work with page builders / Elementor / the block editor?

Yes. Every builder that reads the media library sees the same files.

Is it multisite compatible?

Yes. Tables are created per site on activation.

What happens on uninstall?

All 9 wp_ff_ tables and options are removed. Your media files and alt text remain.

Where do I get support?

Free support on the WordPress.org forum. Priority support at support@approidtech.com.

16. Changelog

• Unlimited nested folders with colors, icons, drag-and-drop, context menu and keyboard shortcuts
• Tags with user / AI / system source and confidence
• AI auto-tagging and alt text via the WordPress core AI Client (WP 7.0+)
• Smart folders with a 7-filter query builder and live preview
• Per-folder permissions (read / write / delete / admin) for users and roles, with inheritance
• Bulk move, tag, delete and AI analyze with single-entry undo
• Duplicate detection: SHA-256 exact matches, perceptual aHash near-duplicates, upload-time warning
• Audit log with server-side undo
• FolderForge Gallery block
• Coexistence detection for 9 folder plugins; one-click importers for 7
• 27 REST endpoints under folderforge/v1
• Dark mode, RTL, mobile breakpoints

17. Roadmap

Under consideration for 1.x. Nothing here is a commitment; vote and suggest on the support forum.

• Shared smart folders
• Folder export / import as JSON
• AI-suggested folder placement on upload
• WP-CLI commands for folders, tags and import
• Semantic search over AI descriptions