diff --git a/README.md b/README.md
index d2c56cd..dd3de08 100644
--- a/README.md
+++ b/README.md
@@ -25,3 +25,8 @@ One repository may expose several small `cmd/` entry points while sharing domain
 - on-demand analytics worker that calculates dashboard sections in parallel and caches versioned results in Redis
 
 The exact package layout is deferred until the Go architecture and DI decisions are approved.
+
+## Merchant API contract
+
+- [`docs/API-SPEC.md`](docs/API-SPEC.md) defines the reviewable MVP capability, security boundaries, SSE recovery, detail pagination, and CSV-export policy.
+- [`docs/openapi.yaml`](docs/openapi.yaml) is the draft OpenAPI 3.1 interface source of truth and will generate frontend types after approval.