=== Inciteful Connector ===
Contributors: inciteful
Tags: geo, generative engine optimization, ai, schema, content
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.5.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Import Inciteful GEO content clusters as editable Gutenberg drafts with Article and FAQ schema, receive pushes from Inciteful, and track AI citations.

== Description ==

Inciteful Connector links one WordPress site to one Inciteful client workspace with a dedicated site-scoped WordPress credential, then imports answer-shaped content clusters as draft posts - built from real Gutenberg blocks, with schema.org JSON-LD (Article + FAQPage, and HowTo on procedural pages) and meta title/description.

All content rendering happens server-side in Inciteful; the plugin inserts the result verbatim, so the output stays identical to every other Inciteful export.

Features:

* Connect with an inc_wp_ WordPress credential issued for this exact site and client workspace (configurable API base).
* Import a cluster's pages as draft posts - Gutenberg blocks, schema, meta.
* Idempotent re-import (updates the same posts by cluster + slug; no duplicates).
* Push from Inciteful: saving Connect registers this site, and clusters you push from Inciteful publish straight to Posts (re-push updates the same posts). Inciteful records the live URLs against the deployment.
* Mark a cluster implemented to start Inciteful's time-to-citation tracking.
* Stage immutable Content v2 releases as drafts, publish the exact approved candidate on push, withdraw it safely, and independently verify the public page.

= Push flow =

When you save the Connect settings, the plugin generates a per-site receiver token once, keeps it across re-saves, and pairs this site with Inciteful. The staged inc_wp_ credential becomes active only after exact site registration and a successful scoped workspace read. A push from Inciteful is a nudge, not a content payload: Inciteful calls this site's REST endpoint (/wp-json/inciteful/v1/pull) with the receiver token, the plugin pulls only its bound workspace's cluster, imports it published (updating the same posts by cluster + slug), and replies with the permalinks so Inciteful can show per-URL citation proof. The receiver token is checked in constant time and pushes are rejected until Connect has been paired.

= Coordinated credential migration and rollback =

The scoped backend flag is global and disables the old registration route for every legacy plugin. Inciteful must inventory and prepare every affected WordPress installation before enabling it, including sites that will not use Content v2. Account-wide credentials may also be shared by REST, CLI, MCP or automation consumers; revocation is permitted only after that complete key-use group has a tested replacement. If any affected site cannot migrate, the global flag must remain off.

Connector 1.4 keeps the old account value out of runtime use in non-autoloaded quarantine and keeps the active receiver token in its dedicated option for a bounded rollback window. A coordinated rollback must restore both exact legacy settings fields on every upgraded site while the scoped flag is still on, downgrade every site, and only then turn the global flag off. An explicit WordPress administrator runs:

`wp --user=<administrator> inciteful connector restore-legacy --confirm=RESTORE_QUARANTINED_INCITEFUL_LEGACY_CREDENTIAL`

The command restores only the exact legacy settings fields, is idempotent, and never displays either secret. Any failure stops rollback. An aborted recovery can be safely cancelled while remaining on 1.4 with `cancel-legacy-restore --confirm=CANCEL_INCITEFUL_LEGACY_RECOVERY`. After the rollback window, Inciteful must replace every remaining consumer, revoke the account-wide key server-side, and purge quarantine with `finalize-legacy-migration --confirm=FINALIZE_REVOKED_INCITEFUL_LEGACY_CREDENTIAL`. Finalization requires a durable paired active inc_wp_ credential and no pending replacement or restore. All three actions are WP-CLI-only and administrator-authorized.

== External services ==

This plugin is a client for the Inciteful service and connects to the Inciteful API to fetch your content. It requires an Inciteful account and does not function without one.

* Service: Inciteful (provided by VALKER), https://tryinciteful.com
* When it connects: only on actions you initiate - when you save your connection settings (which also registers this site for push), when you list or import your content clusters in wp-admin, and when a push you trigger from Inciteful asks this site to pull a cluster.
* What is sent: your site-scoped WordPress credential; on Connect save, your site URL, site name, and a randomly generated receiver token (so Inciteful can authenticate its pushes to this site); on legacy import or push, the id of the cluster. Content v2 deployment receives an immutable approved HTML artifact and release identities. Public Content v2 verification returns non-content identities and cryptographic hashes only; it does not expose artifact bytes, credentials, or visitor data. No site-visitor data and no personal data are sent.
* Where it is sent: the Inciteful scoped WordPress endpoints https://tryinciteful.com/api/v1/wp/site/register, https://tryinciteful.com/api/v1/wp/clusters, https://tryinciteful.com/api/v1/wp/cluster/pages, and https://tryinciteful.com/api/v1/wp/cluster/implemented (the base URL is configurable for an Inciteful-managed sandbox). Content v2 deployment calls the site's own `/wp-json/inciteful/v2/deployments/*` endpoints.
* What is received: legacy content as Gutenberg block markup, schema.org JSON-LD, and meta title/description; Content v2 receives one immutable approved HTML artifact plus bounded metadata. A Content v2 candidate remains a draft until its explicit push publishes the exact owned artifact. Inciteful then verifies the independently fetched public page before recording it as live.

Terms of service: https://tryinciteful.com/terms
Privacy policy: https://tryinciteful.com/privacy

== Installation ==

1. Upload the plugin via Plugins -> Add New -> Upload Plugin, then activate.
2. Ask the Inciteful account owner to issue an inc_wp_ WordPress credential for this exact site and client workspace. It is shown once and must be paired within its displayed binding window.
3. Go to Inciteful -> Connect, paste that inc_wp_ credential, and choose Save & connect. Do not use a general REST/CLI/MCP API key.
4. Go to Inciteful -> Import, pick a cluster, and import it as drafts.
5. Review the drafts under Posts, then publish.

Requires an administrator account so Gutenberg block markup is stored verbatim.

== Frequently Asked Questions ==

= Do I need an Inciteful account? =

Yes. The plugin is a client for Inciteful. An Inciteful account owner must issue a dedicated inc_wp_ WordPress credential for this exact site and client workspace. General account API keys are intentionally rejected.

= What data does the plugin send? =

Only the dedicated site-scoped WordPress credential, the exact site/workspace pairing data described above, and the id of the cluster you choose to import are sent to the Inciteful API. No site-visitor or personal data is sent. See "External services" above.

= Does it conflict with my SEO plugin? =

No. If Yoast, Rank Math, All in One SEO, or SEOPress is active, the plugin defers the meta-description tag to it. The imported JSON-LD is additive and does not duplicate an existing Article schema you have configured elsewhere.

= Are imported posts published automatically? =

Importing from wp-admin never publishes - clusters land as drafts for you to review. Legacy cluster pushes publish immediately. Content v2 candidate creation also remains draft-only. After review and immutable approval in Inciteful, an explicit Content v2 push publishes only that exact owned candidate; independent live verification must still succeed before Inciteful records it as verified live.

= Can I re-import a cluster without creating duplicates? =

Yes. Re-import updates the same posts by cluster and slug, so it is idempotent.

== Screenshots ==

1. Connect - paste the inc_wp_ WordPress credential issued for this exact site and client workspace.
2. Import - pick a content cluster and import its pages as drafts.
3. An imported draft - real Gutenberg blocks with schema.org JSON-LD.

== Changelog ==

= 1.5.0 =
* Removes the Content v2 deployment endpoints: Content v2 was retired on the Inciteful side on 2026-09-03. Legacy import, pull, push and retrofit workflows are unchanged.

= 1.4.0 =
* Replaces account-wide connector authority with a dedicated inc_wp_ credential bound to one site and workspace. A replacement is staged and activated only after exact registration and a scoped read succeed.
* Adds administrator-only WP-CLI recovery, cancellation and finalization actions for a bounded coordinated credential rollback; no action prints or returns the quarantined credential.
* Content v2 WordPress deployment protocol v2 now publishes the exact immutable owned candidate on push and unpublishes only that exact candidate on withdrawal. Replays remain idempotent, altered or unrelated posts fail closed, and public verification remains independent. Legacy import, pull and retrofit workflows remain available through the scoped endpoints.

= 1.3.0 =
* Adds Content v2 draft staging and updating, withdrawal, and credential-free public readback of the exact immutable approved artifact. Content v2 mutations remain draft-only; a WordPress editor publishes, and Inciteful verifies the public page independently.

= 1.2.1 =
* Compliance/housekeeping: front-end output (JSON-LD, retrofit blocks, meta description) moved into a prefixed ICC_Frontend class, settings input sanitisation tightened, and tested up to WordPress 7.0. No functional change.

= 1.2.0 =
* Retrofit receivers: Inciteful can now apply an approved, additive retrofit patch to an existing page (/wp-json/inciteful/v1/retrofit) and revert it cleanly (/wp-json/inciteful/v1/retrofit-revert). Every apply keeps a baseline so revert restores the exact prior content.

= 1.1.0 =
* Push from Inciteful: Connect save now registers the site (per-site receiver token, generated once), and a new REST receiver (/wp-json/inciteful/v1/pull) imports pushed clusters published, updating the same posts by slug, then reports the live URLs back.

= 1.0.0 =
* Initial release: connect, import clusters as Gutenberg-block drafts with schema, mark implemented.

== Upgrade Notice ==

= 1.4.0 =
This is a global coordinated credential migration, not a per-site switch. Install only inside Inciteful's approved maintenance window after every affected legacy WordPress installation and every shared raw-key consumer has a tested migration/replacement plan. Pair and verify every site. Revoke an account-wide key only after its complete key-use group is clear and the rollback window closes, then use the administrator-only finalization command to purge quarantine. Push publishes the exact approved candidate and withdrawal unpublishes it; legacy Content workflows remain available through the scoped site binding.

= 1.3.0 =
Adds the Content v2 deployment and independent readback contract. Re-save Connect if the site needs to refresh its paired receiver registration.

= 1.2.1 =
Compliance and housekeeping update. No functional change - safe to update.

= 1.2.0 =
Adds retrofit apply/revert receivers. Update the plugin, then Inciteful's retrofit actions work against this site.

= 1.1.0 =
Adds push: send clusters from Inciteful straight to this site. Re-save Connect once after updating to register the site.

= 1.0.0 =
Initial release.
