docs: describe the published catalog API

Author: gekichumai-admin

README.md

@@ -46,10 +46,25 @@ scripts/
 
 ### Packages
 
-- **`packages/dxdata`** — Annotated maimai DX song and sheet metadata as JSON, with TypeScript enums for versions, categories, and difficulty levels. Generated by `scripts/annotator`.
+- **`packages/dxdata`** — The legacy compatibility snapshot and TypeScript
+  helpers. New native clients read the published catalog API; this package
+  remains while existing web and renderer consumers migrate.
 
 - **`packages/tsconfig`** — Shared TypeScript configuration used across all apps and packages.
 
+### Published catalog API
+
+`GET /api/v1/dxdata` returns the complete current catalog and its metadata in
+one schema-versioned, null-free document. The producer stores immutable bodies
+in PostgreSQL and atomically advances the `production-v1` pointer; the API never
+reconstructs the document per request or exposes stored provenance.
+
+The endpoint supports `GET`, metadata-only `HEAD`, strong `ETag` validators,
+and `If-None-Match`. Successful responses are public and use separate browser
+and CDN stale-while-revalidate policies. Errors are `no-store`. The Cloudflare
+Cache Rules workflow manages only the queryless catalog and arcade-catalog
+paths, leaving unrelated zone rules untouched.
+
 ## Tech Stack
 
 | Layer | Technology |