=== HarperFlow – AI Blog Writer & SEO Autopilot ===
Contributors: thefamoushesham
Tags: ai, seo, content writer, blog automation, geo
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.2
Stable tag: 1.5.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Your blog on autopilot: an AI content writer that researches, writes and publishes SEO articles to WordPress, built to be quoted by AI search.

== Description ==

HarperFlow (https://harperflow.io) puts your WordPress blog on autopilot. It studies your
site, finds the topics your customers search for, then researches, writes and publishes each
article for you. Every article comes with its sources, an FAQ and structured data, and is
built to be quoted by AI search such as ChatGPT, Perplexity and Google's AI answers.

You stay in control. Each article is scheduled before it goes live, so you can read it, edit
it or skip it. If you want to check every article first, turn on approval and nothing is
published until you approve it.

**We will set it up with you.** If you are not technical, or short on time, book a free
15-minute call at https://cal.com/hesham.us/harperflow-client-consultations and HarperFlow's
founder will connect your site with you and walk you through your first article.

HarperFlow is a paid service. The 7-day trial includes three articles and asks for a card.
Plans and prices: https://www.harperflow.io/pricing

= What this plugin does =

The plugin connects your WordPress site to your HarperFlow account in one step: paste a
pairing code and click Connect. It also adds the extras WordPress core has no home for:

* **SEO title & description** — written into Yoast or Rank Math when present, or
  emitted by the plugin itself when no SEO plugin is active.
* **Self-contained HarperFlow article components** — preserves the renderer's
  inline-styled feature header, table of contents, comparison cards, promotional
  CTAs, and author cards on REST writes for HarperFlow-authored posts only.
* **Styled TL;DR box** and **FAQ accordion** — rendered from HarperFlow's structured
  metadata, scoped only to HarperFlow-authored posts so the rest of your site is
  untouched.
* **FAQPage structured data (JSON-LD)** — helps Google, Bing and AI answer engines
  understand each article's FAQ.
* **Wider reading layout** — in an Elementor single post template, a HarperFlow article that
  shows its contents beside the text gets a wider text column on desktop screens. On by
  default; turn it off under **HarperFlow → Reading layout**.

How it works:

1. Registers HarperFlow post meta (`_hf_*`) with `show_in_rest` so HarperFlow can
   write SEO/FAQ/TL;DR data over the REST API.
2. Re-exposes Yoast / Rank Math SEO meta over REST when those plugins are active
   (they hide those keys from REST by default).
3. Serves `GET /wp-json/harperflow/v1/health` so HarperFlow can detect the plugin and
   which SEO engine is live.
4. Preserves HarperFlow-rendered article HTML with a narrow KSES allowlist. Scripts,
   iframes, event handlers, and unsafe URL schemes are still stripped.
5. Adds a **HarperFlow** menu in wp-admin: connection status, the HarperFlow articles
   sent to this site (with their content type + topic cluster), and a link into
   the full HarperFlow dashboard (autopilot, scheduling, veto inbox, GEO reports).

== Installation ==

1. In your WordPress admin, go to **Plugins → Add New**, search for **HarperFlow**, click
   **Install Now**, then **Activate**. (You can also upload `harperflow.zip` under
   **Upload Plugin**.)
2. Go to **HarperFlow** in your wp-admin menu.
3. In your HarperFlow dashboard, add this WordPress site and copy the **pairing code**. If
   you have no account yet, start a trial at https://app.harperflow.io/auth/register
4. Paste the code into **Connect to HarperFlow** and click **Connect**.

That's it. One click links this site to your HarperFlow account — you never create or
copy a password. The plugin mints a WordPress Application Password for HarperFlow
automatically, registers the site, and enables one-click sign-in back to your dashboard.

Stuck at any step? Book a free 15-minute call at
https://cal.com/hesham.us/harperflow-client-consultations and we will do it with you.

== Frequently Asked Questions ==

= Can someone set this up for me? =

Yes. Book a free 15-minute call at https://cal.com/hesham.us/harperflow-client-consultations
and HarperFlow's founder will connect your site with you, choose your settings and walk you
through your first article.

= Is HarperFlow free? =

The plugin is free. HarperFlow itself is a paid service: the 7-day trial includes three
articles and asks for a card. See https://www.harperflow.io/pricing for plans and prices.

= Can I approve articles before they are published? =

Yes. Turn on **Approve each article before it goes live** in your HarperFlow dashboard. New
articles then wait under **Articles → To approve** until you approve them.

= How do I connect my site to HarperFlow? =

Install and activate the plugin, open **HarperFlow** in your wp-admin menu, then paste the
**pairing code** from your HarperFlow dashboard into **Connect to HarperFlow** and click
Connect. The plugin does the rest.

= Do I need to create an Application Password myself? =

No. The plugin creates a WordPress Application Password named "HarperFlow" for you, using
WordPress core, and sends it securely to HarperFlow during the one-click connect. You never
create or copy a password. Application Passwords require WordPress 5.6+ and HTTPS; if they
are turned off on your site (some security plugins, such as Wordfence, have a setting for
this), the plugin tells you so you can turn them back on. Use **Disconnect** to revoke that
password at any time.

If a Reconnect cannot be confirmed (HarperFlow reports an error on its side, or its answer
never arrives), you may see a second password such as "HarperFlow (2)". Leave it in place:
HarperFlow may already publish with it. The next successful connect, or Disconnect,
removes the extra one.

= Do my articles still publish without this plugin? =

Yes. Posts publish and render in your theme either way. Without the plugin, the SEO
title/description and the dedicated styled FAQ/TL;DR sections are not added — but the
FAQ and TL;DR text is inlined into the post body, so no information is lost.

= Should I edit HarperFlow articles in WordPress? =

No. HarperFlow sends each article to WordPress as a draft so you can preview it there, and a
later update from HarperFlow can overwrite changes made in WordPress. Edit, approve, publish
and discard HarperFlow articles in your HarperFlow dashboard.

= Does it touch the rest of my site? =

No. The styling and the content additions only run on single posts that HarperFlow
authored (gated on a meta flag).

= What does the wider reading layout change? =

It only changes HarperFlow articles that show their contents beside the text, and only in an
Elementor single post template (Elementor Pro's Post Content widget) on screens 1025px and
wider. On those articles, the Elementor box that holds the Post Content widget can be up to
1140px wide. In a box that is 860px wide, the text is about 500px wide; at 1140px it is about
780px. The contents stay beside the article and stay in view while you scroll.

The plugin changes only the maximum width of that box. The article never makes the page scroll
sideways and never covers a column next to it. An Elementor container set to Boxed is never made
narrower: if it is wider than 1140px, it keeps its width. With Elementor 3.16 or later, a
container set to Full Width (at the top of the template or inside another container) is left as
it is. With an older Elementor, it is limited to 1140px. A section with two or more columns is
left as it is. Other boxes that are wider than 1140px, or have no limit (a one-column section, or
an Elementor 4 div block or flexbox), are limited to 1140px on these articles. This is
deliberate: it keeps the text at a comfortable reading width. Anything else in the same box (for
example a divider or a button below the article) follows the new width.

The text, or a column next to the article, can get narrower. If your template puts a sidebar
next to the article inside a box that is limited to 1140px, the text and the sidebar get
narrower. In an Elementor 4 row, the box that holds the article can take width from the column
next to it, so that column gets narrower, and the contents can move up beside the text, so the
text gets narrower. If your template looks like this, turn the wider reading layout off.

When the text is about 780px wide or more and the article is no more than 1140px wide, the key
takeaways, disclaimer, sources, FAQ and author card are limited to the width of the text, so
they end where the text ends. In any other article they keep the full width of the article.

Tablets and phones, other posts and pages, HarperFlow articles without the contents beside the
text, and themes that do not use Elementor's Post Content widget are not changed. If your site
uses a page cache, clear it after you update the plugin or change the setting.

= How do I turn off the wider reading layout? =

In wp-admin, open **HarperFlow**, clear **Use the wider reading layout** under **Reading
layout**, and click **Save reading layout**. A developer can also turn it off in code:
`add_filter( 'harperflow_wide_reading_layout', '__return_false' );`

= Which SEO plugins are supported? =

Yoast SEO and Rank Math. HarperFlow writes the matching SEO meta when either is
active; otherwise the plugin emits a basic title and meta description itself.

== External services ==

This plugin connects your site to HarperFlow, a third-party Software-as-a-Service
platform (https://harperflow.io) that writes and publishes articles to your site.
The plugin communicates with two HarperFlow hosts:

* **api.harperflow.io** — the HarperFlow API.
* **app.harperflow.io** — the HarperFlow web dashboard (opened in your browser).

**What is sent, and when:**

* **On Connect** (you paste a pairing code and click Connect): your site URL, your
  WordPress username, and a WordPress Application Password the plugin mints for
  HarperFlow are sent to `api.harperflow.io` so HarperFlow can publish to your site.
  Nothing is sent until you initiate the connection.
* **On "Open HarperFlow Dashboard (SSO)"** (you click the button): your site host
  (used as your HarperFlow account identifier), this plugin's version number, and an
  HMAC-signed timestamp are sent to `api.harperflow.io` to mint a one-click sign-in
  link, then your browser opens `app.harperflow.io`.
* **On HarperFlow article writes**: HarperFlow calls this site's REST API (authenticated
  with the Application Password above) to publish or update its own articles. This
  plugin sends nothing outbound here; it only receives and stores the article data.

No data is transmitted for visitors of your site, and nothing is sent in the
background without an action you took. Use **Disconnect** at any time to revoke the
Application Password and clear the stored credentials.

By connecting, you agree to HarperFlow's Terms of Service
(https://www.harperflow.io/terms-of-service) and Privacy Policy
(https://www.harperflow.io/privacy-policy).

== Screenshots ==

1. The HarperFlow panel inside wp-admin — plugin status, one-click sign-in to your dashboard, and every published article tracked with its content type and topic cluster.
2. Connecting takes one step — paste the pairing code from your HarperFlow dashboard; no passwords or API keys to manage.
3. What a published HarperFlow article looks like on your site — a featured image, a styled comparison table, a TL;DR summary, an FAQ, and JSON-LD schema, engineered to be cited by AI search.

== Changelog ==

= 1.5.4 =
* The plugin's name and description now say what HarperFlow does: it writes and publishes
  articles to your blog. Nothing changes in how the plugin works on your site.
* The installation steps now start from Plugins → Add New.
* New in the FAQ: setup help on a free call, what HarperFlow costs, and how to approve
  articles before they are published.

= 1.5.3 =
* New: a wider reading layout for HarperFlow articles that show their contents beside the
  text, in Elementor single post templates. On screens 1025px and wider, the Elementor box that
  holds the Post Content widget can be up to 1140px wide. In an 860px box the text was about
  500px wide; now it is about 780px. The contents stay beside the article and stay in view.
* When the text is about 780px wide or more and the article is no more than 1140px wide, the
  key takeaways, disclaimer, sources, FAQ and author card above and below the text are limited
  to the width of the text, so their lines do not get too long. In any other article they keep
  the full width of the article.
* Never made narrower: an Elementor container set to Boxed (one that is wider than 1140px keeps
  its width). With Elementor 3.16 or later, a container set to Full Width is left as it is.
  With an older Elementor, it is limited to 1140px. A section with two or more columns is left
  as it is. Other boxes that were wider than 1140px, or had no limit (a one-column section, or
  an Elementor 4 div block or flexbox), are limited to 1140px on these articles. This is
  deliberate: it keeps the text at a comfortable reading width.
* Only the maximum width changes, so the article never makes the page scroll sideways and never
  covers a column next to it. But the text, or a column next to the article, can get narrower:
  when a sidebar is next to the article in a box that is limited to 1140px, or in an Elementor 4
  row. Turn the layout off for such a template.
* Tablets and phones, other posts and pages, and HarperFlow articles without the contents
  beside the text do not change. Articles already on your site change when you update the
  plugin; HarperFlow does not need to send them again. If your site uses a page cache, clear it.
* Turn it off under HarperFlow → Reading layout, or with the `harperflow_wide_reading_layout`
  filter (return false).

= 1.5.2 =
* New: FAQ structured data (FAQPage JSON-LD) for the FAQ inside HarperFlow articles. Articles
  HarperFlow wrote or updated since 19 October 2026 show their FAQ once and had no FAQ structured
  data with earlier versions of the plugin. With 1.5.2 they get it again.
* Articles already on your site get it the next time HarperFlow updates them, for example when
  you edit one in HarperFlow or apply your template to existing articles from the Templates page.
* Fix: articles HarperFlow wrote before 19 October 2026 showed their Key Takeaways and FAQ twice.
  The plugin no longer adds its own copy to an article that shows them itself. Those articles
  keep their FAQ structured data.
* Fix: in the structured data, questions and answers decode HTML entities ("&" instead of
  "&amp;") and keep their line breaks. A password-protected post gets none while it is locked.
* Fix: on WordPress 5.6 to 5.9, saving any post failed while the plugin was active.
* Developer: the `harperflow_faq_schema` filter. Return false to print no FAQPage for a post,
  for example when an SEO plugin already prints one.

= 1.5.1 =
* Security: one-click sign-in ("Open HarperFlow Dashboard (SSO)") is limited to site
  administrators. It signs in as the HarperFlow account owner, so Editors, Authors and
  Contributors can no longer use it.
* Security: the fallback SEO title (used when no SEO plugin is active) is escaped.
* Security: the sign-in request includes the plugin version, so HarperFlow can refuse
  sign-in from older plugin versions.
* Reconnect safety: a failed Reconnect (for example an expired or mistyped pairing code)
  no longer revokes the Application Password HarperFlow publishes with. The previous
  password is revoked only after HarperFlow accepts the new one. When a Reconnect cannot
  be confirmed (an error on HarperFlow's side, or no answer), the new password is kept as
  well, in case HarperFlow already uses it; the next successful connect, or Disconnect,
  removes the extra one.
* Admin: the connect, disconnect, reconnect and advanced settings are shown to site
  administrators only. Other roles see the connection status.
* Clearer connect errors: separate messages for a site already connected to another
  HarperFlow workspace, an account without the rights HarperFlow needs, an Authorization
  header removed by the host, a site address that is not HTTPS or not public, too many
  attempts, an error on HarperFlow's side, and a pairing code that is invalid, expired or
  already used. The Application Passwords message names the security-plugin setting
  (Wordfence, for example) that turns them off.
* Copy: the article counter reads "HarperFlow articles" (it counts drafts too), the admin
  page no longer says HarperFlow auto-publishes and asks you to edit, approve, publish and
  discard HarperFlow articles in HarperFlow, unpublished articles link to a preview, and the
  status column uses WordPress's own status names.
* i18n: every string on the HarperFlow admin screen is now translatable.

= 1.5.0 =
* Docs: added an External Services disclosure (the third-party HarperFlow hosts this
  plugin talks to, exactly what data is sent, and when) and bumped Tested up to 7.0.
* i18n: user-facing admin and front-end strings are now translatable under the
  `harperflow` text domain.
* Hardening: escapers are applied inline at every output site, and the FAQPage JSON-LD
  now encodes with JSON_HEX_TAG so a `</script>` in a question can never break out.
  No behavior change — lint/robustness only.

= 1.4.2 =
* Security: the "Open dashboard (SSO)" handshake now also refuses a non-https API URL, so
  the signed request is only ever sent over https. Completes the https enforcement started
  in 1.4.1 (which covered the connect handshake and the Advanced override) by applying the
  same guard to the third and last outbound call.

= 1.4.1 =
* Security: the Advanced API URL override now requires https:// — a non-secure override
  is rejected at save time with a clear error, and the one-click connect refuses to send
  your Application Password to a non-https API URL even if an old/injected setting has
  one (checked before minting the password, so nothing is created needlessly).
* Clarity: "Treat this code like a password — don't share it" warning next to the pairing
  code field. Whoever redeems the code first links your site to their HarperFlow account.

= 1.4.0 =
* New: true one-click connect. Enter the pairing code from your HarperFlow dashboard and
  click Connect — the plugin mints a WordPress Application Password via core
  (WP_Application_Passwords) and registers this site automatically. You never create or
  copy a password. Replaces the previous "paste your SSO key" step; the returned SSO
  secret is stored in the same option, so the existing HMAC style-preservation, one-click
  SSO, and SEO features work unchanged.
* New: Disconnect button — revokes the HarperFlow Application Password and clears the
  stored SSO secret. Reconnect anytime with a fresh pairing code.
* Clear errors for the WordPress < 5.6 / Application-Passwords-disabled cases (with a
  fallback to connecting from the HarperFlow dashboard).

= 1.3.1 =
* Security: bind style-preservation to a per-site HMAC signature (sso_secret)
  instead of the forgeable _hf_authored meta flag. Authors cannot inject inline
  CSS without a valid HarperFlow integration signature.
* Enhancement: allow color-mix(), clamp(), min(), max() CSS function values
  emitted by the adaptive renderer via the safecss_filter_attr_allow_css filter,
  with a tight security guard blocking url(), expression(), and javascript:.
* Hardening: wrap wp_kses in try/finally so an unexpected throw cannot leak the
  expanded CSS allowlist into other filters in the same request.

= 1.3.0 =
* New: preserve HarperFlow's inline-styled article components on REST writes for
  HarperFlow-authored posts only, while keeping scripts, iframes, event handlers,
  and unsafe URL schemes stripped.

= 1.2.0 =
* New: one-click SSO from wp-admin — “Open HarperFlow Dashboard (SSO)” signs you straight into your HarperFlow dashboard (no password). Paste the SSO key shown in the dashboard after connecting this site. Single-use, short-lived login tokens; minted server-to-server.

= 1.1.0 =
* New: HarperFlow admin dashboard page (wp-admin → HarperFlow) — connection status,
  recent HarperFlow articles with their GEO metadata, and a link into the web
  dashboard. Read-only; never mutates site data. Purely additive over 1.0.0.

= 1.0.0 =
* Initial release: REST-exposed HarperFlow meta, Yoast/Rank Math interop, health
  route, scoped TL;DR + FAQ rendering, FAQPage JSON-LD.

== Upgrade Notice ==

= 1.5.4 =
A new name and description for the plugin. Nothing changes on your site.

= 1.5.3 =
When you update, HarperFlow articles with their contents beside the text get a wider text column in Elementor single post templates on desktop. With Elementor 3.16 or later, full-width containers stay as they are. If the text or a sidebar gets narrower, turn it off in HarperFlow → Reading layout.

= 1.5.2 =
Brings back FAQ structured data (FAQPage JSON-LD) for HarperFlow articles, and older articles no longer show their FAQ and Key Takeaways twice. Existing articles get the structured data the next time HarperFlow updates them. Also fixes saving posts on WordPress 5.6 to 5.9.
