=== PilotDeck Connector ===
Contributors: aveosoft
Tags: seo, schema, author schema, auto publish, content automation
Requires at least: 5.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Publish content from PilotDeck into WordPress with the SEO meta, FAQ schema and author details that the core REST API silently discards.

== Description ==

If you have ever published to WordPress from an external tool and found the SEO fields
empty afterwards - no meta description, no focus keyword, no canonical, every post
credited to the same admin account - this plugin exists for that exact problem.

PilotDeck Connector publishes content from [PilotDeck](https://pilotdeck.co) into this
WordPress site with the meta title, meta description, focus keyword, canonical URL,
FAQ structured data and the article's author all intact, written into whichever SEO
plugin you already use.

**Why a plugin is needed at all**

WordPress core already exposes `/wp/v2/posts`, so creating a post remotely needs no
plugin. What core cannot do is write SEO meta. Yoast, Rank Math, All in One SEO and
SEOPress store their fields as post meta that is not registered with `show_in_rest`,
so core accepts the request, returns `201 Created`, and discards those fields without
an error. For an SEO workflow that is a broken publish, not a partial one.

This plugin closes that single gap. Its surface is deliberately small.

**What it does**

* Creates and updates posts sent from your PilotDeck account.
* Writes meta title, meta description and focus keyword to whichever supported SEO
  plugin is installed - Yoast SEO, Rank Math, All in One SEO or SEOPress. If none is
  installed, posts still publish normally.
* Writes the canonical URL for Yoast, Rank Math and SEOPress.
* Outputs FAQPage (`schema.org`) structured data in the page head, which SEO plugins
  do not generate because they cannot infer questions and answers from prose.
* Credits each article to its real author (new in 1.3.0) - see "Authors" below.
* Sets the featured image from a remote URL, including images served by CDNs from
  paths with no file extension.
* Assigns categories and tags, creating any that do not already exist.
* Honours a future publish date by scheduling the post rather than publishing it.

**Authors (new in 1.3.0)**

The authors you set up in PilotDeck now carry through to WordPress, so each article
is credited to the person who wrote it instead of one shared account. This supports
the author signals (E-E-A-T) that search engines and AI answers look for.

* **Matched to an existing user.** If a WordPress user who can write posts has the
  same display name as the article's author, the post is credited to that user.
* **Created when missing.** If no such user exists, the plugin creates one with the
  **Author** role, the author's name and bio, and their photo as the profile picture.
  The account gets a random password that is never shown and a placeholder email on
  the reserved `.invalid` domain, so nobody can sign in as it unless a site admin
  sets a password. You can edit, or reassign and delete, these users like any other.
* **Person structured data.** A `schema.org` Person block describing the author
  (name, job title, bio, photo and profile links) is added to the page head of each
  article, next to the FAQ block.
* **Default author as a fallback.** Articles without an author, or any article whose
  author user could not be created, are credited to the user you choose under
  Settings → PilotDeck, as before.

**How connecting works**

On activation the plugin generates a random 48-character key and stores it on your
site. Settings → PilotDeck shows an Integration Key that packs your site address and
that key together, so you paste one value into PilotDeck instead of two. You can
regenerate the key at any time, which immediately stops any previous copy from working.

Requests arrive over your site's REST API and must present that key. Nothing else can
publish through this plugin.

== External services ==

This plugin is a connector for **[PilotDeck](https://pilotdeck.co)**, a paid third-party
content and SEO platform from Aveo Software. The plugin is not useful on its own - it
exists so that a PilotDeck account can publish into this site.

**How data flows**

The plugin does **not** send your site's content, credentials or visitor data anywhere.
It does not phone home, collect analytics, or contact PilotDeck on its own. It only
listens.

PilotDeck connects *inbound* to your site's REST API and sends the content you have
asked it to publish, including the article author's name, bio, photo URL and profile
links. When it does, the plugin returns:

* the created or updated post ID, its public URL and status;
* your site name, site URL and WordPress version;
* which SEO plugin is installed, and the user ID configured as the post author;
* which parts of the request were applied (for example, whether the post was credited
  to a matched or newly created author).

That information is returned only in response to a request that already carries your
Integration Key, and only to whoever made that request.

**Outbound requests (images only)**

When a publish request includes a featured image URL, or an author photo URL for an
author user the plugin is creating, your site downloads that image so it can be added
to your media library. The request goes to whatever host that image is on - normally
PilotDeck's own storage or your image CDN. No other outbound requests are made.

**Terms and privacy**

* PilotDeck website: [pilotdeck.co](https://pilotdeck.co)
* PilotDeck [Terms of Service](https://pilotdeck.co/terms)
* PilotDeck [Privacy Policy](https://pilotdeck.co/privacy)

By connecting this site to PilotDeck you agree to the [Terms of Service](https://pilotdeck.co/terms) and [Privacy Policy](https://pilotdeck.co/privacy). A PilotDeck account
is required to use this plugin.

== Installation ==

1. Install and activate the plugin.
2. Go to **Settings → PilotDeck**.
3. Copy the Integration Key.
4. In PilotDeck, go to **Integrations → WordPress** and paste the key. There is nothing
   else to fill in - the key already contains this site's address.
5. Optional: under **Settings → PilotDeck**, pick the **Default author** used for
   articles that have no author of their own.

Serve your site over HTTPS. The settings screen warns you if it is not, because the key
would otherwise travel in clear text.

== Frequently Asked Questions ==

= Do I need a PilotDeck account? =

Yes. The plugin is a connector; it does nothing without a PilotDeck account sending
content to it.

= I installed this without a PilotDeck account. What happens? =

Nothing. The plugin generates a key, adds one settings screen, and waits. It does not
alter your posts, your users, your theme, your database beyond two options, or your
site's front end until a connected PilotDeck account publishes something. You can
deactivate and delete it and the site is exactly as it was. If you want to see what it
would publish, there is an overview at [pilotdeck.co](https://pilotdeck.co).

= Do I need an SEO plugin? =

No. Posts publish normally either way. If Yoast SEO, Rank Math, All in One SEO or
SEOPress is installed, the plugin also fills in the SEO fields. If none is installed,
there is simply nowhere for a meta description to go.

= How does the plugin decide who the author of a post is? =

It looks for a WordPress user who can write posts and whose display name matches the
article author's name in PilotDeck, ignoring upper and lower case. If it finds one, the
post is credited to that user. If not, it creates a new user with the Author role for
that person. Articles with no author go to the Default author chosen on the settings
screen.

= Will it create user accounts on my site? =

Only when PilotDeck publishes an article whose author has no matching user yet, and
only with the Author role, which can write and edit their own posts and nothing else.
The account has a random password that is never shown and a placeholder email on the
reserved `.invalid` domain, so it cannot receive mail or be signed into until a site
admin sets a password. To avoid a new user, give an existing user the same display
name as the author in PilotDeck before publishing.

= An author was created twice, or not matched to my existing user. Why? =

Matching uses the display name exactly as written, apart from case. "Jane Doe" and
"Jane A. Doe" are different names. Change the display name of your existing user (or
the author's name in PilotDeck) so they are the same, then publish again. Posts already
credited to the extra user can be reassigned when you delete it.

= Does it add author structured data? =

Yes. Each article with an author gets a `schema.org` Person block in the page head,
built by PilotDeck from the author's profile (name, job title, bio, photo and profile
links). It sits alongside any Article schema your SEO plugin outputs. Re-publishing an
article without an author removes the block.

= Where is the Integration Key stored? =

In your site's options table, like any other WordPress setting. It is generated on your
site and never transmitted by the plugin. Treat it like a password: anyone holding it
can publish to your site.

= What happens if I regenerate the key? =

The previous key stops working immediately, everywhere it was pasted. Publishing resumes
once you paste the new key into PilotDeck.

= Can PilotDeck overwrite my existing pages or posts? =

No. Updates are only ever applied to posts this plugin created on this site. A request
that points at anything else - a page, or a post written by a human - is refused rather
than overwritten.

= I pasted a valid key and still get an authentication error. =

Some servers, mainly Apache running PHP over CGI or FastCGI, strip the `Authorization`
header before WordPress sees it. The plugin checks the standard fallback used by those
setups and also accepts an `X-PilotDeck-Key` header. If it still fails, ask your host to
pass the `Authorization` header through to PHP.

= What is removed when I delete the plugin? =

Both of its options and the post meta it wrote, including the FAQ and author structured
data, plus the profile-photo link it set on author users. Your posts, images,
categories, tags and users - including author users the plugin created - are left
untouched, because they belong to your site and are credited on published posts.

== Screenshots ==

1. Settings → PilotDeck. The Integration Key is generated on your own site; copy it once and paste it into PilotDeck. The Default author is used for articles without an author of their own.
2. The Plugins screen, with a direct Settings link and a prompt explaining what to do next after activation.
3. Posts published from PilotDeck, each credited to its own author: an existing user matched by name, or an author user the plugin created.

== Changelog ==

= 1.3.0 =
* New: articles are credited to their real author. The plugin matches an existing user
  by display name, or creates one with the Author role, name, bio and profile photo.
* New: `schema.org` Person structured data for the article's author in the page head.
* New: for author users it creates, the author's photo from PilotDeck becomes their
  profile picture.
* Changed: "Posts are authored by" on the settings screen is now "Default author", the
  fallback for articles without an author.
* Changed: the name is now written PilotDeck throughout.
* Deleting the plugin now also removes the author structured data and photo links it
  stored. Users it created are kept.

= 1.2.1 =
First public release on WordPress.org.

* Publishes posts sent from PilotDeck, with meta title, meta description, focus keyword
  and canonical URL written to Yoast SEO, Rank Math, All in One SEO or SEOPress.
* Emits FAQPage structured data in the page head.
* Sets the featured image from a remote URL, including CDN paths with no file extension.
* Assigns categories and tags, and schedules future-dated posts.
* Restricts updates to posts this plugin created, so a stale post ID cannot overwrite
  unrelated content.
* Works on hosts that strip the `Authorization` header, via the standard fallback and an
  `X-PilotDeck-Key` alternative.
* Removes its options and post meta when the plugin is deleted.

== Upgrade Notice ==

= 1.3.0 =
Adds author support: articles from PilotDeck are credited to their real author, with Person structured data. No settings change needed.
