> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Surface contract (C8)

> Canonical names, URL resolution, ownership, and naming rules for Better Data surfaces — product, OSS, and web.

# Surface contract (C8)

This page is the **system-wide validation reference** for surfaces: one canonical **name**, one **URL strategy** (or resolver), and one **primary owner** per row. Product, OSS, and web must match.

<Note>
  **MCP deployment roles** (gateway-console vs Registry MCP vs hosted gateway MCP): [MCP surfaces](/reference/mcp-surfaces). **Developer demo URLs** resolve via `resolveDeveloperDemoUrls` in `@repo/analytics/taxonomy` (same paths everywhere when env overrides are unset).
</Note>

## Canonical surfaces

| Surface                             | Canonical name                                                       | URL / resolution                                                                                                               | Primary owner       |
| ----------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| Operator UI for self-hosted gateway | **Gateway Console**                                                  | App: `apps/gateway-console` (deployed host per env)                                                                            | Platform — Gateway  |
| Hosted commerce MCP shell           | **Hosted Gateway MCP**                                               | `apps/hosted-gateway-mcp`                                                                                                      | Platform — Gateway  |
| LLM commerce protocol & package     | **Commerce Gateway**                                                 | OSS/docs: [commercegateway.io](https://commercegateway.io); integration: [Commerce Gateway](/integrations/commerce-gateway)    | DX + Gateway OSS    |
| Discovery protocol & OSS server     | **Registry MCP**                                                     | Package `@commercegateway/registry-mcp`; deployed **registry-mcp-server**; system ref: [MCP surfaces](/reference/mcp-surfaces) | DX + Registry OSS   |
| In-product listing & workspace      | **Commerce Registry**                                                | SCM routes under `/commerce/registry`; public discovery: `registry.betterdata.co`                                              | Platform — Registry |
| Governed automation                 | **Loop Engine**                                                      | [Loops](/platform/loops), [loopengine.io](https://loopengine.io)                                                               | Platform — Loops    |
| Reference implementations           | **Gateway Demo** · **Commerce Demo** · **Agent Starter** (docs/code) | `resolveDeveloperDemoUrls` + `BUILD_AGENT_DOC_PATH` in `@repo/analytics/taxonomy`                                              | DX — Reference      |
| Product shell                       | **Better Data**                                                      | [app](https://app.betterdata.co) / marketing [betterdata.co](https://www.betterdata.co)                                        | Product             |

## Naming rules (must not conflate)

* **Registry MCP** is the **discovery protocol / MCP tools** (`@shop` resolution, etc.). It is **not** the Commerce Registry product card.
* **Commerce Registry** is the **workspace and product surface** for listing, verification, and discovery configuration — native to the platform, not a separate external signup product.
* **Gateway Console** is the **operator dashboard** (config, keys, status). It is **not** the Commerce Gateway protocol runtime.
* **Commerce Gateway** is the **protocol and packages** that expose commerce tools to LLMs — not the console UI.

## Commerce Agent (composition, not a surface row)

**Commerce Agent** is **not** an additional row in this table and **not** a product SKU. It is the **canonical composition pattern**: discover (**Registry MCP**) → execute (**Commerce Gateway**) → govern (**Loop Engine**) → **recorded outcome**; **Gateway Demo** / **Commerce Demo** are optional **experience** layers (reference only). See **[Commerce Agent pattern (C9)](/reference/commerce-agent-pattern)** — the only definition; do not introduce “agent” as a standalone product.

## Demos

* **Gateway Demo** and **Commerce Demo** are **reference layer** experiences — **not** product modules, not control planes, not multiple competing URLs. URLs resolve through **`resolveDeveloperDemoUrls`** (optional env overrides; otherwise docs fallbacks from `DEVELOPER_DEMO_DOCS_PATHS` in `@repo/analytics/taxonomy`).

## Setup flows

* Gateway and registry **setup happen in-product** after workspace connection. Protocol and Remote MCP endpoints are **configuration**, not a separate external product signup. See messaging on [MCP surfaces](/reference/mcp-surfaces).

## System diagram (single canonical story)

* **Canonical layered messaging** (Infrastructure → Protocol → Reference → Control → Platform): [Core Concepts — Layered ecosystem](/getting-started/concepts#layered-ecosystem-model-canonical) and the same model in `@repo/analytics/taxonomy` (`LAYERED_ECOSYSTEM_MODEL`).
* **Four product layers** and **operational signal chain** (tags → loops → gateway → SCM/DCM): [Platform architecture](/getting-started/platform-architecture) — **complementary** illustration, not a competing “flat product stack.”
* **LLM ↔ gateway ↔ backends** (narrow): mermaid under [Architecture Overview](/getting-started/concepts#architecture-overview) in Core Concepts — **gateway plumbing**, not the full platform diagram.

## Where to go next

* [Commerce Agent pattern (C9)](/reference/commerce-agent-pattern)
* [MCP surfaces](/reference/mcp-surfaces)
* [MCP Tool Reference](/integrations/mcp-reference)
* [Platform architecture](/getting-started/platform-architecture)
* [Core Concepts](/getting-started/concepts)