From 6e382abc2388477304920b31286b2fe167c41636 Mon Sep 17 00:00:00 2001
From: ulises-jeremias <ulisescf.24@gmail.com>
Date: Fri, 17 Jul 2026 01:42:49 -0300
Subject: [PATCH] docs: document cpa-templates layered CI uvx/PyPI contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Template-bank CI must scaffold with uvx from PyPI only — no source
fallback to this monorepo. Tracked in Create-Python-App/cpa-templates#46.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/CPA_TEMPLATES_TRACKING.md | 14 ++++++++++++++
 docs/TROUBLESHOOTING.md        |  9 +++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/CPA_TEMPLATES_TRACKING.md b/docs/CPA_TEMPLATES_TRACKING.md
index 652d5c3..9285345 100644
--- a/docs/CPA_TEMPLATES_TRACKING.md
+++ b/docs/CPA_TEMPLATES_TRACKING.md
@@ -11,6 +11,7 @@ Previously tracked by
 - [x] `fastapi-starter` template + initial extensions
 - [x] Wire catalog URL in CLI (`CPA_CATALOG_URL`, default raw GitHub URL)
 - [x] Integration tests against `cpa-templates` checkout
+- [x] Layered CI on `cpa-templates` (L0–L3) — always scaffold via `uvx` from PyPI ([cpa-templates#46](https://github.com/Create-Python-App/cpa-templates/issues/46))
 - [ ] Website (optional, later)
 
 ## Repositories
@@ -20,6 +21,18 @@ Previously tracked by
 | CLI monorepo | [create-python-app](https://github.com/Create-Python-App/create-python-app) |
 | Template bank | [cpa-templates](https://github.com/Create-Python-App/cpa-templates) |
 
+## CI contract (`cpa-templates`)
+
+Template-bank CI **must** invoke the CLI as published on PyPI:
+
+```sh
+uvx create-awesome-python-app@latest …
+```
+
+It must **not** check out this monorepo or fall back to `uv run` against a local source tree. That way green Actions means the same binary users install works with the templates under test.
+
+CLI CI in this repo stays focused on unit/lint/type/smoke-distribution (`uvx` / Docker / brew / AUR).
+
 ## CNA parity reference
 
 | CNA | CPA |
@@ -28,3 +41,4 @@ Previously tracked by
 | `cna-templates` | `cpa-templates` |
 | `cna.config.json` | `cpa.config.json` |
 | `~/.cache/cna` | `~/.cache/cpa` |
+| Layered L0–L3 CI | Layered L0–L3 CI (`uvx` / PyPI) |
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 4056d77..1932a06 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -365,3 +365,12 @@ uvx create-awesome-python-app@latest --version
 If behavior differs between `uvx` and a global install, compare versions and
 clear the uv tool cache. See [DISTRIBUTION_SETUP.md](./DISTRIBUTION_SETUP.md) for
 maintainer release workflow.
+
+### `cpa-templates` CI contract
+
+The template bank CI scaffolds exclusively with `uvx create-awesome-python-app@latest`
+(PyPI). It does not check out this monorepo as a scaffolding fallback. If template
+CI fails after a CLI release, fix/publish the CLI — do not teach template CI to
+`uv run` against source. See
+[cpa-templates#46](https://github.com/Create-Python-App/cpa-templates/issues/46)
+and [CPA_TEMPLATES_TRACKING.md](./CPA_TEMPLATES_TRACKING.md).