Commit 4bbb398f0a4 for woocommerce

commit 4bbb398f0a4bc73cc8b4ad5e3f33e2629b3968f1
Author: Bero <1199991+bgrgicak@users.noreply.github.com>
Date:   Tue Nov 17 15:45:55 2026 +0100

    Add llms.txt store guidance for AI agents (#70741)

    * Add llms.txt store guidance for AI agents

    * Add changelog entry for llms.txt store guidance

    * Fix llms.txt fallback and readiness checks

    * Add focused llms.txt integration tests

    * Respect 404 template providers for llms.txt

    * Cache llms.txt store guidance

    * Omit Store API guidance when its root route is missing

    * Detect physical llms.txt when fallback is disabled

    * Use WordPress whitespace normalization for llms.txt

    * Rename llms.txt test variable

    * Remove 404 template handling from llms.txt fallback

    * Fix llms.txt requests for encoded site paths

    * Include UCP guidance with plain permalinks

diff --git a/plugins/woocommerce/.wp-env.e2e.json b/plugins/woocommerce/.wp-env.e2e.json
index a2051ed3855..7865d4ec7b2 100644
--- a/plugins/woocommerce/.wp-env.e2e.json
+++ b/plugins/woocommerce/.wp-env.e2e.json
@@ -33,6 +33,7 @@
 	},
 	"mappings": {
 		"wp-content/plugins/e2e-test-bin": "./tests/e2e/bin",
+		"wp-content/plugins/llms-txt-provider": "./tests/e2e/test-plugins/llms-txt-provider",
 		"wp-content/plugins/settings-ui-component-registration": "./tests/e2e/test-plugins/settings-ui-component-registration",
 		"test-data/images/": "./tests/e2e/test-data/images/",
 		"wp-content/themes/emptytheme": "./tests/e2e/themes/blocks/emptytheme",
diff --git a/plugins/woocommerce/changelog/add-llms-txt-store-guidance b/plugins/woocommerce/changelog/add-llms-txt-store-guidance
new file mode 100644
index 00000000000..caf8875100d
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-llms-txt-store-guidance
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Provide a store guide for AI agents when no other llms.txt file is available.
diff --git a/plugins/woocommerce/includes/class-woocommerce.php b/plugins/woocommerce/includes/class-woocommerce.php
index c903c8d44f5..e91f2206534 100644
--- a/plugins/woocommerce/includes/class-woocommerce.php
+++ b/plugins/woocommerce/includes/class-woocommerce.php
@@ -461,6 +461,7 @@ final class WooCommerce {
 		$container->get( Automattic\WooCommerce\Internal\ScheduledSalePriceReconciler::class )->register();
 		$container->get( Automattic\WooCommerce\Internal\OrderWithdrawal\OrderWithdrawalController::class )->register();
 		$container->get( Automattic\WooCommerce\Internal\Ucp\UcpDiscovery::class )->register();
+		$container->get( Automattic\WooCommerce\Internal\LlmsTxt\LlmsTxt::class )->register();
 		$container->get( Automattic\WooCommerce\Internal\AgentReadiness\ScheduledScan::class )->register();
 		$container->get( Automattic\WooCommerce\Internal\AgentReadiness\ReadinessRestController::class )->register();
 		$container->get( Automattic\WooCommerce\Internal\AgentReadiness\AgenticCommerceSettings::class )->register();
diff --git a/plugins/woocommerce/src/Internal/LlmsTxt/LlmsTxt.php b/plugins/woocommerce/src/Internal/LlmsTxt/LlmsTxt.php
new file mode 100644
index 00000000000..3bd7d8f599b
--- /dev/null
+++ b/plugins/woocommerce/src/Internal/LlmsTxt/LlmsTxt.php
@@ -0,0 +1,355 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\Internal\LlmsTxt;
+
+use Automattic\WooCommerce\Internal\RegisterHooksInterface;
+use Automattic\WooCommerce\Internal\ComingSoon\ComingSoonHelper;
+use Automattic\WooCommerce\Internal\Ucp\UcpDiscovery;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils as UcpUtils;
+
+/**
+ * Provides store guidance when no other provider serves llms.txt.
+ *
+ * @since 11.4.0
+ */
+final class LlmsTxt implements RegisterHooksInterface {
+
+	/**
+	 * The template selected before other template filters run.
+	 *
+	 * @var string|null
+	 */
+	private $original_template;
+
+	/**
+	 * Register the fallback after other providers have handled the request.
+	 *
+	 * @since 11.4.0
+	 */
+	public function register(): void {
+		add_filter( 'redirect_canonical', array( $this, 'filter_canonical_redirect' ) );
+		add_filter( 'exit_on_http_head', array( $this, 'filter_exit_on_http_head' ) );
+		add_filter( 'template_include', array( $this, 'remember_template' ), PHP_INT_MIN );
+		add_filter( 'template_include', array( $this, 'maybe_render' ), PHP_INT_MAX );
+	}
+
+	/**
+	 * Keep WordPress from redirecting the missing file to a trailing-slash URL.
+	 *
+	 * @internal
+	 *
+	 * @param string|false $redirect_url Canonical redirect URL.
+	 * @return string|false
+	 */
+	public function filter_canonical_redirect( $redirect_url ) {
+		return $this->should_render() ? false : $redirect_url;
+	}
+
+	/**
+	 * Let HEAD requests reach template selection for the fallback.
+	 *
+	 * @internal
+	 * @param bool $should_exit Whether WordPress should exit early.
+	 * @return bool
+	 */
+	public function filter_exit_on_http_head( $should_exit ) {
+		return $this->should_render() ? false : $should_exit;
+	}
+
+	/**
+	 * Report local file checks for llms.txt after init.
+	 *
+	 * Status is physical_file, disabled, or unknown. A physical file takes precedence when the fallback is disabled.
+	 * Check the public URL to determine which provider actually responds.
+	 *
+	 * @since 11.4.0
+	 *
+	 * @return array{status:string,section:string}
+	 */
+	public function get_status(): array {
+		if ( ! $this->is_enabled() ) {
+			return array(
+				'status'  => true === $this->has_physical_file() ? 'physical_file' : 'disabled',
+				'section' => '',
+			);
+		}
+
+		$status            = 'unknown';
+		$has_physical_file = $this->has_physical_file();
+		if ( true === $has_physical_file ) {
+			$status = 'physical_file';
+		}
+
+		return array(
+			'status'  => $status,
+			'section' => $this->get_guidance(),
+		);
+	}
+
+	/**
+	 * Remember the template selected before other filters run.
+	 *
+	 * @internal
+	 * @param string $template Selected template.
+	 * @return string
+	 */
+	public function remember_template( $template ) {
+		$this->original_template = $template;
+		return $template;
+	}
+
+	/**
+	 * Serve an unclaimed request after other providers have had a chance to respond.
+	 *
+	 * @internal
+	 * @param string $template Selected template.
+	 * @return string
+	 */
+	public function maybe_render( $template ) {
+		if ( '' === $template || $template !== $this->original_template || ! $this->should_render() ) {
+			return $template;
+		}
+
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput
+		$method = $_SERVER['REQUEST_METHOD'] ?? '';
+		if ( ! in_array( $method, array( 'GET', 'HEAD' ), true ) ) {
+			if ( ! headers_sent() ) {
+				header( 'Allow: GET, HEAD' );
+			}
+			status_header( 405 );
+			exit;
+		}
+
+		status_header( 200 );
+		if ( ! headers_sent() ) {
+			header( 'Content-Type: text/plain; charset=utf-8' );
+			header( 'Cache-Control: no-cache, must-revalidate' );
+			header( 'X-WooCommerce-LLMs-Txt: 1' );
+			if ( ! get_option( 'blog_public' ) ) {
+				header( 'X-Robots-Tag: noindex, nofollow', false );
+			}
+		}
+		if ( 'GET' === $method ) {
+			echo $this->get_content(); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Plain-text Markdown, not HTML.
+		}
+		exit;
+	}
+
+	/**
+	 * Check whether WooCommerce may serve this request as a fallback.
+	 */
+	private function should_render(): bool {
+		return $this->is_llms_request()
+			&& $this->is_enabled()
+			&& ! wc_get_container()->get( ComingSoonHelper::class )->is_store_coming_soon()
+			&& $this->is_unclaimed_request()
+			&& true !== $this->has_physical_file()
+			&& ! $this->has_route();
+	}
+
+	/**
+	 * Check the request path against this site's llms.txt URL.
+	 */
+	private function is_llms_request(): bool {
+		if ( ! isset( $_SERVER['REQUEST_URI'] ) ) {
+			return false;
+		}
+
+		$request_path = wp_parse_url( sanitize_url( wp_unslash( $_SERVER['REQUEST_URI'] ) ), PHP_URL_PATH );
+		return wp_parse_url( home_url( '/llms.txt' ), PHP_URL_PATH ) === $request_path;
+	}
+
+	/**
+	 * Plain permalinks or a stale rewrite rule can resolve the path as the front page.
+	 */
+	private function is_unclaimed_request(): bool {
+		global $wp;
+
+		return is_404() || ( isset( $wp ) && is_front_page() && empty( $wp->query_vars ) );
+	}
+
+	/**
+	 * Check custom rewrites and existing content without treating catch-all permalinks as routes.
+	 */
+	private function has_route(): bool {
+		global $wp_rewrite;
+
+		if ( isset( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) {
+			$rules = $wp_rewrite->extra_rules_top + $wp_rewrite->extra_rules + $wp_rewrite->non_wp_rules;
+			foreach ( array_keys( $rules ) as $rule ) {
+				if ( preg_match( '#^' . $rule . '#', 'llms.txt' ) ) {
+					return true;
+				}
+			}
+		}
+
+		return 0 !== url_to_postid( home_url( '/llms.txt' ) );
+	}
+
+	/**
+	 * Whether WooCommerce may provide guidance and a fallback response.
+	 */
+	private function is_enabled(): bool {
+		/**
+		 * Controls WooCommerce's llms.txt guidance and fallback response.
+		 *
+		 * @since 11.4.0
+		 *
+		 * @param bool $enabled Whether the feature is enabled.
+		 */
+		return (bool) apply_filters( 'woocommerce_enable_llms_txt', true );
+	}
+
+	/**
+	 * Check the site root for a physical file without changing it.
+	 *
+	 * @return bool|null Null when the site root cannot be determined reliably.
+	 */
+	private function has_physical_file(): ?bool {
+		if ( is_multisite() && trim( (string) wp_parse_url( home_url(), PHP_URL_PATH ), '/' ) !== '' ) {
+			return null;
+		}
+		if ( untrailingslashit( home_url() ) !== untrailingslashit( site_url() ) ) {
+			return null;
+		}
+		if ( ! function_exists( 'get_home_path' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+
+		return is_file( trailingslashit( get_home_path() ) . 'llms.txt' );
+	}
+
+	/**
+	 * Build the complete fallback document.
+	 */
+	private function get_content(): string {
+		$name    = $this->plain_text( get_bloginfo( 'name' ) );
+		$tagline = $this->plain_text( get_bloginfo( 'description' ) );
+		$content = '# ' . ( '' !== $name ? $name : home_url() ) . "\n\n";
+
+		if ( '' !== $tagline ) {
+			$content .= '> ' . $tagline . "\n\n";
+		}
+
+		return $content . $this->get_guidance( ! is_user_logged_in() );
+	}
+
+	/**
+	 * Build the guidance used by the fallback and readiness check.
+	 *
+	 * @param bool $use_cache Whether to reuse guidance for an anonymous request.
+	 */
+	private function get_guidance( bool $use_cache = false ): string {
+		$cache_key = 'wc_llms_txt_guidance_' . md5( get_locale() . '|' . home_url() );
+		$guidance  = $use_cache ? get_transient( $cache_key ) : false;
+
+		if ( ! is_array( $guidance ) || ! isset( $guidance['section'], $guidance['profile'] ) || ! is_string( $guidance['section'] ) || ! is_array( $guidance['profile'] ) ) {
+			$guidance = $this->build_guidance();
+			if ( $use_cache ) {
+				set_transient( $cache_key, $guidance, 5 * MINUTE_IN_SECONDS );
+			}
+		}
+
+		/**
+		 * Filters the Markdown guidance in WooCommerce's llms.txt.
+		 *
+		 * @since 11.4.0
+		 *
+		 * @param string $section The Markdown guidance.
+		 * @param array  $profile The UCP profile, or an empty array when unavailable.
+		 */
+		$section = apply_filters( 'woocommerce_llms_txt_agentic_section', $guidance['section'], $guidance['profile'] );
+		return is_string( $section ) ? $section : '';
+	}
+
+	/**
+	 * Build the guidance and UCP profile.
+	 *
+	 * @return array{section:string,profile:array}
+	 */
+	private function build_guidance(): array {
+		$profile      = array();
+		$capabilities = array();
+
+		if ( UcpUtils::is_enabled() ) {
+			$profile      = wc_get_container()->get( UcpDiscovery::class )->get_profile();
+			$capabilities = array_keys( $profile['ucp']['capabilities'] ?? array() );
+			$labels       = array(
+				'dev.ucp.shopping.catalog.search' => 'search products',
+				'dev.ucp.shopping.catalog.lookup' => 'look up products',
+				'dev.ucp.shopping.cart'           => 'build a cart',
+			);
+			$capabilities = array_map(
+				static function ( $capability ) use ( $labels ) {
+					return $labels[ $capability ] ?? $capability;
+				},
+				$capabilities
+			);
+		}
+
+		$routes      = rest_get_server()->get_routes();
+		$policies    = array(
+			'terms'   => (int) get_option( 'woocommerce_terms_page_id' ),
+			'returns' => (int) get_option( 'woocommerce_refund_returns_page_id' ),
+			'privacy' => (int) get_option( 'wp_page_for_privacy_policy' ),
+		);
+		$policy_urls = array();
+		foreach ( $policies as $key => $page_id ) {
+			if ( $page_id <= 0 ) {
+				continue;
+			}
+			$page = get_post( $page_id );
+			if ( $page instanceof \WP_Post && 'page' === $page->post_type && 'publish' === $page->post_status && is_post_publicly_viewable( $page ) && ! $page->post_password ) {
+				$policy_urls[ $key ] = get_permalink( $page );
+			}
+		}
+
+		$lines                  = array( '## Agentic capabilities', '' );
+		$store_api_capabilities = array();
+		if ( isset( $routes['/wc/store/v1/products'] ) ) {
+			$store_api_capabilities[] = 'browse products';
+		}
+		if ( isset( $routes['/wc/store/v1/cart'] ) ) {
+			$store_api_capabilities[] = 'use the cart';
+		}
+		if ( $store_api_capabilities && isset( $routes['/wc/store/v1'] ) ) {
+			$lines[] = '- [WooCommerce Store API](' . esc_url_raw( rest_url( 'wc/store/v1' ) ) . '): ' . ucfirst( implode( ' and ', $store_api_capabilities ) ) . '. See the [Store API documentation](https://developer.woocommerce.com/docs/apis/store-api/).';
+		}
+		if ( $profile ) {
+			$version       = $this->plain_text( $profile['ucp']['version'] ?? '' );
+			$checkout_note = isset( $profile['ucp']['capabilities']['dev.ucp.shopping.checkout'] ) ? '' : ' Checkout is completed on the store, not through UCP.';
+			$lines[]       = '- [Universal Commerce Protocol (UCP) profile](' . esc_url_raw( home_url( '/.well-known/ucp' ) ) . '): ' . implode( ', ', $capabilities ) . '. Version ' . $version . '.' . $checkout_note;
+		}
+		if ( isset( $routes['/mcp/mcp-adapter-default-server'] ) ) {
+			$lines[] = '- [Merchant MCP](' . esc_url_raw( rest_url( 'mcp/mcp-adapter-default-server' ) ) . '): For authorized store management; authentication is required.';
+		}
+		if ( $policy_urls ) {
+			$policy_labels = array(
+				'terms'   => 'Terms and conditions',
+				'returns' => 'Refund and returns',
+				'privacy' => 'Privacy policy',
+			);
+			$lines[]       = '';
+			$lines[]       = '## Policies';
+			$lines[]       = '';
+			foreach ( $policy_urls as $key => $url ) {
+				$lines[] = '- [' . $policy_labels[ $key ] . '](' . esc_url_raw( $url ) . ')';
+			}
+		}
+		return array(
+			'section' => implode( "\n", $lines ) . "\n",
+			'profile' => $profile,
+		);
+	}
+
+	/**
+	 * Make site text safe to include on one Markdown line.
+	 *
+	 * @param string $text Site text.
+	 */
+	private function plain_text( string $text ): string {
+		$text = str_replace( array( "\f", "\v" ), ' ', html_entity_decode( $text, ENT_QUOTES, 'UTF-8' ) );
+		return wp_strip_all_tags( $text, true );
+	}
+}
diff --git a/plugins/woocommerce/tests/e2e/playwright.config.ts b/plugins/woocommerce/tests/e2e/playwright.config.ts
index 9a1a79d488f..af39bb403a3 100644
--- a/plugins/woocommerce/tests/e2e/playwright.config.ts
+++ b/plugins/woocommerce/tests/e2e/playwright.config.ts
@@ -121,6 +121,8 @@ const serialRunSpecs = [
 	// Activates a test plugin with WP-CLI, which races other workers on the
 	// `active_plugins` option.
 	'**/tests/checkout/checkout-shortcode-custom-place-order-button.spec.ts',
+	// Changes site visibility and the active plugins while checking llms.txt.
+	'**/tests/llms-txt/*.spec.ts',
 	// Mutate the global onboarding profile/options, site-visibility options and
 	// the active theme.
 	'**/tests/onboarding/**/*.spec.ts',
diff --git a/plugins/woocommerce/tests/e2e/test-plugins/llms-txt-provider/llms-txt-provider.php b/plugins/woocommerce/tests/e2e/test-plugins/llms-txt-provider/llms-txt-provider.php
new file mode 100644
index 00000000000..abd34635019
--- /dev/null
+++ b/plugins/woocommerce/tests/e2e/test-plugins/llms-txt-provider/llms-txt-provider.php
@@ -0,0 +1,24 @@
+<?php
+/**
+ * Plugin Name: E2E llms.txt provider
+ * Description: Provides a template-based llms.txt for integration tests.
+ *
+ * @package WooCommerce\Tests
+ */
+
+declare( strict_types = 1 );
+
+if ( did_action( 'template_redirect' ) ) {
+	status_header( 200 );
+	header( 'Content-Type: text/plain; charset=utf-8' );
+	echo "# Existing llms.txt provider\n";
+	return;
+}
+
+add_filter(
+	'template_include',
+	static function ( $template ) {
+		global $wp;
+		return isset( $wp ) && 'llms.txt' === $wp->request ? __FILE__ : $template;
+	}
+);
diff --git a/plugins/woocommerce/tests/e2e/tests/llms-txt/llms-txt.spec.ts b/plugins/woocommerce/tests/e2e/tests/llms-txt/llms-txt.spec.ts
new file mode 100644
index 00000000000..043c6c6e569
--- /dev/null
+++ b/plugins/woocommerce/tests/e2e/tests/llms-txt/llms-txt.spec.ts
@@ -0,0 +1,95 @@
+/**
+ * Internal dependencies
+ */
+import { expect, test } from '../../fixtures/fixtures';
+import { wpCLI } from '../../utils/cli';
+
+const provider = 'llms-txt-provider/llms-txt-provider.php';
+const fileContent = '# Existing physical llms.txt provider\n';
+
+test.describe( 'llms.txt', () => {
+	test( 'serves the fallback and leaves a physical file untouched', async ( {
+		request,
+	} ) => {
+		const response = await request.get( '/llms.txt' );
+		expect( response.status() ).toBe( 200 );
+		expect( response.headers()[ 'content-type' ] ).toContain(
+			'text/plain'
+		);
+		expect( await response.text() ).toContain( 'WooCommerce Store API' );
+
+		const head = await request.head( '/llms.txt' );
+		expect( head.status() ).toBe( 200 );
+		expect( await head.text() ).toBe( '' );
+		const post = await request.post( '/llms.txt' );
+		expect( post.status() ).toBe( 405 );
+		expect( post.headers().allow ).toBe( 'GET, HEAD' );
+
+		await wpCLI( [
+			'wp',
+			'eval',
+			`$file = ABSPATH . 'llms.txt'; if ( file_exists( $file ) ) { WP_CLI::error( 'llms.txt already exists' ); } file_put_contents( $file, ${ JSON.stringify( fileContent ) } );`,
+		] );
+		try {
+			const existing = await request.get( '/llms.txt' );
+			expect( existing.status() ).toBe( 200 );
+			expect( await existing.text() ).toBe( fileContent );
+		} finally {
+			await wpCLI( [
+				'wp',
+				'eval',
+				`$file = ABSPATH . 'llms.txt'; if ( file_exists( $file ) && file_get_contents( $file ) === ${ JSON.stringify( fileContent ) } ) { unlink( $file ); }`,
+			] );
+		}
+	} );
+
+	test( 'lets a template-based provider handle the request', async ( {
+		request,
+	} ) => {
+		await wpCLI( [ 'wp', 'plugin', 'activate', provider ] );
+		try {
+			const response = await request.get( '/llms.txt' );
+			expect( response.status() ).toBe( 200 );
+			expect( await response.text() ).toBe(
+				'# Existing llms.txt provider\n'
+			);
+		} finally {
+			await wpCLI( [ 'wp', 'plugin', 'deactivate', provider ] );
+		}
+	} );
+
+	test( 'respects site-wide coming-soon mode', async ( { request } ) => {
+		const { stdout } = await wpCLI( [
+			'wp',
+			'eval',
+			"echo wp_json_encode( array( get_option( 'woocommerce_coming_soon', null ), get_option( 'woocommerce_store_pages_only', null ) ) );",
+		] );
+		const original = Buffer.from( stdout.trim() ).toString( 'base64' );
+		try {
+			await wpCLI( [
+				'wp',
+				'option',
+				'update',
+				'woocommerce_coming_soon',
+				'yes',
+			] );
+			await wpCLI( [
+				'wp',
+				'option',
+				'update',
+				'woocommerce_store_pages_only',
+				'no',
+			] );
+			const response = await request.get( '/llms.txt' );
+			const body = await response.text();
+			expect( body ).toContain( 'woocommerce-coming-soon' );
+			expect( body ).not.toContain( '## Agentic capabilities' );
+		} finally {
+			await wpCLI( [
+				'wp',
+				'eval',
+				`$options = json_decode( base64_decode( '${ original }' ), true ); foreach ( array( 'woocommerce_coming_soon', 'woocommerce_store_pages_only' ) as $i => $name ) { null === $options[$i] ? delete_option( $name ) : update_option( $name, $options[$i] ); }`,
+			] );
+		}
+	} );
+} );
diff --git a/plugins/woocommerce/tests/php/src/Internal/LlmsTxt/LlmsTxtTest.php b/plugins/woocommerce/tests/php/src/Internal/LlmsTxt/LlmsTxtTest.php
new file mode 100644
index 00000000000..ea0f16c2d79
--- /dev/null
+++ b/plugins/woocommerce/tests/php/src/Internal/LlmsTxt/LlmsTxtTest.php
@@ -0,0 +1,77 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\Tests\Internal\LlmsTxt;
+
+use Automattic\WooCommerce\Internal\LlmsTxt\LlmsTxt;
+
+/**
+ * Tests for the llms.txt readiness check.
+ */
+class LlmsTxtTest extends \WC_Unit_Test_Case {
+	/**
+	 * @testdox Reports unknown and provides guidance when no physical file is present, or disabled when the feature is off.
+	 */
+	public function test_readiness_without_a_physical_file(): void {
+		$file = $this->site_root_file();
+		if ( file_exists( $file ) ) {
+			$this->markTestSkipped( 'The test site already has an llms.txt file.' );
+		}
+
+		$llms_txt = wc_get_container()->get( LlmsTxt::class );
+		$result   = $llms_txt->get_status();
+		$this->assertSame( 'unknown', $result['status'] );
+		$this->assertStringContainsString( 'WooCommerce Store API', $result['section'] );
+
+		add_filter( 'woocommerce_enable_llms_txt', '__return_false' );
+		$this->assertSame(
+			array(
+				'status'  => 'disabled',
+				'section' => '',
+			),
+			$llms_txt->get_status()
+		);
+	}
+
+	/**
+	 * @testdox Detects a physical file without changing its content.
+	 */
+	public function test_readiness_with_a_physical_file(): void {
+		$file   = $this->site_root_file();
+		$handle = @fopen( $file, 'x' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen, WordPress.PHP.NoSilencedErrors.Discouraged -- Never overwrite an existing site file.
+		if ( false === $handle ) {
+			$this->markTestSkipped( 'The test site root is not writable or already has an llms.txt file.' );
+		}
+
+		try {
+			fwrite( $handle, 'Existing provider' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fwrite
+			fclose( $handle ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose
+			clearstatcache( true, $file );
+			$result = wc_get_container()->get( LlmsTxt::class )->get_status();
+			$this->assertSame( 'physical_file', $result['status'] );
+			$this->assertSame( 'Existing provider', file_get_contents( $file ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+
+			add_filter(
+				'site_url',
+				static function ( $url ) {
+					return trailingslashit( $url ) . 'wp';
+				}
+			);
+			$this->assertSame( 'unknown', wc_get_container()->get( LlmsTxt::class )->get_status()['status'] );
+		} finally {
+			unlink( $file ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink -- Remove only the file created by this test.
+		}
+	}
+
+	/**
+	 * Get the physical path checked by the readiness method.
+	 *
+	 * @return string
+	 */
+	private function site_root_file(): string {
+		if ( ! function_exists( 'get_home_path' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+		return trailingslashit( get_home_path() ) . 'llms.txt';
+	}
+}