diff --git a/docs/templates-json-schema.md b/docs/templates-json-schema.md
new file mode 100644
index 0000000..fe39fb3
--- /dev/null
+++ b/docs/templates-json-schema.md
@@ -0,0 +1,30 @@
+# `templates.json` schema (CPA)
+
+Parity with [cna-templates `templates.json`](https://github.com/Create-Node-App/cna-templates).
+
+```json
+{
+  "templates": [
+    {
+      "slug": "fastapi-starter",
+      "name": "FastAPI Starter",
+      "category": "backend",
+      "url": "https://github.com/Create-Python-App/cpa-templates?subdir=templates/fastapi-starter",
+      "description": "Minimal FastAPI app with uv"
+    }
+  ],
+  "addons": [
+    {
+      "slug": "ruff-setup",
+      "name": "Ruff",
+      "category": "tooling",
+      "url": "https://github.com/Create-Python-App/cpa-templates?subdir=extensions/ruff-setup"
+    }
+  ]
+}
+```
+
+## Differences from Node
+
+- URLs point at Python templates (pyproject/uv/ruff) instead of package.json/npm
+- Compatibility metadata should list Python ranges instead of Node engines