ARC/1.0 — Agent-Readable Catalog

Specification version ARC/1.0 · Published 2026-06-10 · Status: Stable
Steward: Save The Brain (KaliCart) · License: CC BY 4.0 · Reference implementation: KaliCart Bridge ≥ 1.0.76 for WooCommerce

Abstract. ARC defines how an e-commerce storefront exposes its catalog as a machine-readable, read-only REST surface that autonomous AI agents can discover, trust and consume without scraping, authentication or vendor lock-in. It specifies three discovery signals, a self-describing discovery document, a catalog endpoint contract, a normative product object, an explicit consent model for federated indexing, and interoperability with UCP (/.well-known/ucp). ARC is platform-neutral; this document uses WooCommerce examples throughout.

Contents

Conformance levels & terminology
Discovery signals
The discovery document
Catalog endpoints
The product object
Consent & crawl policy
Checkout sessions (optional)
UCP interoperability
Security considerations
Specification changelog

1. Conformance levels & terminology

The key words must, must not, should and may are to be interpreted as described in RFC 2119.

Level	Name	Requirements
ARC-READ	Readable catalog	At least one discovery signal (§2), a valid discovery document (§3), and the `search`, `products`, `product` and `categories` endpoints (§4) serving product objects (§5). No authentication on any of these surfaces.
ARC-TRUST	Trustworthy catalog	ARC-READ, plus: quality quarantine (§5.6), explicit consent flags (§6), freshness metadata, honest stock confidence (§5.4), and the price/total verification rules of §5.3.
ARC-CHECKOUT	Checkout handoff	ARC-TRUST, plus checkout sessions (§7). Payment must remain on the merchant storefront; ARC surfaces never process payments.

2. Discovery signals

A conforming storefront must publish at least one — and should publish all — of the following signals, each resolving to the discovery document:

2.1 HTML head link

<link rel="kalicart-agent" type="application/json"
      href="https://shop.example.com/wp-json/kalicart/v1/discovery" />

The rel="kalicart-agent" relation in the storefront <head> is the primary in-band signal. Agents parsing storefront HTML should check the head before reconstructing a catalog from page content. Implementations may additionally render a visible body anchor (badge) pointing to a human/agent-readable index; field testing shows body anchors materially improve discovery by DOM-browsing agents.

2.2 Well-known paths

The storefront should serve /.well-known/agent.json, /.well-known/agent-catalog and an implementation-named alias (reference: /.well-known/kalicart-bridge), each containing at minimum the discovery document URL and the implementation version.

2.3 Crawl surfaces

The storefront may advertise the discovery URL in robots.txt (as a comment/allow entry) and expose an agent-oriented sitemap enumerating the catalog endpoints.

3. The discovery document

A single self-describing JSON document. It is the contract: an agent that has read it needs no out-of-band documentation. Normative fields:

Field	Req.	Meaning
`document_kind`	MUST	Fixed string identifying the document family (reference: `kalicart_agent_discovery`).
`schema_version`	MUST	Version of the document schema.
`plugin_version`	MUST	Implementation version (semver).
`endpoints{}`	MUST	Absolute URLs for `discovery`, `search`, `products`, `product` (templated `{id}`), `categories`, `meta`.
`authentication`	MUST	`{required:false, scheme:"none"}` for all public catalog surfaces.
`capabilities{}`	MUST	Honest boolean map: `search`, `offers`, `availability`, `shipping_policy`, `coupon_hints`, `cart`, `checkout`, `payments`, `mutations`, `read_only`. Capabilities not implemented must be `false`.
`crawler_policy{}` / `intent_flags{}`	MUST (L2)	Consent model — see §6.
`price_format`	MUST	Price encoding declaration — see §5.3.
`variation_discovery`	MUST	Declares the list-vs-detail variants contract — see §5.5.
`freshness`	SHOULD (L2)	Whether data is live or a snapshot, and its staleness bound.
`trust{}`	SHOULD	`safe_for[]` / `not_for[]` task lists, checkout authority, coupon price rule.
`ucp_profile_url`	SHOULD	Absolute URL of `/.well-known/ucp` — see §8.
`merchant{}`, `return_policy`, `merchant_shipping_policy`	SHOULD	Boundary truths exposed as structured data, never as prose advice.

Design rule — boundary truth. Anything the merchant is authoritative for (price, availability, shipping at checkout, return policy) must be exposed as structured data with an explicit authority note, and must not be replaced by computed or advisory values.

4. Catalog endpoints

All endpoints are read-only GET, unauthenticated, JSON. Reference base: /wp-json/kalicart/v1/.

Endpoint	Contract
`catalog/search`	Filters: `q`, `category`, `gender`, `color`, `on_sale`, `in_stock`, `min_price`, `max_price`. Accepted filters must be enumerated by `catalog/meta`.
`catalog/products`	Paginated list. Response must include `products[]`, `total`, `page`, `per_page`, `total_pages`.
`catalog/product/{id}`	Single product with full `variants[]` (see §5.5).
`catalog/categories`	Category tree with per-node product counts. Categories are the merchant's own taxonomy; ARC does not impose a global taxonomy.
`catalog/meta`	Accepted filters and the catalog price range.

5. The product object

5.1 Identity

id, sku, type (simple|variable), name, slug, url, status, categories[] (each with a full path such as "Wine > Prosecco"), tags[], barcodes[] (EAN/GTIN/UPC when present — additive, empty when absent).

5.2 Provenance

metadata.bridge_version (implementation version that emitted the object) and updated_at/created_at must be present.

5.3 Price

Catalog prices are encoded as decimal_major_units (e.g. 29.99 = 29.99 EUR) and the encoding must be declared in price_format. price.current is always the merchant catalog price; coupons are conditional checkout savings and must not replace it. list_price carries the strikethrough list price for UCP interop. Agents must not quote totals that the merchant checkout has not computed (total verification rule).

5.4 Stock

stock.availability_status uses UCP standard values (in_stock, out_of_stock, backorder). stock.confidence declares precision honestly: numeric_stock_quantity, availability_status_only, or variant_dependent. If quantity is null the agent must not invent numeric inventory.

5.5 Variants

variants[] is always an array, never null. In list and search responses: a single entry for simple products, an empty array for variable products — full variants come from catalog/product/{id}. This asymmetry must be declared in variation_discovery.list_context_note. Agents must not quote a final price for a variable product until a variation is selected.

5.6 Quality quarantine ARC-TRUST

Each product carries quarantine: {in_quarantine, score, flags[]}. The score starts at 100 with deductions for missing title, description, category, price, image, SKU. Products quarantined for structural defects (title/description/category/price) must be excluded from any downstream index built on the catalog. The merchant retains a private health dashboard; the public surface only exposes the verdict.

5.7 Purchase readiness

purchase_readiness: {status, blocking_fields[], can_add_to_cart_directly} tells the agent whether a direct checkout_url add-to-cart is possible or which attributes must be selected first.

ARC separates reading a single store (always allowed on public surfaces) from federated indexing (aggregating the catalog into a cross-merchant index). Consent for the latter is published by the merchant in the discovery document — the robots.txt model: the signal lives with the data, and the indexer is bound to honor it.

"crawler_policy": {
  "allow_llm_training":    false,
  "allow_live_agent_reads": true,
  "allow_global_indexing":  true
},
"intent_flags": {
  "single_merchant_only":    true,
  "global_indexable":        true,
  "federated_search_source": true,
  "agent_read_surface":      true
}

A federated indexer must read these flags at probe time, must not ingest a catalog whose allow_global_indexing is false, and must identify itself with an honest User-Agent. The reference implementation ships consent enabled by default with a one-click opt-out in the merchant admin; either default is conforming, but the toggle must exist and the published flags must reflect it within the freshness bound.

7. Checkout sessions (optional) ARC-CHECKOUT

POST checkout/session creates a cart session for one or more products and returns cart_url / checkout_url. The human completes payment on the merchant storefront. ARC surfaces must not capture payments, store payment credentials, or require OAuth for this handoff. The capability is off by default and its state must be visible in capabilities.checkout_sessions.

8. UCP interoperability

A conforming implementation should serve /.well-known/ucp declaring catalog.search and catalog.lookup, and link it via ucp_profile_url. ARC's availability_status, list_price and variants[] contracts are aligned with UCP so that one catalog serves both ecosystems without translation.

9. Security considerations

All public surfaces are read-only; capabilities.mutations must be false. No API keys on public surfaces — secrets in agent contexts leak. Federated probes must apply SSRF guards (no IP literals, no internal hostnames, bounded redirects/timeouts) and an identifying User-Agent. Admin/health surfaces must require platform capability checks. Implementations must not call third-party services from the merchant's server as a side effect of serving catalog reads.

10. Specification changelog

Version	Date	Notes
`ARC/1.0`	2026-06-10	Initial stable release. Codifies the contract shipped by KaliCart Bridge 1.0.76: three discovery signals, discovery document, five catalog endpoints, product object with quarantine and purchase readiness, opt-out consent model for federated indexing, optional checkout sessions, UCP interop.

Feedback and implementation reports: GitHub issues.