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.

MCP deployment roles (gateway-console vs Registry MCP vs hosted gateway MCP): MCP surfaces. Developer demo URLs resolve via resolveDeveloperDemoUrls in @repo/analytics/taxonomy (same paths everywhere when env overrides are unset).

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; integration: Commerce Gateway | DX + Gateway OSS | | Discovery protocol & OSS server | Registry MCP | Package @commercegateway/registry-mcp; deployed registry-mcp-server; system ref: 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, 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 / marketing 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) — 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 standalone administration stacks, 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.

System diagram (single canonical story)

Canonical layered messaging (Infrastructure → Protocol → Reference → Control → Platform): Core Concepts — Layered ecosystem 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 — complementary illustration, not a competing “flat product stack.”
LLM ↔ gateway ↔ backends (narrow): mermaid under Architecture Overview in Core Concepts — gateway plumbing, not the full platform diagram.