# Alt Goblin

Alt Goblin is a WordPress plugin that generates AI-powered alt text for media library images.

## What it does

The plugin adds generation controls directly to media attachment editing and provides admin tools for large libraries:

- Single-image generation from the attachment UI
- Optional keyword-guided prompting
- Automatic generation on upload (optional setting)
- Bulk generation for images with missing/empty alt text
- Credit tracking (free monthly + paid credits)

## Key features

- **WordPress-native admin integration** on media screens and a dedicated settings page
- **Three settings tabs**: `Settings`, `Bulk Generation`, and `Credits`
- **Credit-aware generation flow** with clear error messages for quota, network, and permission issues
- **Image resizing before API calls** to reduce payload size and improve reliability
- **Security checks** using nonces and capability checks on AJAX endpoints
- **Localization-ready strings** with text domain `alt-goblin`

## Requirements

- WordPress 6.0+
- PHP 7.4+
- GD image functions enabled (for server-side resizing)

## Installation

1. Upload `alt-goblin` to `wp-content/plugins/`
2. Activate the plugin from **Plugins > Installed Plugins**

## Usage

### Generate for one image

1. Open an image in the Media Library details view
2. Click **Generate Alt Text** or **Re-generate Alt Text**
3. (Optional) Toggle **Add keywords** and enter comma-separated terms

### Bulk generation

1. Go to **Settings > Alt Goblin > Bulk Generation**
2. Click **Start Bulk Generation**
3. Watch progress, stats, and logs
4. Click **Stop Processing** to stop after the current image

### Credits

1. Go to **Settings > Alt Goblin > Credits**
2. Review free, paid, and total credit balances
3. Use purchase links for one-time top-ups if needed

## Architecture overview

- `alt-goblin.php`: plugin bootstrap, constants, activation registration
- `admin/settings-page.php`: tabbed settings UI and credit purchase/status display
- `includes/functions.php`: image preprocessing, prompt composition, API calls, upload automation
- `includes/ajax-handler.php`: secure AJAX endpoints for single and bulk generation
- `includes/enqueue-scripts.php`: admin script/style loading and localized strings
- `js/*.js`: modular frontend logic for generation, bulk processing, and keyword toggles

## API integration

The plugin talks to the Alt Goblin API service:

- `POST /register-site` on activation
- `POST /generate` for alt text generation
- `POST /site-usage` for credits/usage data

Depending on workflow, requests may include site URL, site token, optional API key, prompt text, and resized image data.

## Credits model

- Free monthly credits are available without an API key
- Paid credits can be purchased as one-time top-ups
- 1 credit = 1 generated alt text
- Free monthly credits are consumed before paid credits

## Privacy note

Image data and related request payloads are sent to the Alt Goblin API service to generate alt text. Use of the plugin implies consent to this processing for feature functionality.

## Releasing an update via SVN

1. **Check out the SVN repo** (first time only):
   ```bash
   svn co https://plugins.svn.wordpress.org/alt-goblin C:/Users/Jimmy/svn/alt-goblin
   ```

2. **Copy your updated plugin files into trunk:**
   ```bash
   cp -r "D:/Local Sites/alt-friend-plugin-test/app/public/wp-content/plugins/alt-goblin"/* C:/Users/Jimmy/svn/alt-goblin/trunk/
   ```

3. **Stage any new files** (skip if no new files were added):
   ```bash
   svn add --force C:/Users/Jimmy/svn/alt-goblin/trunk/*
   ```

4. **Commit trunk:**
   ```bash
   svn ci C:/Users/Jimmy/svn/alt-goblin/trunk/ -m "Update to version X.X.X"
   ```

5. **Tag the release:**
   ```bash
   svn copy https://plugins.svn.wordpress.org/alt-goblin/trunk \
            https://plugins.svn.wordpress.org/alt-goblin/tags/X.X.X \
            -m "Tagging version X.X.X"
   ```
Remember to update "X.X.X" to the actual version number.

That's it. WordPress will pick up the new version within minutes once the tag exists and `Stable tag` in `readme.txt` matches it.