@relvehq/agent-ready 0.2.1 → 0.3.1

package/dist/wp/relve-agent-ready/includes/index.php

@@ -1,2 +1,2 @@
-<?php
-// Silence is golden.
+<?php
+// Silence is golden.

package/dist/wp/relve-agent-ready/index.php

@@ -1,2 +1,2 @@
-<?php
-// Silence is golden.
+<?php
+// Silence is golden.

package/dist/wp/relve-agent-ready/readme.txt

@@ -1,75 +1,112 @@
-=== Relve Agent Ready ===
-Contributors: relve
-Tags: markdown, llms.txt, ai, agents, seo
-Requires at least: 6.0
-Tested up to: 6.7
-Requires PHP: 7.4
-Stable tag: 0.1.0
-License: MIT
-License URI: https://opensource.org/licenses/MIT
-
-Serve a clean Markdown version of your posts and pages to AI agents, plus an llms.txt. Browsers always get the normal page.
-
-== Description ==
-
-AI agents and coding assistants (Claude Code, Cursor, Copilot and others) read the web better as Markdown than as themed HTML. Relve Agent Ready answers them with Markdown built from WordPress's own data, while every browser keeps getting your normal page.
-
-An agent can ask in three ways:
-
-* `Accept: text/markdown` on any post or page URL, when it prefers Markdown over (or equally to) HTML. A browser's Accept header, `*/*`, or no header never gets Markdown. The user agent is never used to decide.
-* `<permalink>.md`, for example `https://example.com/my-post.md` (the home page is `/index.md`).
-* `<permalink>?format=md`.
-
-What it serves:
-
-* Posts and pages (published, public, not password-protected, of the post types you enable): YAML front matter (title, canonical, author, published, modified, categories, tags, description, source), one `# Title` heading, the featured image and the content converted to Markdown (headings, lists, links, images, tables, code blocks).
-* The posts front page and category, tag and author archives: a heading and a list of their latest 50 posts.
-* `llms.txt` under your home path: your site name, tagline and links to the `.md` version of up to 200 recent posts and pages.
-* Refined files: upload the zip Relve produces for your site and those hand-checked Markdown files are served first.
-
-Response headers: `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, `Link: <permalink>; rel="canonical"`, `X-Robots-Tag: noindex` (search engines keep indexing your HTML page), `x-markdown-tokens`, `ETag` (304 on `If-None-Match`), `x-agent-ready-source: native | stored | llms`. Markdown asked for by `Accept` is sent with `Cache-Control: private, max-age=300`; `.md`, `?format=md` and llms.txt with `Cache-Control: public, s-maxage=300, stale-while-revalidate=86400`.
-
-The plugin is installed switched off. Nothing changes until you tick "Enabled" in Settings -> Agent Ready.
-
-== Installation ==
-
-1. Upload the `relve-agent-ready` zip in Plugins -> Add New -> Upload Plugin, then activate it.
-2. Go to Settings -> Agent Ready, tick "Enabled" and save.
-3. Optional: choose post types, add excluded paths, pick the llms.txt mode.
-4. Optional: upload the refined-files zip Relve sent you.
-5. Run the three test commands shown in the Status panel.
-
-== Frequently Asked Questions ==
-
-= Will this change what my visitors or Google see? =
-
-No. Browsers send an Accept header that prefers HTML, so they get your normal page. Markdown responses carry `X-Robots-Tag: noindex` and a canonical link to the HTML page.
-
-= My site sits behind Cloudflare, a Worker or another proxy. What must it pass through? =
-
-The `Accept` header, paths ending in `.md`, the `format` query parameter and `/llms.txt` (under your home path) must reach WordPress unchanged. If the proxy caches pages, it should either include `Accept` in its cache key or not cache responses marked `Cache-Control: private`. `?format=md` works through any proxy that forwards the query string.
-
-= I use WP Rocket or another page cache. =
-
-The plugin sets `DONOTCACHEPAGE` on every Markdown response and tells WP Rocket never to cache `.md` URLs or llms.txt. A page cache that already holds the HTML of a page may still answer an `Accept: text/markdown` request with that HTML. That is safe (the agent gets the normal page); the `.md` URL always returns Markdown.
-
-= I use Yoast SEO. =
-
-The description in the front matter uses your Yoast meta description when there is one. If Yoast's own llms.txt feature is on, the "auto" mode leaves llms.txt to Yoast; choose "On" to serve this plugin's version instead.
-
-= What is in the refined-files zip? =
-
-A top-level `md/` folder with one `.md` file per URL path (`/` is `md/index.md`, `/blog/my-post/` is `md/blog/my-post.md`). Other files (such as `.json` sidecars) are skipped. Entries outside `md/`, absolute paths and paths containing `..` are rejected. Uploading replaces the stored set. Files are kept in `wp-content/uploads/relve-agent-ready/md/`, behind a deny-all `.htaccess`, and are only ever sent as text.
-
-= Which pages are never served? =
-
-Drafts, private and password-protected posts, post types you did not enable, search results, feeds, 404s and any path in the excluded list (by default `/wp-admin`, `/wp-login.php`, `/wp-json`, `/feed`, `/cart`, `/checkout`, `/my-account`, `/account` and WordPress's own folders). An `Accept` request for those gets WordPress's normal response; a `.md` or `?format=md` request gets a plain-text 404.
-
-= What happens when I uninstall? =
-
-Deactivating flushes rewrite rules and removes the WP Rocket rules. Deleting the plugin also removes its settings and the refined-files folder.
-
-== Changelog ==
-
-= 0.1.0 =
-* First release: Markdown for posts, pages, the front page and archives via Accept, `.md` and `?format=md`; llms.txt; refined-files upload; WP Rocket and Yoast awareness; settings page with status and test commands.
+=== Relve Agent Ready ===
+Contributors: relve
+Tags: markdown, llms.txt, ai, agents, seo
+Requires at least: 6.0
+Tested up to: 6.7
+Requires PHP: 7.4
+Stable tag: 0.2.1
+License: MIT
+License URI: https://opensource.org/licenses/MIT
+
+Serve a clean Markdown version of your posts and pages to AI agents, plus an llms.txt. Browsers always get the normal page.
+
+== Description ==
+
+AI agents and coding assistants (Claude Code, Cursor, Copilot and others) read the web better as Markdown than as themed HTML. Relve Agent Ready answers them with Markdown built from WordPress's own data, while every browser keeps getting your normal page.
+
+An agent can ask in three ways:
+
+* `Accept: text/markdown` on any post or page URL, when it prefers Markdown over (or equally to) HTML. A browser's Accept header, `*/*`, or no header never gets Markdown. The user agent is never used to decide.
+* `<permalink>.md`, for example `https://example.com/my-post.md` (the home page is `/index.md`).
+* `<permalink>?format=md`.
+
+What it serves:
+
+* Posts and pages (published, public, not password-protected, of the post types you enable): YAML front matter (title, canonical, author, published, modified, categories, tags, description, source), one `# Title` heading, the featured image and the content converted to Markdown (headings, lists, links, images, tables, code blocks).
+* The posts front page and category, tag and author archives: a heading and a list of their latest 50 posts.
+* `llms.txt` under your home path: your site name, tagline and links to the `.md` version of up to 200 recent posts and pages.
+* Rewritten files: with your own OpenAI key, each post is rewritten into clean Markdown with Relve's prompt (see below) and served first.
+* Refined files: upload a zip of Markdown files (a top-level `md/` folder) and those files are served first.
+
+Response headers: `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, `Link: <permalink>; rel="canonical"`, `X-Robots-Tag: noindex` (search engines keep indexing your HTML page), `x-markdown-tokens`, `ETag` (304 on `If-None-Match`), `x-agent-ready-source: native | stored | llms`. Markdown asked for by `Accept` is sent with `Cache-Control: private, max-age=300`; `.md`, `?format=md` and llms.txt with `Cache-Control: public, s-maxage=300, stale-while-revalidate=86400`.
+
+The plugin is installed switched off. Nothing changes until you tick "Enabled" in Settings -> Agent Ready.
+
+= Better Markdown with your own OpenAI key =
+
+The Markdown built from WordPress is faithful but plain. For agent-ready pages that read well (a clear summary, clean headings, tables kept, theme clutter gone), save your OpenAI API key in Settings -> Agent Ready:
+
+* When a post of an enabled type is published or updated, WP-Cron sends it about 30 seconds later (never while you wait on the editor) to Relve's refine service at `https://relvehq.com/api/agent-ready/v1/refine`: the permalink, and a small HTML page with the title, description, canonical link, structured data and the rendered content.
+* Relve rewrites it with its own prompt, using your key for that single OpenAI call, checks the result and sends back the Markdown. The plugin stores it as that post's file in `wp-content/uploads/relve-agent-ready/md/`; it is served first (`x-agent-ready-source: stored`).
+* A post that has not changed since its last rewrite is answered "unchanged" without a model call, so it costs nothing.
+* "Rewrite all now" queues every published post of the enabled types; WP-Cron works through them 5 at a time. The settings page shows progress, posts rewritten, the last run and the last error code.
+* If OpenAI rejects the key or the account is out of quota, rewriting pauses and an admin notice says so. Saving a new key resumes it.
+* Unpublishing or deleting a post deletes its rewritten file. If a rewrite fails, the previous file (or the Markdown built from WordPress) keeps being served.
+* Models: `gpt-4o` (default, the most accurate; about 1 to 2 cents a post), `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o-mini` (cheapest; can mix up whose price is whose on busy pages). Every call spends your own OpenAI key; no Relve account is needed.
+* When Relve improves its prompt, each post is rewritten once on its next run, even if the post itself has not changed.
+
+The key is stored in your site's own options, shown masked (`sk-...abcd`) and only ever sent to the Relve endpoint over https, with redirects disabled. A developer can point the plugin at another endpoint with the `RELVE_AR_REFINE_ENDPOINT` constant or the `relve_ar_refine_endpoint` filter; anything other than https (or http on localhost, for testing) is refused and the key is not sent.
+
+== Installation ==
+
+1. Upload the `relve-agent-ready` zip in Plugins -> Add New -> Upload Plugin, then activate it.
+2. Go to Settings -> Agent Ready, tick "Enabled" and save.
+3. Optional: choose post types, add excluded paths, pick the llms.txt mode.
+4. Optional: paste your OpenAI API key, save, then click "Rewrite all now".
+5. Run the three test commands shown in the Status panel.
+
+== Frequently Asked Questions ==
+
+= Will this change what my visitors or Google see? =
+
+No. Browsers send an Accept header that prefers HTML, so they get your normal page. Markdown responses carry `X-Robots-Tag: noindex` and a canonical link to the HTML page.
+
+= My site sits behind Cloudflare, a Worker or another proxy. What must it pass through? =
+
+The `Accept` header, paths ending in `.md`, the `format` query parameter and `/llms.txt` (under your home path) must reach WordPress unchanged. If the proxy caches pages, it should either include `Accept` in its cache key or not cache responses marked `Cache-Control: private`. `?format=md` works through any proxy that forwards the query string.
+
+= I use WP Rocket or another page cache. =
+
+The plugin sets `DONOTCACHEPAGE` on every Markdown response and tells WP Rocket never to cache `.md` URLs or llms.txt. A page cache that already holds the HTML of a page may still answer an `Accept: text/markdown` request with that HTML. That is safe (the agent gets the normal page); the `.md` URL always returns Markdown.
+
+= I use Yoast SEO. =
+
+The description in the front matter uses your Yoast meta description when there is one. If Yoast's own llms.txt feature is on, the "auto" mode leaves llms.txt to Yoast; choose "On" to serve this plugin's version instead.
+
+= Does Relve see my OpenAI key? =
+
+It passes through Relve's server for the single call that rewrites a post: the plugin sends it in a request header over https, Relve uses it for that one OpenAI call, and does not store or log it. It is never returned and never written to a database, file or cache on Relve's side. On your site it is kept in the plugin's option in your own database, like other plugin API keys, and is never shown in full on the settings page. Relve also receives the post's public permalink and content, which are public anyway. Remove the key at any time with "Remove the saved key"; deleting the plugin deletes it too.
+
+= What does rewriting cost? =
+
+Your OpenAI usage for each rewrite (one model call per changed post, typically a few thousand tokens). Unchanged posts cost nothing.
+
+= Why does the status say "rejected" or "too_little_text" for a post? =
+
+`rejected` means the rewrite did not pass Relve's quality check twice; `too_little_text` means the post is too short to be worth rewriting. Nothing is stored for that post and the Markdown built from WordPress keeps being served.
+
+= What is in the refined-files zip? =
+
+A top-level `md/` folder with one `.md` file per URL path (`/` is `md/index.md`, `/blog/my-post/` is `md/blog/my-post.md`). Other files (such as `.json` sidecars) are skipped. Entries outside `md/`, absolute paths and paths containing `..` are rejected. Uploading replaces the stored set. Files are kept in `wp-content/uploads/relve-agent-ready/md/`, behind a deny-all `.htaccess`, and are only ever sent as text.
+
+= Which pages are never served? =
+
+Drafts, private and password-protected posts, post types you did not enable, search results, feeds, 404s and any path in the excluded list (by default `/wp-admin`, `/wp-login.php`, `/wp-json`, `/feed`, `/cart`, `/checkout`, `/my-account`, `/account` and WordPress's own folders). An `Accept` request for those gets WordPress's normal response; a `.md` or `?format=md` request gets a plain-text 404.
+
+= What happens when I uninstall? =
+
+Deactivating flushes rewrite rules, removes the WP Rocket rules and cancels scheduled rewrites. Deleting the plugin also removes its settings (including the OpenAI key), its rewrite status and post meta, and the refined-files folder.
+
+== Changelog ==
+
+= 0.2.1 =
+* Default model is now gpt-4o: in testing, gpt-4o-mini sometimes gave the prices of example cards on a page to the page itself. gpt-4o-mini stays available.
+
+= 0.2.0 =
+* Better Markdown with your own OpenAI key: posts are rewritten with Relve's prompt through Relve's refine API, in WP-Cron, on publish and update.
+* "Rewrite all now" works through all posts 5 at a time, with progress on the settings page.
+* Status: key saved, posts rewritten, last run, last error code. Rewriting pauses with an admin notice when OpenAI rejects the key or the quota runs out.
+* Unpublished and deleted posts lose their rewritten file. "Clear refined files" also resets the rewrite fingerprints.
+
+= 0.1.0 =
+* First release: Markdown for posts, pages, the front page and archives via Accept, `.md` and `?format=md`; llms.txt; refined-files upload; WP Rocket and Yoast awareness; settings page with status and test commands.

package/dist/wp/relve-agent-ready/relve-agent-ready.php

@@ -1,70 +1,81 @@
-<?php
-/**
- * Plugin Name:       Relve Agent Ready
- * Plugin URI:        https://relvehq.com/agent-md
- * Description:       Serves a Markdown version of posts, pages and archives to AI agents (Accept: text/markdown, .md URLs, ?format=md) plus an llms.txt. Browsers are never affected. Off until enabled in Settings -> Agent Ready.
- * Version:           0.1.0
- * Requires at least: 6.0
- * Requires PHP:      7.4
- * Author:            Relve
- * Author URI:        https://relvehq.com
- * License:           MIT
- * License URI:       https://opensource.org/licenses/MIT
- * Text Domain:       relve-agent-ready
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-define( 'RELVE_AR_VERSION', '0.1.0' );
-define( 'RELVE_AR_FILE', __FILE__ );
-define( 'RELVE_AR_DIR', plugin_dir_path( __FILE__ ) );
-
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-settings.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-negotiation.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-converter.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-markdown-builder.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-response.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-llms.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-store.php';
-require_once RELVE_AR_DIR . 'includes/class-relve-ar-router.php';
-
-/**
- * Activation: default settings (disabled), the refined-files folder with its
- * protection files, fresh rewrite rules and WP Rocket config.
- *
- * @return void
- */
-function relve_ar_activate() {
-	add_option( Relve_AR_Settings::OPTION, Relve_AR_Settings::defaults() );
-	$store = new Relve_AR_Store();
-	$store->ensure();
-	flush_rewrite_rules();
-	add_filter( 'rocket_cache_reject_uri', array( 'Relve_AR_Router', 'rocket_reject_uri' ) );
-	Relve_AR_Router::refresh_rocket();
-}
-
-/**
- * Deactivation: flush rewrite rules and drop our WP Rocket reject rules.
- * Settings and refined files are kept (uninstall removes them).
- *
- * @return void
- */
-function relve_ar_deactivate() {
-	flush_rewrite_rules();
-	remove_filter( 'rocket_cache_reject_uri', array( 'Relve_AR_Router', 'rocket_reject_uri' ) );
-	Relve_AR_Router::refresh_rocket();
-}
-
-register_activation_hook( __FILE__, 'relve_ar_activate' );
-register_deactivation_hook( __FILE__, 'relve_ar_deactivate' );
-
-Relve_AR_Router::init();
-
-if ( is_admin() ) {
-	require_once RELVE_AR_DIR . 'includes/class-relve-ar-admin.php';
-	Relve_AR_Admin::init();
-}
+<?php
+/**
+ * Plugin Name:       Relve Agent Ready
+ * Plugin URI:        https://relvehq.com/agent-md
+ * Description:       Serves a Markdown version of posts, pages and archives to AI agents (Accept: text/markdown, .md URLs, ?format=md) plus an llms.txt. Optionally rewrites posts into better Markdown with Relve's prompt and your own OpenAI key. Browsers are never affected. Off until enabled in Settings -> Agent Ready.
+ * Version:           0.2.1
+ * Requires at least: 6.0
+ * Requires PHP:      7.4
+ * Author:            Relve
+ * Author URI:        https://relvehq.com
+ * License:           MIT
+ * License URI:       https://opensource.org/licenses/MIT
+ * Text Domain:       relve-agent-ready
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+define( 'RELVE_AR_VERSION', '0.2.1' );
+define( 'RELVE_AR_FILE', __FILE__ );
+define( 'RELVE_AR_DIR', plugin_dir_path( __FILE__ ) );
+
+// The Relve refine endpoint. Define it in wp-config.php to override (https
+// only; http is accepted for localhost). Also filterable:
+// relve_ar_refine_endpoint.
+if ( ! defined( 'RELVE_AR_REFINE_ENDPOINT' ) ) {
+	define( 'RELVE_AR_REFINE_ENDPOINT', 'https://relvehq.com/api/agent-ready/v1/refine' );
+}
+
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-settings.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-negotiation.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-converter.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-markdown-builder.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-response.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-llms.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-store.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-router.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-refiner.php';
+
+/**
+ * Activation: default settings (disabled), the refined-files folder with its
+ * protection files, fresh rewrite rules and WP Rocket config.
+ *
+ * @return void
+ */
+function relve_ar_activate() {
+	add_option( Relve_AR_Settings::OPTION, Relve_AR_Settings::defaults() );
+	$store = new Relve_AR_Store();
+	$store->ensure();
+	flush_rewrite_rules();
+	add_filter( 'rocket_cache_reject_uri', array( 'Relve_AR_Router', 'rocket_reject_uri' ) );
+	Relve_AR_Router::refresh_rocket();
+}
+
+/**
+ * Deactivation: flush rewrite rules, drop our WP Rocket reject rules and
+ * every scheduled rewrite. Settings and refined files are kept (uninstall
+ * removes them).
+ *
+ * @return void
+ */
+function relve_ar_deactivate() {
+	Relve_AR_Refiner::unschedule_all();
+	flush_rewrite_rules();
+	remove_filter( 'rocket_cache_reject_uri', array( 'Relve_AR_Router', 'rocket_reject_uri' ) );
+	Relve_AR_Router::refresh_rocket();
+}
+
+register_activation_hook( __FILE__, 'relve_ar_activate' );
+register_deactivation_hook( __FILE__, 'relve_ar_deactivate' );
+
+Relve_AR_Router::init();
+Relve_AR_Refiner::init();
+
+if ( is_admin() ) {
+	require_once RELVE_AR_DIR . 'includes/class-relve-ar-admin.php';
+	Relve_AR_Admin::init();
+}

package/dist/wp/relve-agent-ready/uninstall.php

@@ -1,24 +1,35 @@
-<?php
-/**
- * Uninstall: remove the option and the refined-files folder.
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
-	exit;
-}
-
-require_once __DIR__ . '/includes/class-relve-ar-negotiation.php';
-require_once __DIR__ . '/includes/class-relve-ar-store.php';
-
-delete_option( 'relve_agent_ready' );
-
-if ( is_multisite() ) {
-	delete_site_option( 'relve_agent_ready' );
-}
-
-$relve_ar_store = new Relve_AR_Store();
-$relve_ar_store->delete_all();
-
-flush_rewrite_rules();
+<?php
+/**
+ * Uninstall: remove the options (settings, including the OpenAI key; refine
+ * state; refine queue), the refine post meta, any scheduled rewrites and the
+ * refined-files folder.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
+	exit;
+}
+
+require_once __DIR__ . '/includes/class-relve-ar-negotiation.php';
+require_once __DIR__ . '/includes/class-relve-ar-store.php';
+
+foreach ( array( 'relve_agent_ready', 'relve_agent_ready_refine', 'relve_agent_ready_refine_queue' ) as $relve_ar_option ) {
+	delete_option( $relve_ar_option );
+	if ( is_multisite() ) {
+		delete_site_option( $relve_ar_option );
+	}
+}
+delete_transient( 'relve_ar_refine_lock' );
+
+foreach ( array( '_relve_ar_fingerprint', '_relve_ar_refined_at', '_relve_ar_refined_path' ) as $relve_ar_meta_key ) {
+	delete_post_meta_by_key( $relve_ar_meta_key );
+}
+
+wp_unschedule_hook( 'relve_ar_refine_post' );
+wp_unschedule_hook( 'relve_ar_refine_batch' );
+
+$relve_ar_store = new Relve_AR_Store();
+$relve_ar_store->delete_all();
+
+flush_rewrite_rules();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relvehq/agent-ready",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "Make your site agent-ready: serve every page as clean Markdown to AI agents (Accept: text/markdown, .md URLs, llms.txt), refine it with AI ahead of time, and prove it with a free checker and a visits dashboard. Next.js adapter included.",
   "keywords": [