# Riviera

Riviera is infrastructure that gives independent pizza restaurants their
own AI-ordering storefront. It lets an AI assistant look up a restaurant's
menu, check delivery eligibility, get a deterministic price quote, and
submit a pizza order on a customer's behalf.

Riviera is not a food delivery marketplace and does not do multi-restaurant
search or ranking. This endpoint is a shared demo surface covering multiple
demo restaurants for testing; the target model is one AI-ordering
storefront per merchant, typically at `https://<merchant>.riviera.app` or a
merchant-owned domain (see this repository's
`docs/engineering/merchant-agent-storefronts.md` for the full design).
Individual merchant storefronts are already available at `/restaurants/:slug/mcp`
and the other `/restaurants/:slug/{agent,openapi.json,llms.txt,.well-known/agent-commerce.json}` paths.

## Machine-readable interfaces

- OpenAPI spec: /openapi.json
- Agent-commerce manifest: /.well-known/agent-commerce.json
- Remote MCP endpoint: /mcp (Streamable HTTP, stateless, customer-agent
  tools only)

A local stdio MCP server is also available for Claude Desktop and Claude
Code — see docs/engineering/mcp-server.md. Both transports expose the same
seven customer-agent tools. Merchant accept/reject remains human-facing and
token-gated; it is never exposed through MCP, over either transport.

## Demo restaurants

Two restaurants are available for testing: `tonys-pizza` and
`riviera-pizza`. Use their slugs in the API paths, e.g.
`/api/agent/restaurants/tonys-pizza/menu`. `tonys-pizza` requires
authorization-first payment (see below); `riviera-pizza` is pay-on-delivery
only.

## Rules for agents

- Never invent menu items, prices, delivery areas, or availability — always
  read them from the API.
- Always call the quote endpoint and show the customer the final total
  before submitting an order.
- Order submission requires explicit customer confirmation
  (`customer_confirmation: true`). Never submit an order without it.
- A submitted order is not confirmed until the restaurant explicitly
  accepts it — check order status rather than assuming acceptance.
- Merchant actions (view/accept/reject) are token-gated. These endpoints
  are for the restaurant, not for customer-facing agents. Never exposed
  through MCP or through any payment-related response.
- Payment: some restaurants (e.g. `tonys-pizza`) require authorization-first
  payment via Stripe Checkout. When `submit_order` returns
  `payment_required: true`, call `create_payment_authorization` with the
  order id to get a secure, customer-safe `authorization_url` — give this
  URL to the customer to open themselves and never collect or ask for card
  details directly. The order is not sent to the restaurant until the
  customer authorizes payment there. Other restaurants remain
  pay-on-delivery or pay-on-collection only.