=== Ariadne Related Posts ===
Contributors: uosamuel
Tags: related posts, recommendations, semantic search, embeddings, content discovery
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.9.42
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Related-posts blocks scored by shared tags, categories, and title overlap — with AI-powered semantic matching available in Pro.

== Description ==

Ariadne Related Posts surfaces genuinely related posts for any WordPress site, entirely on its own:

* **Shared tags** — a capped, diminishing-returns tag-overlap score.
* **Shared categories** — the same capped-overlap formula, independent of tags.
* **Title overlap** — Jaccard similarity of stopword-stripped title tokens.

Every signal's weight is adjustable from the Settings screen. Nothing is scored live at page-render time — everything is precomputed on save and kept fresh by background jobs that continue processing on their own, without waiting on site traffic to trigger the next batch, so the plugin stays safe on sites with heavy traffic or full-page caching, and still finishes a large backfill promptly on a quiet site. Everything above runs 100% locally — no external service, no API key, no account, nothing to configure to get started.

Related posts display automatically, or place them yourself with a shortcode, a Gutenberg block, or a widget — your choice. A "Dashboard," "Settings," and "Post Status" admin screen (with an optional dark mode) show background-job progress and per-post status, and each post's edit screen gets a meta box showing its current auto-computed related list, with scores, for transparency.

= Pro & Pro+ =

Upgrading adds real body-text understanding on top of the free signals above (Pro: hybrid local BM25 lexical scoring + Voyage AI semantic embeddings, fused via Reciprocal Rank Fusion), plus WooCommerce/other post-type support, full Customizer style control, manual pin/exclude, Cornerstone Posts, a live-preview button that scores your unsaved draft before you publish, and more. Pro+ adds repeating boxes placed naturally inside the article body, settings export/import, and WP-CLI. See the in-plugin pricing page for the full breakdown.

== Installation ==

1. Upload the `ariadne-related-posts` folder to `/wp-content/plugins/`.
2. Activate the plugin through the "Plugins" screen in WordPress.
3. Visit Settings → Ariadne Related Posts to adjust scoring weights, or just leave the defaults — it works immediately with zero configuration.

== External services ==

This plugin's own scoring and matching (tags, categories, title overlap) runs entirely locally — no data leaves your site for that. It uses the Freemius SDK for licensing, and two optional pieces load an external resource, under the conditions below:

**Freemius (licensing)** — this plugin uses the Freemius SDK to manage plugin updates and Pro/Pro+ license activation. It contacts the Freemius API (`api.freemius.com`) to check your license status and deliver updates; on activation, Freemius shows its own opt-in screen asking permission before any anonymous, non-personal diagnostic data (e.g. site URL, plugin/WordPress/PHP versions) is shared — this is optional and declining it does not affect the plugin's functionality. See Freemius's Privacy Policy: https://freemius.com/privacy/ and Terms of Service: https://freemius.com/terms/

**Google Fonts (Pro/Pro+ only)** — this plugin's own Dashboard, Settings, and Post Status admin screens use a self-hosted typeface (DM Sans, bundled with the plugin) — nothing is requested from Google for those. Separately, if a Pro/Pro+ license is active and a site owner selects one of the curated Google Fonts for the related-posts card styling (Customizer), that one font family is requested from Google's font CDN (`fonts.googleapis.com`) on your site's frontend. No data beyond the standard browser request (e.g. IP address, user agent) is sent to Google. See Google's Privacy Policy: https://policies.google.com/privacy and Google Fonts' own privacy FAQ: https://developers.google.com/fonts/faq/privacy

**Voyage AI (Pro/Pro+ only)** — if a Pro/Pro+ license is active and a site owner has entered their own Voyage AI API key, this plugin sends each post's title and body text to the Voyage AI API (https://voyageai.com) once, when that post is saved and its content has changed, to compute a semantic-embedding vector used for the AI-matching signal. This is entirely opt-in (no key = no calls) and uses the site owner's own account and key, not a shared or plugin-provided one. See Voyage AI's Terms of Service: https://www.voyageai.com/tos and Privacy Policy: https://www.voyageai.com/privacy

== Frequently Asked Questions ==

= Does this call any external service? =

Not in the free version. Every signal (tags, categories, title overlap) is computed locally, with no external API calls, no account, and nothing to configure. Pro adds an optional AI-powered semantic-matching signal, which does call a third-party API (Voyage AI) using your own API key — entirely opt-in, and the plugin works fully without it.

= Does this slow down my site? =

No. Nothing is ever scored at page-render time. Every related-post list is precomputed in the background (in small, budgeted batches) and simply read from a cache when a page loads.

= Can I control where the related-posts block appears? =

Yes — auto-insert after your content, or place it yourself anywhere with the `[ariadne_related]` shortcode, the Gutenberg block, or a widget. (Pro adds choosing the exact paragraph it lands after, and Pro+ adds boxes placed naturally inside the article body.)

= What happens to my settings if I downgrade from Pro/Pro+? =

Nothing is lost. Anything that depends on a Pro/Pro+ feature (custom styling, pinned posts, etc.) simply stops being applied while locked — the underlying data stays saved, and everything picks back up automatically if you upgrade again.

== Screenshots ==

1. Dashboard — system health, background job progress, and AI usage at a glance.
2. Settings — General tab, with auto-insert, content types, and reporting access.
3. Post Status — every published post's embedding and related-list status, with quick filters.
4. A related-posts block on the front end, auto-inserted after the article content.

== Changelog ==

= 1.9.42 =
* Changed: Dashboard's System Health/AI Usage row now gives the usage chart more visual weight relative to the health list, instead of an even split.
* Added: a "Cornerstone Posts" report on the Dashboard — how many posts are currently pinned to always appear as related content sitewide, and a list of which ones, each linking to its edit screen.

= 1.9.41 =
* Changed: every enqueued script/style handle (`arp-admin`, `arp-style`, `arp-blocks`, etc. — 11 handles, 19 registration/reference sites) was still the old short prefix; renamed to `ariadne-*` for the same WordPress.org naming-uniqueness reason as v1.9.38's function/class/option rename. No visible change — same files, same behavior, just how they're registered internally.

= 1.9.40 =
* Fixed: the fix in 1.9.38 that stopped discarding a downgraded site's saved style settings also accidentally removed the license check on the actual Google Fonts CDN request — a downgraded site now correctly keeps its stored font choice in its own card CSS without pinging Google's servers for it, matching this readme's own "Pro/Pro+ only" disclosure again.
* Changed: two more admin page slugs (Settings, Post Status) were still the old `arp-`-prefixed names; now consistent with the rest of the v1.9.38 rename.

= 1.9.39 =
* Fixed: a stale shortcode example in this readme still showed the old `[arp_related]` name — now `[ariadne_related]`, matching what's actually registered.
* Changed: the admin menu slug and Freemius menu config were the last two leftover `arp-`-prefixed identifiers from the v1.9.38 rename; now `ariadne-dashboard`.

= 1.9.38 =
* Fixed: a locked/downgraded site's related-posts styling and Google Fonts selection were silently discarded and replaced with defaults at render time regardless of what was actually saved — settings are always honored now; only the Customizer controls to change them stay Pro-gated.
* Fixed: this readme's Voyage AI Terms/Privacy links (voyageai.com's bare domain now redirect-loops; switched to www.voyageai.com).
* Changed: internal function/class/option prefix renamed for WordPress.org's naming-uniqueness guideline. Existing installs migrate settings, post data, and the internal cache automatically on upgrade — nothing user-facing changes.

= 1.9.34 – 1.9.37 =
* Fixed: narrow-width panel spacing on Dashboard/Settings/Post Status; an int cast before a display value; a tier-check helper failing open for an undefined key; tightened settings-import file validation.
* Added: this readme's External Services section now discloses the Freemius SDK's own license/update-check calls; bundled the DM Sans font's OFL license text.
* Changed: trimmed the header description; made a Preview panel help line tier-aware; internal build-hygiene follow-ups (no functional change).

= 1.9.33 =
* Added: Post Status now has a combined "Status" column (Healthy / Needs update / Missing summary / Not using AI) and one-click filter shortcuts above the existing detailed filters.

= 1.9.31 – 1.9.32 =
* Changed: the Dashboard's Overview KPI row was folded into System Health (it repeated the same signals a second time); dark mode's card borders are now a soft translucent highlight; several mobile-width layout gaps fixed.
* Fixed: a "Quick Settings" card could link into a Customizer section unavailable on the current plan — a locked card now shows its required tier and links to upgrade instead.

= 1.9.29 – 1.9.30 =
* Changed: Dashboard redesigned around what actually needs answering (health, attention, AI/API usage, background activity, configuration). Settings/Post Status also got a visual pass.

= 1.9.26 – 1.9.28 =
* Changed: "Who can view reports" is now a free role-picker for every tier. Removed the Customizer's Custom CSS field in favor of WordPress's own Additional CSS. Admin UI refinement; addressed Plugin Check findings; fixed an incomplete uninstall cleanup.

= 1.9.18 – 1.9.25 =
* Fixed: tag-matching scored zero for non-Post content types; a background job that could get stuck "Running…" with no manual restart.
* Changed: several WordPress.org compliance fixes and admin UI polish (page width, status pills, dark-mode search, reduced-motion, keyboard accessibility).

= 1.9.0 – 1.9.17 =
* Added: a chart hover tooltip, Voyage API call tracking, author exclusion, a per-signal score breakdown tooltip. Fixed the usage chart lagging a day behind. Rewrote the plugin description to lead with what Free actually does.

= 1.6.0 – 1.8.9 =
* IMPORTANT: introduced the Free/Pro/Pro+ split — AI matching and inline related-post boxes became Pro/Pro+ only. Every Pro/Pro+ feature gained a license gate, then physical code-stripping from the Free build. The Ariadne brand mark, named position presets, a duplicate-insertion guard.

= 0.1.0 – 1.5.8 =
* Early development history (multi-post-type support, Cornerstone Posts, the rename from "Echo Related Post" to "Ariadne Related Posts", dark mode, and more) — full detail lives in this plugin's version control.
