Improve GitHub documentation and public discoverability

README.md

@@ -1,26 +1,70 @@
 # SEO Magic
 
-CalliopeWP repository for SEO Magic.
+A WordPress plugin for AI-assisted SEO metadata, image SEO, and content optimization workflows, developed by CalliopeWP.
 
-## Current Status
+## Overview
 
-The `main` branch contains the validated SEO Magic Free 1.7.0 codebase.
+SEO Magic brings editable AI-assisted SEO workflows into the WordPress dashboard. It helps administrators review SEO coverage, generate or revise titles and meta descriptions, work with social metadata, improve image metadata, and review content from a focused assistant interface. The Free edition in this repository uses a site owner's Google Gemini API key for AI generation and keeps suggestions editable until the user saves them. It supports posts, pages, products, public post types, media, taxonomies, and author archives through WordPress admin screens.
 
-Verified plugin metadata:
+The `main` branch contains the validated SEO Magic Free 1.7.0 codebase. Additional commercial features may be available separately through CalliopeWP.
 
-- Plugin Name: SEO Magic
-- Version: 1.7.0
-- Text Domain: seo-magico
-- Requires PHP: 7.4
+## Key Features
 
-The WordPress.org metadata and changelog remain in `readme.txt`.
+- Bulk SEO metadata review from a paginated admin table.
+- Editable SEO titles and meta descriptions for supported content types.
+- Facebook/Open Graph and Twitter metadata fields.
+- Image title, alt text, caption, and description generation.
+- Content Assistant with snippet previews and editable SEO fields.
+- Autopilot jobs for selected missing metadata and image fields using WordPress Cron.
+- Sequential processing, server locks, and cross-tab coordination to reduce overlapping AI requests.
+- Compatibility settings for Yoast SEO, Rank Math, and All in One SEO.
 
-Archived branches may contain historical source snapshots preserved for reference. The current development base is `main`.
+## Use Cases
 
-## Distribution
+- Review missing SEO metadata across posts, pages, products, and public post types.
+- Generate first drafts of titles and descriptions, then edit them before saving.
+- Improve image metadata in the WordPress media library.
+- Fill selected missing metadata on a schedule with Autopilot.
+- Keep SEO metadata aligned with an active supported SEO plugin.
 
-Use the official CalliopeWP release process for distribution. Do not publish generated ZIP files, database dumps, logs, local configuration files, or credentials.
+## Requirements
 
-## Technical Contact
+- WordPress: 6.3 or higher.
+- PHP: 7.4 or higher.
+- Google Gemini API key for AI-assisted generation.
+- Optional supported SEO provider: Yoast SEO, Rank Math, or All in One SEO.
 
-contacto@calliope.com.ar
+## Installation
+
+1. Install [SEO Magic on WordPress.org](https://wordpress.org/plugins/seo-magico/) from the WordPress Plugins screen, or upload the `seo-magico` folder to `/wp-content/plugins/`.
+2. Activate the plugin in WordPress.
+3. Open SEO Magic > Settings.
+4. Add your Google Gemini API key.
+5. Select your active SEO provider when applicable.
+6. Open Metadata SEO, Multimedia SEO, or Content Assistant and review your first suggestion.
+
+## Documentation
+
+Read the [SEO Magic documentation](https://seomagic.click/documentation/) for setup and feature guidance. The WordPress.org metadata, FAQ, external services notice, screenshots, and changelog remain in `readme.txt`.
+
+## WordPress.org
+
+View [SEO Magic on WordPress.org](https://wordpress.org/plugins/seo-magico/).
+
+## Support
+
+For the Free edition, use the [SEO Magic support forum on WordPress.org](https://wordpress.org/support/plugin/seo-magico/). Do not include API keys, credentials, private URLs, or customer data in public support requests.
+
+## Development
+
+The `main` branch contains the current validated Free version. Use feature branches and pull requests for changes. See `CONTRIBUTING.md` for contribution guidance and `SECURITY.md` for private security reporting.
+
+Do not commit generated ZIP files, database dumps, logs, local configuration files, API keys, or credentials.
+
+## License
+
+SEO Magic is licensed under GPLv2 or later. See `readme.txt` for the WordPress.org license metadata.
+
+## About CalliopeWP
+
+CalliopeWP is the WordPress plugin line developed by Estudio Calliope from Rosario, Santa Fe, Argentina. Explore the [CalliopeWP plugin catalog](https://pluginswordpress.calliope.com.ar/) and [Estudio Calliope](https://calliope.com.ar/).