=== GEO Cite 22 ===
Contributors: alessandroang
Tags: seo, ai, generative-engine-optimization, schema, llms-txt
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.6.1
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 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.6.1 =
* UX: on the Purchase admin page, the "Activate Premium" button is replaced with a "Coming Soon" label — Premium plans are temporarily not purchasable. The webapp checkout blocks Premium attempts server-side too.

= 1.6.0 =
* New: public display of the GEO fields. Six fields (Quick Answer, Key Takeaways, FAQ, Direct Definition, Key Statistics, Citation Sources) can now also be shown to readers, not just emitted in the JSON-LD. Three complementary ways: automatic output in the post content (opt-in, per-field toggle and position in Settings → "Frontend display"); shortcodes (`[gc22_quick_answer]`, `[gc22_faq]`, `[gc22_key_takeaways]`, `[gc22_direct_definition]`, `[gc22_key_statistics]`, `[gc22_citation_sources]`); and native Gutenberg blocks under the "GEO Cite 22" category. The FAQ uses a no-JavaScript &lt;details&gt; accordion. A field placed manually via shortcode or block is not duplicated by the automatic output.

= 1.5.1 =
* Fix: "Generate with AI" failing with "the provider did not return a valid tool_use", especially on Gemini and when generating many fields at once. The token budget was too low (2048): structured multi-field output — plus the internal "thinking" of Gemini 2.x models — got truncated before the tool call was emitted. Raised to 8192.
* Fix: the Gemini error is no longer opaque — it now reports the real reason (finishReason MAX_TOKENS / MALFORMED_FUNCTION_CALL / safety block).
* Fix: the "Primary Schema type" field was not saved when updating/publishing a post. The select sanitizer lowercased the value, discarding valid CamelCase options (Article, BlogPosting, HowTo, FAQPage).

= 1.5.0 =
* Security fix (important): removed the `GC22_MOCK_LICENSE` / `GC22_MOCK_TIER` / `GC22_MOCK_AI` constants entirely. Their `true` default meant any production install that did not redefine them in `wp-config.php` ran in mock mode, granting a fake Premium Unlimited license to every well-formed key. The plugin now always validates the license against the real geocite22.com server — there is no longer any way to enable development mode with a local `define()`.
* Changed: development mode is now the `premium_unlimited` license tier. A dev license issued by a geocite22.com admin unlocks unlimited credits/sites and makes "Generate with AI" return zero-cost mock payloads. It replaces both removed mock constants.
* UX: Removed the technical "Mock license active" banner from the License admin page and the Mock diagnostics rows from the Support page.
* UX: the "API Keys Provider AI" box (Settings) now shows Advanced licenses a link to a step-by-step guide for creating the provider API keys.
* Compatibility: updated "Tested up to" flag to WordPress 7.0.

= 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`).