@relvehq/agent-ready 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,543 @@
+<?php
+/**
+ * Store: refined Markdown files from Relve.
+ *
+ * Upload contract (agreed with the Relve runner, `venture.ts --zip`): the zip
+ * holds a top-level `md/` folder; inside it, `<url-path>.md` relative to the
+ * site root exactly as the npm refine writes them ("/" -> md/index.md,
+ * "/blog/my-post/" -> md/blog/my-post.md). `.json` sidecars and other files
+ * are skipped, not errors. Entries outside `md/`, absolute paths, `..` and
+ * oversized files are rejected.
+ *
+ * Files live in wp-content/uploads/relve-agent-ready/md/, behind an
+ * .htaccess "deny all" and index.php files. They are only ever read and sent
+ * as text, never included or executed.
+ *
+ * The validation and lookup helpers are pure and unit-tested; the class takes
+ * its base directory in the constructor so tests use a temp dir.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Refined-files store.
+ */
+class Relve_AR_Store {
+
+	/** Max zip size in bytes. */
+	const MAX_ZIP_BYTES = 20971520; // 20 MB.
+
+	/** Max size of one Markdown file in bytes. */
+	const MAX_FILE_BYTES = 2097152; // 2 MB.
+
+	/** Max total uncompressed bytes written from one zip. */
+	const MAX_TOTAL_BYTES = 104857600; // 100 MB.
+
+	/** Max entries read from one zip. */
+	const MAX_ENTRIES = 20000;
+
+	/** Root folder: .../uploads/relve-agent-ready. @var string */
+	private $root;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param string|null $root Root folder; default uploads/relve-agent-ready.
+	 */
+	public function __construct( $root = null ) {
+		if ( null === $root ) {
+			$uploads = wp_upload_dir( null, false );
+			$root    = trailingslashit( $uploads['basedir'] ) . 'relve-agent-ready';
+		}
+		$this->root = rtrim( str_replace( '\\', '/', (string) $root ), '/' );
+	}
+
+	/**
+	 * Root folder.
+	 *
+	 * @return string
+	 */
+	public function root() {
+		return $this->root;
+	}
+
+	/**
+	 * Folder the .md files live in.
+	 *
+	 * @return string
+	 */
+	public function md_dir() {
+		return $this->root . '/md';
+	}
+
+	// ── validation (pure) ─────────────────────────────────────────────────
+
+	/**
+	 * Classify one zip entry name.
+	 *
+	 * @param string $name Entry name as stored in the zip.
+	 * @return array { status: store|skip|reject, path: relative path under md/ (store only), reason: string }
+	 */
+	public static function validate_entry( $name ) {
+		$name = (string) $name;
+		$skip = function ( $reason ) {
+			return array(
+				'status' => 'skip',
+				'path'   => '',
+				'reason' => $reason,
+			);
+		};
+		$reject = function ( $reason ) {
+			return array(
+				'status' => 'reject',
+				'path'   => '',
+				'reason' => $reason,
+			);
+		};
+		if ( '' === $name || false !== strpos( $name, "\0" ) || preg_match( '/[\x00-\x1F\x7F]/', $name ) ) {
+			return $reject( 'bad name' );
+		}
+		if ( false !== strpos( $name, '\\' ) ) {
+			return $reject( 'backslash in path' );
+		}
+		if ( '/' === $name[0] || preg_match( '#^[A-Za-z]:#', $name ) ) {
+			return $reject( 'absolute path' );
+		}
+		$segments = explode( '/', $name );
+		foreach ( $segments as $seg ) {
+			if ( '..' === $seg || '.' === $seg ) {
+				return $reject( 'path traversal' );
+			}
+		}
+		if ( '/' === substr( $name, -1 ) ) {
+			return $skip( 'folder' );
+		}
+		if ( 'md' !== $segments[0] || count( $segments ) < 2 ) {
+			return $reject( 'outside md/' );
+		}
+		$rel = implode( '/', array_slice( $segments, 1 ) );
+		if ( strtolower( substr( $rel, -3 ) ) !== '.md' ) {
+			return $skip( 'not a .md file' );
+		}
+		foreach ( array_slice( $segments, 1 ) as $seg ) {
+			if ( '' === $seg ) {
+				return $reject( 'empty path segment' );
+			}
+			if ( '.' === $seg[0] ) {
+				return $reject( 'hidden file' );
+			}
+			if ( preg_match( '#[<>:"|?*]#', $seg ) ) {
+				return $reject( 'bad character' );
+			}
+		}
+		if ( strlen( $rel ) > 1024 ) {
+			return $reject( 'path too long' );
+		}
+		return array(
+			'status' => 'store',
+			'path'   => $rel,
+			'reason' => '',
+		);
+	}
+
+	/**
+	 * Relative file names to try for a request path, most specific first:
+	 * the full path, then the path relative to the home path.
+	 *
+	 * @param string $path      Normalised request path ("/blog/my-post", "/").
+	 * @param string $home_path Home path without trailing slash ("" or "/blog").
+	 * @return string[] e.g. array( 'blog/my-post.md', 'my-post.md' ).
+	 */
+	public static function candidates( $path, $home_path = '' ) {
+		$norm = Relve_AR_Negotiation::normalize_path( $path );
+		if ( null === $norm ) {
+			return array();
+		}
+		$list = array( self::file_for( $norm ) );
+		if ( '' !== $home_path && ( $norm === $home_path || 0 === strpos( $norm, $home_path . '/' ) ) ) {
+			$rel    = substr( $norm, strlen( $home_path ) );
+			$list[] = self::file_for( '' === $rel ? '/' : $rel );
+		}
+		return array_values( array_unique( $list ) );
+	}
+
+	/**
+	 * "/" -> "index.md", "/a/b" -> "a/b.md".
+	 *
+	 * @param string $norm Normalised path.
+	 * @return string
+	 */
+	private static function file_for( $norm ) {
+		$clean = trim( $norm, '/' );
+		return ( '' === $clean ? 'index' : $clean ) . '.md';
+	}
+
+	// ── reading ───────────────────────────────────────────────────────────
+
+	/**
+	 * Stored Markdown for a request path, or null.
+	 *
+	 * @param string $path      Normalised request path.
+	 * @param string $home_path Home path.
+	 * @return string|null
+	 */
+	public function get( $path, $home_path = '' ) {
+		foreach ( self::candidates( $path, $home_path ) as $rel ) {
+			$file = $this->md_dir() . '/' . $rel;
+			if ( ! $this->inside( $file ) || ! is_file( $file ) || ! is_readable( $file ) ) {
+				continue;
+			}
+			$size = filesize( $file );
+			if ( false === $size || $size > self::MAX_FILE_BYTES ) {
+				continue;
+			}
+			$text = file_get_contents( $file ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- local file.
+			if ( false !== $text && '' !== trim( $text ) ) {
+				return $text;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Is $file inside the md folder (after resolving symlinks)?
+	 *
+	 * @param string $file File path.
+	 * @return bool
+	 */
+	private function inside( $file ) {
+		$real_dir = realpath( $this->md_dir() );
+		$real     = realpath( $file );
+		if ( false === $real_dir || false === $real ) {
+			return false;
+		}
+		$real_dir = rtrim( str_replace( '\\', '/', $real_dir ), '/' ) . '/';
+		return 0 === strpos( str_replace( '\\', '/', $real ), $real_dir );
+	}
+
+	/**
+	 * Number of stored .md files.
+	 *
+	 * @return int
+	 */
+	public function count() {
+		$dir = $this->md_dir();
+		if ( ! is_dir( $dir ) ) {
+			return 0;
+		}
+		$n  = 0;
+		$it = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ) );
+		foreach ( $it as $f ) {
+			if ( $f->isFile() && strtolower( substr( $f->getFilename(), -3 ) ) === '.md' ) {
+				++$n;
+			}
+		}
+		return $n;
+	}
+
+	// ── writing ───────────────────────────────────────────────────────────
+
+	/**
+	 * Create the folders and the protection files.
+	 *
+	 * @return bool
+	 */
+	public function ensure() {
+		foreach ( array( $this->root, $this->md_dir() ) as $dir ) {
+			if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
+				return false;
+			}
+			if ( ! file_exists( $dir . '/index.php' ) ) {
+				file_put_contents( $dir . '/index.php', "<?php\n// Silence is golden.\n" ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+			}
+		}
+		$htaccess = $this->root . '/.htaccess';
+		if ( ! file_exists( $htaccess ) ) {
+			$rules = "# Relve Agent Ready: refined files are served by WordPress, never directly.\n"
+				. "<IfModule mod_authz_core.c>\n\tRequire all denied\n</IfModule>\n"
+				. "<IfModule !mod_authz_core.c>\n\tOrder deny,allow\n\tDeny from all\n</IfModule>\n";
+			file_put_contents( $htaccess, $rules ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+		}
+		return true;
+	}
+
+	/**
+	 * Write one validated file.
+	 *
+	 * @param string $rel     Relative path from validate_entry().
+	 * @param string $content Markdown.
+	 * @return bool
+	 */
+	public function put( $rel, $content ) {
+		$check = self::validate_entry( 'md/' . $rel );
+		if ( 'store' !== $check['status'] || strlen( $content ) > self::MAX_FILE_BYTES ) {
+			return false;
+		}
+		$file = $this->md_dir() . '/' . $check['path'];
+		$dir  = dirname( $file );
+		if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
+			return false;
+		}
+		if ( ! $this->inside( $dir ) && realpath( $dir ) !== realpath( $this->md_dir() ) ) {
+			return false;
+		}
+		return false !== file_put_contents( $file, $content ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+	}
+
+	/**
+	 * Delete every stored file (keeps the folder and its protection files).
+	 *
+	 * @return void
+	 */
+	public function clear() {
+		self::rmdir_r( $this->md_dir() );
+		$this->ensure();
+	}
+
+	/**
+	 * Delete the whole root folder (uninstall).
+	 *
+	 * @return void
+	 */
+	public function delete_all() {
+		self::rmdir_r( $this->root );
+	}
+
+	/**
+	 * Import a zip: replaces the stored files with the zip's md/ files.
+	 *
+	 * @param string $zip_file Path of the uploaded zip.
+	 * @return array { ok: bool, error: string, stored: int, skipped: int, rejected: int, reasons: string[] }
+	 */
+	public function import_zip( $zip_file ) {
+		$result = array(
+			'ok'       => false,
+			'error'    => '',
+			'stored'   => 0,
+			'skipped'  => 0,
+			'rejected' => 0,
+			'reasons'  => array(),
+		);
+		$size = is_file( $zip_file ) ? filesize( $zip_file ) : false;
+		if ( false === $size || 0 === $size ) {
+			$result['error'] = 'The upload is empty or missing.';
+			return $result;
+		}
+		if ( $size > self::MAX_ZIP_BYTES ) {
+			$result['error'] = 'The zip is larger than 20 MB.';
+			return $result;
+		}
+		$files = class_exists( 'ZipArchive' ) ? $this->read_zip_archive( $zip_file, $result ) : $this->read_zip_fallback( $zip_file, $result );
+		if ( null === $files ) {
+			return $result;
+		}
+		if ( ! $files ) {
+			$result['error'] = 'No .md files under md/ were found in the zip. Existing files were kept.';
+			return $result;
+		}
+		// Replace the set: a refined run is always complete.
+		$this->clear();
+		foreach ( $files as $rel => $content ) {
+			if ( $this->put( $rel, $content ) ) {
+				++$result['stored'];
+			} else {
+				++$result['rejected'];
+				$result['reasons'][] = $rel . ': could not be written';
+			}
+		}
+		$result['ok'] = $result['stored'] > 0;
+		if ( ! $result['ok'] ) {
+			$result['error'] = 'No file could be written. Check that wp-content/uploads is writable.';
+		}
+		return $result;
+	}
+
+	/**
+	 * Count one classified entry; return the content to keep or null.
+	 *
+	 * @param array  $check   From validate_entry().
+	 * @param string $name    Entry name.
+	 * @param int    $size    Uncompressed size.
+	 * @param array  $result  Result (counts updated).
+	 * @param int    $total   Running total of accepted bytes.
+	 * @return bool Whether to read the entry.
+	 */
+	private static function accept_entry( $check, $name, $size, &$result, &$total ) {
+		if ( 'skip' === $check['status'] ) {
+			if ( 'folder' !== $check['reason'] ) {
+				++$result['skipped'];
+			}
+			return false;
+		}
+		if ( 'reject' === $check['status'] ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': ' . $check['reason'];
+			return false;
+		}
+		if ( $size > self::MAX_FILE_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': larger than 2 MB';
+			return false;
+		}
+		if ( $total + $size > self::MAX_TOTAL_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': over the 100 MB total';
+			return false;
+		}
+		$total += $size;
+		return true;
+	}
+
+	/**
+	 * Check one entry's content: size and valid UTF-8.
+	 *
+	 * @param string|false $content Content.
+	 * @param string       $name    Entry name.
+	 * @param array        $result  Result.
+	 * @return bool
+	 */
+	private static function content_ok( $content, $name, &$result ) {
+		if ( false === $content || strlen( $content ) > self::MAX_FILE_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': unreadable or too large';
+			return false;
+		}
+		if ( ! preg_match( '//u', $content ) ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': not UTF-8 text';
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Read entries with ZipArchive.
+	 *
+	 * @param string $zip_file Zip.
+	 * @param array  $result   Result.
+	 * @return array|null rel => content, or null on a fatal error.
+	 */
+	private function read_zip_archive( $zip_file, &$result ) {
+		$zip = new ZipArchive();
+		if ( true !== $zip->open( $zip_file ) ) {
+			$result['error'] = 'The file is not a valid zip.';
+			return null;
+		}
+		$files = array();
+		$total = 0;
+		$count = min( $zip->numFiles, self::MAX_ENTRIES );
+		for ( $i = 0; $i < $count; $i++ ) {
+			$stat = $zip->statIndex( $i );
+			if ( ! $stat ) {
+				continue;
+			}
+			$name  = $stat['name'];
+			$check = self::validate_entry( $name );
+			if ( ! self::accept_entry( $check, $name, (int) $stat['size'], $result, $total ) ) {
+				continue;
+			}
+			$content = $zip->getFromIndex( $i, self::MAX_FILE_BYTES + 1 );
+			if ( self::content_ok( $content, $name, $result ) ) {
+				$files[ $check['path'] ] = $content;
+			}
+		}
+		if ( $zip->numFiles > self::MAX_ENTRIES ) {
+			$result['reasons'][] = 'Only the first ' . self::MAX_ENTRIES . ' entries were read.';
+		}
+		$zip->close();
+		return $files;
+	}
+
+	/**
+	 * Read entries with WordPress's unzip_file() (PclZip) when ZipArchive is
+	 * missing: extract to a temp folder, then validate every extracted path
+	 * exactly as zip entry names.
+	 *
+	 * @param string $zip_file Zip.
+	 * @param array  $result   Result.
+	 * @return array|null
+	 */
+	private function read_zip_fallback( $zip_file, &$result ) {
+		if ( ! function_exists( 'unzip_file' ) || ! function_exists( 'WP_Filesystem' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+		if ( ! WP_Filesystem() ) {
+			$result['error'] = 'Could not access the file system to unzip.';
+			return null;
+		}
+		$tmp = $this->root . '/tmp-' . wp_generate_password( 12, false );
+		if ( ! self::mkdir_p( $tmp ) ) {
+			$result['error'] = 'Could not create a temporary folder.';
+			return null;
+		}
+		$unzipped = unzip_file( $zip_file, $tmp );
+		if ( is_wp_error( $unzipped ) ) {
+			self::rmdir_r( $tmp );
+			$result['error'] = 'The file is not a valid zip.';
+			return null;
+		}
+		$files = array();
+		$total = 0;
+		$seen  = 0;
+		$it    = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $tmp, FilesystemIterator::SKIP_DOTS ) );
+		foreach ( $it as $f ) {
+			if ( ! $f->isFile() || ++$seen > self::MAX_ENTRIES ) {
+				continue;
+			}
+			$name  = ltrim( str_replace( '\\', '/', substr( $f->getPathname(), strlen( $tmp ) ) ), '/' );
+			$check = self::validate_entry( $name );
+			if ( ! self::accept_entry( $check, $name, (int) $f->getSize(), $result, $total ) ) {
+				continue;
+			}
+			$content = file_get_contents( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+			if ( self::content_ok( $content, $name, $result ) ) {
+				$files[ $check['path'] ] = $content;
+			}
+		}
+		self::rmdir_r( $tmp );
+		return $files;
+	}
+
+	// ── filesystem helpers ────────────────────────────────────────────────
+
+	/**
+	 * Recursive mkdir.
+	 *
+	 * @param string $dir Folder.
+	 * @return bool
+	 */
+	private static function mkdir_p( $dir ) {
+		if ( function_exists( 'wp_mkdir_p' ) ) {
+			return wp_mkdir_p( $dir );
+		}
+		return is_dir( $dir ) || mkdir( $dir, 0755, true ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir
+	}
+
+	/**
+	 * Recursive delete. Does not follow symlinks.
+	 *
+	 * @param string $dir Folder.
+	 * @return void
+	 */
+	private static function rmdir_r( $dir ) {
+		if ( ! is_dir( $dir ) || is_link( $dir ) ) {
+			return;
+		}
+		$it = new RecursiveIteratorIterator(
+			new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ),
+			RecursiveIteratorIterator::CHILD_FIRST
+		);
+		foreach ( $it as $f ) {
+			if ( $f->isDir() && ! $f->isLink() ) {
+				rmdir( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
+			} else {
+				unlink( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
+			}
+		}
+		rmdir( $dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
+	}
+}

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

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

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

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

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

@@ -0,0 +1,75 @@
+=== 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.

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

@@ -0,0 +1,70 @@
+<?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();
+}