# AI Media Toolkit

WordPress plugin for AI-powered media metadata, SEO filenames, accessibility and safe bulk media management.

**Version:** 1.0.3 · **Author:** PEWIT Labs · **Requires:** WordPress 6.0+, PHP 7.4+

## Repository layout

```
PEWIT LABS/
  AI Media Toolkit/     ← this repo (plugin source, docs, website assets)
```

> **WordPress install folder** must stay `ai-media-toolkit/` (slug from Freemius / wp.org).
> The display name “AI Media Toolkit” is for humans; the ZIP from `./build.sh` already uses the correct slug.

## What it does

AI Media Toolkit scans your media library, generates and completes image metadata
(ALT, title, caption, description) with OpenAI, renames files to SEO-friendly names
while keeping the same attachment ID, and protects you with backups and one-click
rollback before any destructive operation.

## Main features

### AI metadata generation
- Generate ALT, title, caption and description from the image itself (vision model).
- Complete only the missing fields when some metadata already exists (`smart_complete`).
- Generation modes: **Balanced**, **SEO**, **WCAG** (accessibility-first).
- Multilingual: auto-detects language via WPML / Polylang / site locale, or forces a global language.
- Global website context field to steer tone and domain vocabulary.
- Configurable OpenAI model (default `gpt-4o-mini`) and API key test button.

### Scanning & usage detection
- Smart scan of the whole library or only **used** images.
- Usage detection modes: **Strict** (frontend usage only), **Balanced** (image/gallery fields), **Debug** (all meta).
- Detects usage in post content, featured images, WooCommerce galleries, Bricks, EtchWP and ACF fields.
- Filters: missing ALT, incomplete metadata, bad filename, supported only, skipped.
- Skips SVG, small images, and logos/icons/decorative images by filename.

### SEO filenames
- Build SEO filenames from product/page/post usage context.
- Rename existing files **keeping the same attachment ID** (references via ID stay intact).
- Replace a media file in place (keep ID), optional thumbnail regeneration and WooCommerce cache clear.
- Bulk SEO rename: only bad filenames, or all listed images.
- Optional attachment title update after rename.
- Optional raw URL reference replacement in content/meta (off by default for safety since 0.8.12).

### Background queue
- Processes jobs in the background via WP-Cron (every minute).
- Configurable batch size and delay between batches.
- Pause, resume, stop and clear running jobs.
- Live activity log and progress in the admin.

### Safety, backups & recovery
- Auto-backup before file changes, rename, replace and recovery operations.
- Snapshots of image files, attachment metadata and WooCommerce relations.
- One-click rollback of the last operation (file / metadata / WooCommerce, or all).
- Manual recovery snapshots, ZIP export and snapshot deletion.
- Configurable retention period.
- Emergency repair for broken / too-small product images after a bad rename
  (restores the original from the upload month using a confidence score).

### Reports & notifications
- Duplicate and quality analysis with a media health score.
- CSV report export.
- Email notification when a background job finishes, with basic / detailed / full report levels,
  optional failed-items list, filename-change list and CSV attachment.

### Admin
- Top-level admin menu: Dashboard, Generate, Images, SEO Rename, Backup & Recovery, Reports, Settings.
- Media Library bulk actions: generate/complete metadata, SEO rename, SEO rename bad only.
- Full i18n with `.pot` template and bundled Polish (`pl_PL`) translation.

## Installation

Upload the ZIP through WordPress:

Plugins → Add New → Upload Plugin → (replace the current plugin if updating).

The plugin folder must always be `ai-media-toolkit/` and the main file `ai-media-toolkit.php`.

After activating: open **AI Media Toolkit → Settings**, paste your OpenAI API key,
click **Save & Test**, then **Scan images** and start generating.

### Getting an OpenAI API key (beginner-friendly)

> **ChatGPT Plus ≠ API key.** The plugin needs an OpenAI **API key** with pay-as-you-go billing,
> not a ChatGPT chat subscription.

1. Sign up at [platform.openai.com](https://platform.openai.com/).
2. Open [Settings → Billing](https://platform.openai.com/settings/organization/billing), add a payment method, and set a **monthly spend limit**.
3. Go to [API keys](https://platform.openai.com/api-keys) → **Create new secret key** → copy the `sk-…` value immediately (shown once).
4. In WordPress: **AI Media Toolkit → Settings** → paste the key → **Save & Test**.

Full step-by-step guide (PL + EN): `docs/OPENAI_API_KEY_GUIDE.md`.

Default model `gpt-4o-mini` is inexpensive — typically a fraction of a cent per image.

## Requirements

- WordPress 6.0 or newer
- PHP 7.4 or newer (tested up to 8.3)
- An OpenAI API key with access to a vision-capable model
- `ZipArchive` PHP extension (only for ZIP backup export)

## Documentation

User-facing docs for the website and customers:

- **[website/docs/](website/docs/)** — full plugin documentation (EN + PL), ready for `/docs/ai-media-toolkit/` on pewitlabs.com (Markdown + frontmatter).

Developer / internal docs stay in [`docs/`](docs/) (architecture, security, monetization — do not publish as-is).

Key references:

- `website/docs/en/getting-started.md` — install, first scan, Free vs Pro  
- `website/docs/PRODUCT_FEATURE_IDEAS.md` — Pro/Agency killer features backlog  
- `docs/ARCHITECTURE_095.md` — code architecture  
- `docs/OPENAI_API_KEY_GUIDE.md` — PL beginner API key guide  
- `CHANGELOG.md` — version history  

## Notes

This is production release **1.0.2**. Always test bulk operations on staging first,
and keep auto-backup enabled.
