=== GEO Cite 22 ===
Contributors: alessandroang
Tags: seo, ai, generative-engine-optimization, schema, llms-txt
Requires at least: 6.4
Tested up to: 6.9
Requires PHP: 8.1
Stable tag: 1.4.6
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Donate link: https://buy.stripe.com/8x29ATdg3cKU1qC4fV0kE00

Get mentioned and indexed by AI. Generative Engine Optimization (GEO) for WordPress with multi-provider AI.

== Description ==

**GEO Cite 22** adds all the necessary fields and structures to WordPress for optimizing content for Generative Search Engines (**ChatGPT, Claude, Gemini, Perplexity, Mistral, Kimi**). It features automatic field population via multi-provider AI, multi-stack **Schema.org JSON-LD** output, and site-level `llms.txt` file management.

= What the plugin does =

* **14 Post-level GEO fields**: Quick Answer, FAQ, Key Takeaways, Target Queries, Direct Definition, Citation Sources, Key Statistics, Related Entities, Schema Type, Expertise Level, Last Fact Check, Reading Time, Author Override, ItemList Entries.
* **Multi-stack Schema.org JSON-LD**: Organization + BreadcrumbList + Article/BlogPosting/NewsArticle/HowTo/Product/Review/Recipe/Event + FAQPage (optional) + ItemList (optional) — all within a single `@graph` in the `<head>`.
* **Dynamic llms.txt**: Automatically generated with pillar content + contact email + topical clusters.
* **5 AI Providers**: Anthropic (Claude), OpenAI (ChatGPT), Google Gemini, Mistral, Kimi (Moonshot) — featuring native structured tool use for each provider.
* **Three Tiers**: **Base** (Free), **Advanced** (BYOK — Bring Your Own Key), and **Premium** (Managed via geocite22.com proxy with included credits).
* **Audit Log**: Full tracking of all AI generations in a dedicated table (insert-only, including tokens, duration, and credits consumed).
* **Autocalc**: Automatic reading time calculation from post content (~200 words/min, with manual override option).
* **Encryption**: API keys are encrypted at-rest using Sodium secretbox (derived from `AUTH_KEY`).

= Tiers =

**Base (Free)**
GEO fields + JSON-LD + llms.txt. No AI generation. Requires registration at geocite22.com for the Base license.

**Advanced (Low fee, BYOK)**
Configure your own provider API keys — the plugin calls Anthropic/OpenAI/etc. directly. No geocite22 credit consumption.

**Premium (Higher fee, Managed)**
Zero configuration: calls pass through the geocite22.com proxy using Innova.ms keys. Monthly credit allowance included + top-ups available.

= Privacy =

In the **Advanced (BYOK)** tier, AI calls go directly to the provider using your API keys: we see nothing. In the **Premium** tier, calls pass through our proxy, but content is **not logged in plain text**.

See the [full privacy policy](https://geocite22.com/privacy).

= Extension points =

Filterable hooks for developers (see [spec §17](https://geocite22.com/docs)):

* `geo_cite_22_schema_output` — modify JSON-LD payload before output.
* `geo_cite_22_tool_schema` — modify AI tool-use schema.
* `geo_cite_22_field_definitions` — add/remove GEO fields.
* `geo_cite_22_supported_post_types` — whitelist custom post types.
* `geo_cite_22_ai_providers` — register custom AI providers.
* `geo_cite_22_required_capability` — custom capability for plugin management.

== Installation ==

1. Upload the `geo-cite-22` folder to `/wp-content/plugins/`, or install directly from the WP Plugin Directory when available.
2. Activate the plugin through the WordPress **Plugins** menu.
3. Ensure **pretty permalinks** are active (**Settings → Permalinks** → any option other than "Plain").
4. Register a free account at [geocite22.com](https://geocite22.com) to get your Base license key (or upgrade to Advanced/Premium to activate AI features).
5. Paste the license key in **GEO Cite 22 → License**.
6. Configure **GEO Cite 22 → Site Data** (Organization, publisher, topical clusters, pillar content for llms.txt).
7. Enable desired post types in **GEO Cite 22 → Settings**.

== Frequently Asked Questions ==

= Do I need a license even for the Base plan? =

Yes. Starting from v0.1, the plugin requires a valid license key even for the Base tier (free, automatically issued upon registration at geocite22.com).

= Which AI providers are supported? =

Anthropic (Claude), OpenAI (ChatGPT), Google Gemini, Mistral, and Kimi (Moonshot). The tool schema is automatically translated into each provider's native format.

= What is the difference between Advanced and Premium? =

**Advanced (BYOK)** requires your own API keys and is more cost-effective as you pay the providers directly. **Premium** requires no configuration and is simpler for those who don't want to manage multiple API keys. See [Advanced vs Premium](https://geocite22.com/docs/advanced-vs-premium).

= Where are API keys stored? =

In `wp_options` (`geo_cite_22_providers`), encrypted with Sodium secretbox. The encryption key is derived from your `AUTH_KEY` (SHA-256). If `AUTH_KEY` changes, saved keys will become unreadable.

= Does the plugin work without JavaScript on the frontend? =

Yes. The plugin does NOT inject JS into the frontend of client sites. The SEO/GEO output is pure HTML + static JSON-LD in the `<head>`. The only JS is in the admin area (metaboxes + settings).

= Why does /llms.txt return a 404? =

Check: 1) Pretty permalinks are active; 2) The "Publish /llms.txt" toggle is active in both Settings and Site Data; 3) Deactivate and reactivate the plugin to refresh rewrite rules.

= Can I test without consuming AI credits? =

Yes. Set `GC22_MOCK_AI=true` in `wp-config.php`: the "Generate with AI" button will return mock payloads without actually calling the providers.

= Can I support the development of the plugin? =

Yes, thank you! The Base plan is and will remain free. If you'd like to contribute to the open development, patch releases, and the evolution of AI integrations, you can make a donation via Stripe: [Support GEO Cite 22](https://buy.stripe.com/8x29ATdg3cKU1qC4fV0kE00).

== Screenshots ==

1. License page.
2. Dashboard with stats for the last 30 days via the chosen AI provider.
3. Organization data page.
4. Metaboxes in CPTs.

== Changelog ==

= 1.4.6 =
* UX: The Premium tier "Generate with AI" provider dropdown now lists only providers that the geocite22.com proxy actually has configured server-side (managed API keys with active budget). The license validation response now includes `available_managed_providers`, persisted in the license cache and consumed by the metabox. If the webapp temporarily has no managed key for a provider, that option disappears from the dropdown — no more failed AI calls due to a missing managed key surfacing only after the request. Backward compatible: legacy cached license states default to all 5 providers until the next refresh (~12h cron).

= 1.4.5 =
* UX: The "Generate with AI" provider dropdown on the post editor now lists only providers with a configured API key (Advanced/BYOK). Premium tier still shows all five providers (the proxy handles keys server-side). When no provider is configured, the dropdown is replaced by a notice with a direct link to Settings, and the "Generate with AI" button is disabled. No more confusing "missing_api_key" errors after picking an unconfigured provider.

= 1.4.4 =
* Hardening: annotated the last 2 residual Plugin Check warnings on the GEO fields coverage query in `Support\ContentStats` (DirectQuery + NoCaching on a JOIN over wp_posts/wp_postmeta — live aggregate for the dashboard, no caching is useful here).

= 1.4.3 =
* Hardening (Plugin Check warnings cleanup): annotated direct $wpdb queries on the plugin's custom tables (gc22_ai_log, gc22_credits_log) and admin-only diagnostics with phpcs:ignore + motivation; explicit phpcs:ignore on $_POST arrays sanitized downstream and on read-only $_GET flash params; removed the explicit load_plugin_textdomain() call (WP 4.6+ auto-loads translations from the Domain Path header). composer.json is now included in the distribution zip to prevent the "missing composer.json" Plugin Check warning. No functional changes for the user.

= 1.4.2 =
* Compatibility: Updated "Tested up to" flag to WordPress 6.9.
* Hardening: Added translators: comments next to i18n calls with placeholders; revised output escaping in multi-stack JSON-LD and llms.txt; SQL LIKE queries now use $wpdb->esc_like() with prepared statements; enum-only files now include the ABSPATH guard. No functional changes for the user — cleanup required by the official WordPress.org Plugin Check.

= 1.4.1 =
* Fix: The "Interface Language" setting now takes effect immediately. On WordPress 6.7+, "just-in-time" translation loading bypasses the plugin_locale filter; added a second filter on load_textdomain_mofile that always intercepts the .mo path, regardless of how WP loads the domain.

= 1.4.0 =
* New: English translation for the plugin. The interface language automatically follows WordPress (Italian if WP is in Italian, English otherwise). You can force English or Italian from Settings → "Interface Language".
* New: AI generation now automatically detects the post language (compatible with multilingual plugins via the `geo_cite_22_post_language` filter) and instructs the model to respond in the same language.

= 1.3.1 =
* Added 4 screenshots to the plugin's "View details" panel.
* Added a link to support development (optional Stripe donation).

= 1.3.0 =
* Expanded JSON-LD coverage: Direct Definition becomes `description`, Key Takeaways are added to `abstract`, and Key Statistics appear as `Claim` alongside Cited Sources.
* "Generate with AI" now always populates Related Entities and Cited Sources with at least 3 relevant items.

= 1.2.3 =
* Fix: "× Remove" and "+ Add" buttons in FAQ / Statistics / Sources / Entities lists now respond to clicks in all contexts, including the block editor.

= 1.2.2 =
* Fix: Repeater object rows (FAQ, Statistics, Cited Sources, Related Entities) no longer expand to abnormal heights.

= 1.2.1 =
* Fix: "Generate with AI" on BYOK (Advanced) tiers now correctly populates metabox fields for all 5 supported providers (Anthropic, OpenAI, Gemini, Mistral, Kimi).

= 1.2.0 =
* New: 30-day Advanced Starter free trial upon registration at geocite22.com.
* License panel and Dashboard show trial status and remaining days. Automatic downgrade to Base plan upon expiration without interruptions.

= 1.1.0 =
* The "Disconnect" button now notifies the geocite22.com server and immediately frees the plan slot in the user dashboard. Previously required a periodic cron job.

= 1.0.0 =
First stable release. 14 post-level GEO fields, multi-stack JSON-LD in the `<head>`, automatic `llms.txt` generation, multi-provider AI integration, three tiers (Base / Advanced / Premium), AI generation audit log, and at-rest API key encryption.

== Upgrade Notice ==

= 1.4.4 =
Final 2 Plugin Check warnings resolved (ContentStats GEO coverage query). No functional changes.

= 1.4.3 =
Plugin Check warnings cleanup: phpcs:ignore on direct DB queries for custom tables, $_POST/$_GET annotations, removed load_plugin_textdomain() (WP 4.6+ auto-loads). composer.json now bundled in the zip. No functional changes.

= 1.4.2 =
Compatibility e hardening richieste dal Plugin Check WordPress.org. Nessun cambiamento funzionale: aggiornamento consigliato.

= 1.4.1 =
Fix: il selettore "Lingua Interfaccia" non aveva effetto immediato su WordPress 6.7+. Aggiornamento consigliato.

= 1.4.0 =
Added English translation and "Interface Language" setting. Default: Italian if WordPress is in Italian, English otherwise. No DB migration required.

= 1.3.1 =
Added screenshots to the plugin panel and optional donation link in the readme. No changes to database or settings.

= 1.3.0 =
Direct Definition, Key Takeaways, and Key Statistics are now output in the JSON-LD `<head>` (previously populated in the metabox but silenced in the schema). Check with a structured data validator after upgrading.

= 1.0.0 =
First stable release. Configure a strong `AUTH_KEY` in `wp-config.php` (required for API key encryption) and activate pretty permalinks (required for `/llms.txt`).