Agent-ready storefront: llms.txt support and feed-grade structured data completeness

[fballiano]

Overview

Make the storefront legible to AI agents by default: ship llms.txt support and audit Maho_StructuredData for feed-grade completeness, alongside #916 (markdown content negotiation).

AI answers and shopping agents consume machine-readable signals, not rendered HTML: ~65% of pages cited by ChatGPT carry structured data, and llms.txt is the emerging convention for telling agents where the machine-friendly content lives. Together with #916 this is mostly finishing work already started — StructuredData and ContentNegotiation exist; this issue closes the gaps and makes "agent-ready out of the box" a checkable claim.

Design Philosophy

• One catalog, three projections — structured data on the page, markdown via content negotiation (Maho_ContentNegotiation: serve markdown to AI agents via Accept header / .md suffix #916), and feeds (Maho_FeedManager) must all agree, since agents cross-check them.
• Defaults over configuration — a stock Maho install should pass agent-readiness checks with zero setup; store-level toggles exist to opt out, not opt in.

---

MVP Scope

llms.txt

• Auto-generated /llms.txt per store view: store name/description, links to key machine-readable surfaces (category/product markdown routes from Maho_ContentNegotiation: serve markdown to AI agents via Accept header / .md suffix #916, sitemap, feeds), localized per store
• Admin-editable extra content block for merchant-specific guidance

Structured data audit (Maho_StructuredData)

• Audit JSON-LD output against what AI surfaces actually consume — feed-grade Product completeness: price + priceValidUntil, availability, condition, GTIN/MPN/brand, AggregateRating/Review, images, shipping details (OfferShippingDetails) and returns (MerchantReturnPolicy) where data exists
• Fill identified gaps; validate output against schema.org current release and Google Rich Results requirements
• Cover the non-catalog surfaces too: Organization/WebSite (sitelinks search box), BreadcrumbList, blog posts (already present — verify completeness)

Verification

• CI/test coverage asserting required structured-data fields render for the sample-data catalog, so regressions are caught

---

Future (not in MVP)

• Admin "agent readiness" report per store: llms.txt status, structured-data completeness per product, content-negotiation health
• Structured-data completeness surfaced in the product grid (ties into feed field requirements)

Related

• Maho_ContentNegotiation: serve markdown to AI agents via Accept header / .md suffix #916 (Maho_ContentNegotiation) — this issue is its companion; Optimize Maho for agents #911 (optimize Maho for agents)
• Store-data MCP server (MCP server: expose the API Platform resource surface as MCP tools #1124) and AI-channel feeds (Feed Manager: AI-channel product feeds (ChatGPT, Perplexity) and AI traffic attribution #1125): discovery (feeds) + legibility (this issue) + interaction (MCP) form the agentic-commerce track