@relvehq/agent-ready 0.3.1 → 0.4.0

package/README.md

@@ -104,7 +104,7 @@ frameworks" below. For WordPress, the plugin ships inside this package
 | `enabled` | `AGENT_READY_ENABLED` is `1` or `true` |
 | `exclude` | `/api`, `/_next`, auth and admin paths, plus common private pages (account, checkout, cart, dashboard, settings, billing…) and yours; `excludeCommon: false` drops the common list |
 | `llms` | `/llms.txt` built from your `sitemap.xml`; `llms: false` for none |
-| `onHit` | sends each visit to a dashboard when `AGENT_READY_KEY` and `AGENT_READY_ENDPOINT` are set |
+| `onHit` | sends each visit's stats to Relve when `AGENT_READY_KEY` is set (opt-in; `AGENT_READY_ENDPOINT` for another dashboard), see [Share visit stats](#share-visit-stats-with-relve-opt-in) |
 
 Anything you pass wins:
 
@@ -190,6 +190,9 @@ Markdown. The command saves `<out>/<path>.md` plus `<out>/<path>.json`
   page). Relve charges nothing.
 - **Your key:** used for that call only. Relve does not store or log it, and
   it is never written to the output files.
+- **What Relve logs:** for each call, the page URL, the model, the outcome
+  and the size of the result (bytes, words, lines, tokens, headings, links,
+  tables). Not the HTML, not the Markdown, not your key.
 - **Re-run when content changes.** Each saved `.json` holds the page's
   fingerprint; it is sent along, and an unchanged page comes back as
   `unchanged` with no model call (free). `--force` rewrites everything.
@@ -288,6 +291,23 @@ writes a log that `npx agent-ready stats --log <file>` summarises. On
 serverless hosts (Vercel, Amplify) memory and local files don't last between
 requests: implement `HitStore` on your database.
 
+### Share visit stats with Relve (opt-in)
+
+```
+AGENT_READY_KEY=ar_live_yoursite
+```
+
+With that one variable set, `createAgentReady` reports each Markdown request
+an agent makes to `https://relvehq.com/api/agent-ready/v1/hits`: your key, the
+package version, the time, host, path, how the Markdown was asked for, where
+it came from, status, tokens, bytes, the agent's user agent and the time
+taken. Never the Markdown and never the visitor's IP. The report is
+fire-and-forget with a 2 second timeout and never changes the agent's
+response. The key is a label you choose (`ar_` plus 3 to 64 letters, digits,
+`_` or `-`), not a secret. Without it nothing is sent.
+`AGENT_READY_ENDPOINT` sends the same reports to another dashboard instead;
+in code, `reporter({ key, endpoint? })` is the `onHit`.
+
 ## Other frameworks
 
 Express, Connect, Polka, Fastify (via `@fastify/middie`) or a plain `http`

package/dist/core/report.d.ts

@@ -1,9 +1,11 @@
 import type { HitEvent } from "./config";
+/** Relve's ingest URL, used when AGENT_READY_ENDPOINT is not set. */
+export declare const DEFAULT_HITS_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/hits";
 export interface ReporterOptions {
     /** The venture's dashboard key. */
     key: string;
-    /** Ingest URL that receives { key, event }. */
-    endpoint: string;
+    /** Ingest URL that receives { key, client, event }. Default: Relve's. */
+    endpoint?: string;
     /** Give up after this long. Default 2000 ms. */
     timeoutMs?: number;
     /** Injected for tests. */
@@ -11,5 +13,9 @@ export interface ReporterOptions {
 }
 /** An `onHit` that sends each event to the dashboard. */
 export declare function reporter(opts: ReporterOptions): (event: HitEvent) => Promise<void>;
-/** A reporter from env (AGENT_READY_KEY + AGENT_READY_ENDPOINT), or null when either is missing. */
+/**
+ * A reporter from env, or null when AGENT_READY_KEY is missing.
+ * AGENT_READY_ENDPOINT is optional (Relve's by default); when set it must be
+ * http(s), else null.
+ */
 export declare function reporterFromEnv(env: Record<string, string | undefined>): ((event: HitEvent) => Promise<void>) | null;

package/dist/core/report.js

@@ -2,28 +2,42 @@
 // Measure, the easy way: send every agent visit to a dashboard with one key
 // (changes/agent-ready-engine, "easy setup"). Replaces writing an `onHit`.
 //
-//   AGENT_READY_KEY=ar_live_xxx            (the venture's key)
-//   AGENT_READY_ENDPOINT=https://.../hits  (the dashboard's ingest URL)
+//   AGENT_READY_KEY=ar_live_yoursite          (your key: ar_ + 3-64 of A-Z a-z 0-9 _ -)
+//   AGENT_READY_ENDPOINT=https://.../hits     (optional: another dashboard)
 //
-// `reporter()` returns an `onHit` that POSTs { key, event } as JSON, with a
-// short timeout and keepalive. Fire-and-forget like every `onHit`: it never
-// throws and the response never waits for it.
+// With only AGENT_READY_KEY set, visits go to Relve's dashboard
+// (DEFAULT_HITS_ENDPOINT, changes/agent-ready-telemetry). Nothing is sent
+// unless the key is set: reporting is opt-in.
+//
+// What one report holds: the key, the package version and the HitEvent
+// (time, host, path, how the Markdown was asked for and where it came from,
+// status, tokens, bytes, the visitor's user agent, duration). Never the
+// Markdown, never the visitor's IP.
+//
+// `reporter()` returns an `onHit` that POSTs { key, client, event } as JSON,
+// with a short timeout and keepalive. Fire-and-forget like every `onHit`: it
+// never throws and the response never waits for it.
 //
 // EDGE-SAFE. No Node APIs.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HITS_ENDPOINT = void 0;
 exports.reporter = reporter;
 exports.reporterFromEnv = reporterFromEnv;
+const version_1 = require("./version");
+/** Relve's ingest URL, used when AGENT_READY_ENDPOINT is not set. */
+exports.DEFAULT_HITS_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/hits";
 /** An `onHit` that sends each event to the dashboard. */
 function reporter(opts) {
     const f = opts.fetch ?? fetch;
+    const endpoint = opts.endpoint ?? exports.DEFAULT_HITS_ENDPOINT;
     return async (event) => {
         const ctl = new AbortController();
         const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 2000);
         try {
-            await f(opts.endpoint, {
+            await f(endpoint, {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${opts.key}` },
-                body: JSON.stringify({ key: opts.key, event }),
+                body: JSON.stringify({ key: opts.key, client: `npm/${version_1.PACKAGE_VERSION}`, event }),
                 keepalive: true,
                 signal: ctl.signal,
             });
@@ -36,11 +50,17 @@ function reporter(opts) {
         }
     };
 }
-/** A reporter from env (AGENT_READY_KEY + AGENT_READY_ENDPOINT), or null when either is missing. */
+/**
+ * A reporter from env, or null when AGENT_READY_KEY is missing.
+ * AGENT_READY_ENDPOINT is optional (Relve's by default); when set it must be
+ * http(s), else null.
+ */
 function reporterFromEnv(env) {
     const key = env.AGENT_READY_KEY?.trim();
     const endpoint = env.AGENT_READY_ENDPOINT?.trim();
-    if (!key || !endpoint || !/^https?:\/\//.test(endpoint))
+    if (!key)
+        return null;
+    if (endpoint && !/^https?:\/\//.test(endpoint))
         return null;
-    return reporter({ key, endpoint });
+    return reporter({ key, endpoint: endpoint || undefined });
 }

package/dist/core/version.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_VERSION = "0.4.0";

package/dist/core/version.js

@@ -0,0 +1,8 @@
+"use strict";
+// The package version, in one place: the refine user agent and the visit
+// reporter both send it, so Relve can tell which release a venture runs
+// (changes/agent-ready-telemetry). Keep in step with package.json.
+// EDGE-SAFE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_VERSION = void 0;
+exports.PACKAGE_VERSION = "0.4.0";

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export { buildLlmsTxt, type BuildLlmsOptions } from "./core/llms";
 export { byteLength, etagFor, ifNoneMatchHits, markdownResponse, MARKDOWN_CONTENT_TYPE, type RespondOptions } from "./core/respond";
 export { COMMON_PRIVATE_PATHS, createAgentReady, enabledFromEnv, siteFromEnv, type EasyOptions, type Env } from "./core/easy";
 export { entriesFromUrls, humanize, parseSitemap, sitemapEntries, type ParsedSitemap, type SitemapEntriesOptions } from "./core/sitemap";
-export { reporter, reporterFromEnv, type ReporterOptions } from "./core/report";
+export { DEFAULT_HITS_ENDPOINT, reporter, reporterFromEnv, type ReporterOptions } from "./core/report";
+export { PACKAGE_VERSION } from "./core/version";
 export { ANSWER_BOT_TOKENS, classifyAgent, isAnswerBot, type Bot, type BotKind } from "./proof/bots";
 export { filterHits, memoryHitStore, teeHits, type HitQuery, type HitStore } from "./proof/hits";
 export { formatSummary, summarize, type Count, type HitSummary } from "./proof/stats";

package/dist/index.js

@@ -8,7 +8,8 @@
 //   @relvehq/agent-ready/next/route     Next.js route handler
 // and the Next.js middleware adapter lives at @relvehq/agent-ready/next.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatAudit = exports.blockedBots = exports.auditSite = exports.renderDashboard = exports.summarize = exports.formatSummary = exports.teeHits = exports.memoryHitStore = exports.filterHits = exports.isAnswerBot = exports.classifyAgent = exports.ANSWER_BOT_TOKENS = exports.reporterFromEnv = exports.reporter = exports.sitemapEntries = exports.parseSitemap = exports.humanize = exports.entriesFromUrls = exports.siteFromEnv = exports.enabledFromEnv = exports.createAgentReady = exports.COMMON_PRIVATE_PATHS = exports.MARKDOWN_CONTENT_TYPE = exports.markdownResponse = exports.ifNoneMatchHits = exports.etagFor = exports.byteLength = exports.buildLlmsTxt = exports.jsonLdFacts = exports.hasFrontMatter = exports.frontMatter = exports.estimateTokens = exports.enrich = exports.wantsMarkdown = exports.stripMdSuffix = exports.normalizePath = exports.mdUrlPath = exports.isExcluded = exports.isEnabled = exports.emitHit = exports.defineAgentReady = exports.VIA_HEADER = exports.DEFAULT_NEGOTIATED_CACHE_CONTROL = exports.DEFAULT_INTERNAL_PREFIX = exports.DEFAULT_INTERNAL_HEADER = exports.DEFAULT_CACHE_CONTROL = exports.ALWAYS_EXCLUDE = exports.parseAccept = exports.chooseFormat = void 0;
+exports.blockedBots = exports.auditSite = exports.renderDashboard = exports.summarize = exports.formatSummary = exports.teeHits = exports.memoryHitStore = exports.filterHits = exports.isAnswerBot = exports.classifyAgent = exports.ANSWER_BOT_TOKENS = exports.PACKAGE_VERSION = exports.reporterFromEnv = exports.reporter = exports.DEFAULT_HITS_ENDPOINT = exports.sitemapEntries = exports.parseSitemap = exports.humanize = exports.entriesFromUrls = exports.siteFromEnv = exports.enabledFromEnv = exports.createAgentReady = exports.COMMON_PRIVATE_PATHS = exports.MARKDOWN_CONTENT_TYPE = exports.markdownResponse = exports.ifNoneMatchHits = exports.etagFor = exports.byteLength = exports.buildLlmsTxt = exports.jsonLdFacts = exports.hasFrontMatter = exports.frontMatter = exports.estimateTokens = exports.enrich = exports.wantsMarkdown = exports.stripMdSuffix = exports.normalizePath = exports.mdUrlPath = exports.isExcluded = exports.isEnabled = exports.emitHit = exports.defineAgentReady = exports.VIA_HEADER = exports.DEFAULT_NEGOTIATED_CACHE_CONTROL = exports.DEFAULT_INTERNAL_PREFIX = exports.DEFAULT_INTERNAL_HEADER = exports.DEFAULT_CACHE_CONTROL = exports.ALWAYS_EXCLUDE = exports.parseAccept = exports.chooseFormat = void 0;
+exports.formatAudit = void 0;
 var accept_1 = require("./core/accept");
 Object.defineProperty(exports, "chooseFormat", { enumerable: true, get: function () { return accept_1.chooseFormat; } });
 Object.defineProperty(exports, "parseAccept", { enumerable: true, get: function () { return accept_1.parseAccept; } });
@@ -54,8 +55,11 @@ Object.defineProperty(exports, "humanize", { enumerable: true, get: function ()
 Object.defineProperty(exports, "parseSitemap", { enumerable: true, get: function () { return sitemap_1.parseSitemap; } });
 Object.defineProperty(exports, "sitemapEntries", { enumerable: true, get: function () { return sitemap_1.sitemapEntries; } });
 var report_1 = require("./core/report");
+Object.defineProperty(exports, "DEFAULT_HITS_ENDPOINT", { enumerable: true, get: function () { return report_1.DEFAULT_HITS_ENDPOINT; } });
 Object.defineProperty(exports, "reporter", { enumerable: true, get: function () { return report_1.reporter; } });
 Object.defineProperty(exports, "reporterFromEnv", { enumerable: true, get: function () { return report_1.reporterFromEnv; } });
+var version_1 = require("./core/version");
+Object.defineProperty(exports, "PACKAGE_VERSION", { enumerable: true, get: function () { return version_1.PACKAGE_VERSION; } });
 // Proof: who reads, how much, and how agent-ready a site is.
 var bots_1 = require("./proof/bots");
 Object.defineProperty(exports, "ANSWER_BOT_TOKENS", { enumerable: true, get: function () { return bots_1.ANSWER_BOT_TOKENS; } });

package/dist/refine/remote.d.ts

@@ -1,7 +1,8 @@
-export declare const PACKAGE_VERSION = "0.3.0";
+import { PACKAGE_VERSION } from "../core/version";
+export { PACKAGE_VERSION };
 export declare const DEFAULT_REFINE_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/refine";
 export declare const REFINE_MODELS: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini"];
-export declare const USER_AGENT = "agent-ready/0.3.0 (+https://relvehq.com/agent-ready)";
+export declare const USER_AGENT = "agent-ready/0.4.0 (+https://relvehq.com/agent-ready)";
 export type RemoteStatus = "ok" | "unchanged" | "rejected" | "error" | "skipped";
 export interface RemoteItem {
     path: string;

package/dist/refine/remote.js

@@ -52,10 +52,11 @@ exports.savedFingerprint = savedFingerprint;
 exports.refineRemote = refineRemote;
 exports.stopMessage = stopMessage;
 const file_store_1 = require("./file-store");
-exports.PACKAGE_VERSION = "0.3.0";
+const version_1 = require("../core/version");
+Object.defineProperty(exports, "PACKAGE_VERSION", { enumerable: true, get: function () { return version_1.PACKAGE_VERSION; } });
 exports.DEFAULT_REFINE_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/refine";
 exports.REFINE_MODELS = ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini"];
-exports.USER_AGENT = `agent-ready/${exports.PACKAGE_VERSION} (+https://relvehq.com/agent-ready)`;
+exports.USER_AGENT = `agent-ready/${version_1.PACKAGE_VERSION} (+https://relvehq.com/agent-ready)`;
 /** Errors that mean every later call would fail the same way: the run stops. */
 const FATAL = new Set(["openai_auth", "openai_quota", "missing_key"]);
 /** The saved JSON's fingerprint, else one built from a local run's sourceHash, else null. */

package/dist/wp/relve-agent-ready/includes/class-relve-ar-admin.php

@@ -318,6 +318,16 @@ class Relve_AR_Admin {
 						</td>
 					</tr>
 					<?php self::render_refine_fields( $s ); ?>
+					<tr>
+						<th scope="row"><?php esc_html_e( 'Visit stats', 'relve-agent-ready' ); ?></th>
+						<td>
+							<label>
+								<input type="checkbox" name="<?php echo esc_attr( $opt ); ?>[share_stats]" value="1" <?php checked( $s['share_stats'] ); ?> />
+								<?php esc_html_e( 'Share visit stats with Relve', 'relve-agent-ready' ); ?>
+							</label>
+							<p class="description"><?php esc_html_e( 'For each Markdown page or llms.txt an agent reads: the path, how it was asked for, the agent\'s user agent, status, tokens, bytes and time taken. Never the Markdown itself and never the visitor\'s IP address. Off by default.', 'relve-agent-ready' ); ?></p>
+						</td>
+					</tr>
 				</table>
 				<?php submit_button(); ?>
 			</form>

package/dist/wp/relve-agent-ready/includes/class-relve-ar-reporter.php

@@ -0,0 +1,147 @@
+<?php
+/**
+ * Reporter: share agent visits with Relve (changes/agent-ready-telemetry).
+ *
+ * Off unless both "Enabled" and "Share visit stats with Relve" are ticked.
+ * After a Markdown page or llms.txt has been sent, one small JSON report goes
+ * to RELVE_AR_HITS_ENDPOINT:
+ *
+ *   { key: "ar_wp_<12 hex of md5(home_url())>", client: "wordpress/<ver>",
+ *     event: { ts, host, path, via, source, status, tokens, bytes,
+ *              userAgent, durationMs } }
+ *
+ * Never the Markdown, never the visitor's IP. The request is non-blocking
+ * with a 1 second timeout, and where PHP-FPM allows it the agent's response
+ * is finished first, so the agent never waits on Relve.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Visit reports to Relve.
+ */
+class Relve_AR_Reporter {
+
+	const DEFAULT_ENDPOINT = 'https://relvehq.com/api/agent-ready/v1/hits';
+
+	/**
+	 * Endpoint URL: RELVE_AR_HITS_ENDPOINT, filterable (relve_ar_hits_endpoint).
+	 *
+	 * @return string
+	 */
+	public static function endpoint() {
+		$url = defined( 'RELVE_AR_HITS_ENDPOINT' ) ? (string) RELVE_AR_HITS_ENDPOINT : self::DEFAULT_ENDPOINT;
+		return (string) apply_filters( 'relve_ar_hits_endpoint', $url );
+	}
+
+	/**
+	 * Whether this site reports at all.
+	 *
+	 * @param array $settings Settings.
+	 * @return bool
+	 */
+	public static function active( $settings ) {
+		return ! empty( $settings['enabled'] ) && ! empty( $settings['share_stats'] );
+	}
+
+	/**
+	 * The site's dashboard key: stable per home URL, not a secret.
+	 *
+	 * @return string
+	 */
+	public static function site_key() {
+		return 'ar_wp_' . substr( md5( (string) home_url() ), 0, 12 );
+	}
+
+	/**
+	 * One visit, in the package's HitEvent shape.
+	 *
+	 * @param string $path     Requested page path (without ".md"; "via" says how it was asked).
+	 * @param string $via      suffix|query|accept|llms.
+	 * @param string $source   native|stored|llms.
+	 * @param array  $response Relve_AR_Response::build() result.
+	 * @param string $body     The full Markdown (only its size is used).
+	 * @param array  $server   $_SERVER.
+	 * @return array
+	 */
+	public static function event( $path, $via, $source, $response, $body, $server ) {
+		$headers = isset( $response['headers'] ) && is_array( $response['headers'] ) ? $response['headers'] : array();
+		$start   = isset( $server['REQUEST_TIME_FLOAT'] ) ? (float) $server['REQUEST_TIME_FLOAT'] : 0.0;
+		$ua      = isset( $server['HTTP_USER_AGENT'] ) ? substr( (string) $server['HTTP_USER_AGENT'], 0, 512 ) : '';
+		return array(
+			'ts'         => gmdate( 'Y-m-d\TH:i:s\Z' ),
+			'host'       => (string) wp_parse_url( home_url(), PHP_URL_HOST ),
+			'path'       => substr( (string) $path, 0, 2048 ),
+			'via'        => (string) $via,
+			'source'     => (string) $source,
+			'status'     => isset( $response['status'] ) ? (int) $response['status'] : 200,
+			'tokens'     => isset( $headers['x-markdown-tokens'] ) ? (int) $headers['x-markdown-tokens'] : Relve_AR_Response::estimate_tokens( (string) $body ),
+			'bytes'      => strlen( (string) $body ),
+			'userAgent'  => $ua,
+			'durationMs' => $start > 0 ? max( 0, (int) round( ( microtime( true ) - $start ) * 1000 ) ) : null,
+		);
+	}
+
+	/**
+	 * wp_remote_post() arguments for one event.
+	 *
+	 * @param array $event Event.
+	 * @return array
+	 */
+	public static function request_args( $event ) {
+		$version = defined( 'RELVE_AR_VERSION' ) ? RELVE_AR_VERSION : '0';
+		$body    = json_encode( // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- flags wp_json_encode does not add.
+			array(
+				'key'    => self::site_key(),
+				'client' => 'wordpress/' . $version,
+				'event'  => $event,
+			),
+			JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE
+		);
+		$ua = 'relve-agent-ready-wp/' . $version;
+		return array(
+			'method'      => 'POST',
+			'timeout'     => 1,
+			'blocking'    => false,
+			'redirection' => 0,
+			'user-agent'  => $ua,
+			'headers'     => array(
+				'Content-Type' => 'application/json',
+				'User-Agent'   => $ua,
+			),
+			'body'        => (string) $body,
+			'data_format' => 'body',
+		);
+	}
+
+	/**
+	 * Report one served response. Call after Relve_AR_Response::send(); never
+	 * throws.
+	 *
+	 * @param array  $settings Settings.
+	 * @param string $path     Requested path.
+	 * @param string $via      How the Markdown was asked for.
+	 * @param string $source   Where it came from.
+	 * @param array  $response Relve_AR_Response::build() result.
+	 * @param string $body     The full Markdown.
+	 * @return void
+	 */
+	public static function report( $settings, $path, $via, $source, $response, $body ) {
+		if ( ! self::active( $settings ) ) {
+			return;
+		}
+		try {
+			$event = self::event( $path, $via, $source, $response, $body, $_SERVER );
+			if ( function_exists( 'fastcgi_finish_request' ) ) {
+				fastcgi_finish_request(); // The agent has its answer; report after.
+			}
+			wp_remote_post( self::endpoint(), self::request_args( $event ) );
+		} catch ( Throwable $e ) {
+			// A Relve outage must never touch the site.
+		}
+	}
+}

package/dist/wp/relve-agent-ready/includes/class-relve-ar-router.php

@@ -144,7 +144,7 @@ class Relve_AR_Router {
 		}
 
 		if ( $d['llms'] ) {
-			self::serve_llms( $settings, $method );
+			self::serve_llms( $settings, $method, (string) $d['path'] );
 			exit;
 		}
 
@@ -236,18 +236,18 @@ class Relve_AR_Router {
 		}
 
 		self::no_page_cache();
-		Relve_AR_Response::send(
-			Relve_AR_Response::build(
-				$body,
-				array(
-					'method'        => $method,
-					'if_none_match' => $inm,
-					'canonical'     => $target['canonical'],
-					'cache_control' => Relve_AR_Response::cache_control_for( $d['via'] ),
-					'source'        => $source,
-				)
+		$response = Relve_AR_Response::build(
+			$body,
+			array(
+				'method'        => $method,
+				'if_none_match' => $inm,
+				'canonical'     => $target['canonical'],
+				'cache_control' => Relve_AR_Response::cache_control_for( $d['via'] ),
+				'source'        => $source,
 			)
 		);
+		Relve_AR_Response::send( $response );
+		Relve_AR_Reporter::report( $settings, $d['path'], $d['via'], $source, $response, $body );
 		exit;
 	}
 
@@ -348,26 +348,27 @@ class Relve_AR_Router {
 	 *
 	 * @param array  $settings Settings.
 	 * @param string $method   GET or HEAD.
+	 * @param string $path     Requested path, for the visit report.
 	 * @return void
 	 */
-	private static function serve_llms( $settings, $method ) {
+	private static function serve_llms( $settings, $method, $path = '/llms.txt' ) {
 		$inm  = isset( $_SERVER['HTTP_IF_NONE_MATCH'] ) ? wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] ) : null; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- compared only.
 		$body = Relve_AR_Llms::generate( $settings );
 		self::no_page_cache();
-		Relve_AR_Response::send(
-			Relve_AR_Response::build(
-				$body,
-				array(
-					'method'        => $method,
-					'if_none_match' => $inm,
-					'canonical'     => null, // llms.txt is meant to be found and read.
-					'noindex'       => false,
-					'content_type'  => Relve_AR_Response::TEXT_CONTENT_TYPE,
-					'cache_control' => Relve_AR_Response::cache_control_for( 'llms' ),
-					'source'        => 'llms',
-				)
+		$response = Relve_AR_Response::build(
+			$body,
+			array(
+				'method'        => $method,
+				'if_none_match' => $inm,
+				'canonical'     => null, // llms.txt is meant to be found and read.
+				'noindex'       => false,
+				'content_type'  => Relve_AR_Response::TEXT_CONTENT_TYPE,
+				'cache_control' => Relve_AR_Response::cache_control_for( 'llms' ),
+				'source'        => 'llms',
 			)
 		);
+		Relve_AR_Response::send( $response );
+		Relve_AR_Reporter::report( $settings, $path, 'llms', 'llms', $response, $body );
 	}
 
 	// ── caches ────────────────────────────────────────────────────────────

package/dist/wp/relve-agent-ready/includes/class-relve-ar-settings.php

@@ -10,6 +10,9 @@
  *                             shown in full; sent only to the Relve refine endpoint)
  *   refine_model    string    gpt-4o (default), gpt-4.1, gpt-4.1-mini, gpt-4o-mini
  *   refine_on_save  bool      default true (only acts once a key is saved)
+ *   share_stats     bool      default false: send each agent visit's stats
+ *                             (path, bot, tokens, bytes; never the Markdown or
+ *                             the visitor's IP) to Relve (Relve_AR_Reporter)
  *
  * The settings form never posts `openai_key`; it posts `openai_key_new` (a
  * replacement, empty = keep) and `openai_key_remove`. A submission without
@@ -55,6 +58,7 @@ class Relve_AR_Settings {
 			'openai_key'     => '',
 			'refine_model'   => self::DEFAULT_MODEL,
 			'refine_on_save' => true,
+			'share_stats'    => false,
 		);
 	}
 
@@ -103,6 +107,7 @@ class Relve_AR_Settings {
 		$s['openai_key']     = is_string( $s['openai_key'] ) ? $s['openai_key'] : '';
 		$s['refine_model']   = in_array( $s['refine_model'], self::MODELS, true ) ? $s['refine_model'] : self::DEFAULT_MODEL;
 		$s['refine_on_save'] = (bool) $s['refine_on_save'];
+		$s['share_stats']    = (bool) $s['share_stats'];
 		return $s;
 	}
 
@@ -199,6 +204,7 @@ class Relve_AR_Settings {
 		$model               = isset( $input['refine_model'] ) ? (string) $input['refine_model'] : self::DEFAULT_MODEL;
 		$out['refine_model'] = in_array( $model, self::MODELS, true ) ? $model : self::DEFAULT_MODEL;
 		$out['refine_on_save'] = ! empty( $input['refine_on_save'] );
+		$out['share_stats']    = ! empty( $input['share_stats'] );
 		return $out;
 	}
 }

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

@@ -4,7 +4,7 @@ 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
+Stable tag: 0.3.0
 License: MIT
 License URI: https://opensource.org/licenses/MIT
 
@@ -75,7 +75,11 @@ The description in the front matter uses your Yoast meta description when there
 
 = 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.
+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. Relve keeps a usage record of each rewrite (the permalink, the model, the outcome and size counts of the result such as bytes, words, tokens and headings), not the content or the Markdown. Remove the key at any time with "Remove the saved key"; deleting the plugin deletes it too.
+
+= What does "Share visit stats with Relve" send? =
+
+Nothing unless you tick it (and "Enabled"). Then, after each Markdown page or llms.txt is sent to an agent, one small request goes to `https://relvehq.com/api/agent-ready/v1/hits` with: a site key derived from your home URL, the plugin version, the time, your host, the page path, how the Markdown was asked for (`.md`, `?format=md`, Accept or llms.txt), where it came from (built, stored or llms), the status, tokens, bytes, the agent's user agent and the time taken. Never the Markdown and never the visitor's IP address. It is sent without waiting for an answer and never delays or changes the agent's response. Override the endpoint with the `RELVE_AR_HITS_ENDPOINT` constant or the `relve_ar_hits_endpoint` filter.
 
 = What does rewriting cost? =
 
@@ -99,6 +103,9 @@ Deactivating flushes rewrite rules, removes the WP Rocket rules and cancels sche
 
 == Changelog ==
 
+= 0.3.0 =
+* New, off by default: "Share visit stats with Relve". For each Markdown page or llms.txt an agent reads, the plugin sends Relve the path, how it was asked for, the agent's user agent, status, tokens, bytes and time taken, after the agent has its answer. Never the Markdown, never the visitor's IP.
+
 = 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.
 

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

@@ -3,7 +3,7 @@
  * 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
+ * Version:           0.3.0
  * Requires at least: 6.0
  * Requires PHP:      7.4
  * Author:            Relve
@@ -19,7 +19,7 @@ if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
-define( 'RELVE_AR_VERSION', '0.2.1' );
+define( 'RELVE_AR_VERSION', '0.3.0' );
 define( 'RELVE_AR_FILE', __FILE__ );
 define( 'RELVE_AR_DIR', plugin_dir_path( __FILE__ ) );
 
@@ -39,6 +39,7 @@ 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';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-reporter.php';
 
 /**
  * Activation: default settings (disabled), the refined-files folder with its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relvehq/agent-ready",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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": [