From 81a1f7817490258ffbedb602f8600c1548dbd6b1 Mon Sep 17 00:00:00 2001
From: ulises-jeremias <ulisescf.24@gmail.com>
Date: Fri, 17 Jul 2026 01:42:47 -0300
Subject: [PATCH 1/3] =?UTF-8?q?ci:=20replace=20stacked=20matrix=20with=20l?=
 =?UTF-8?q?ayered=20L0=E2=80=93L3=20trust=20(uvx/PyPI)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirror cna-templates layered CI for cpa-templates (#46):

- L0 registry + profile validation
- L1 every template alone
- L2 one extension × fastapi-starter
- L3 curated profiles under ci/profiles/

Scaffolding always uses `uvx create-awesome-python-app@latest` (never a
create-python-app source checkout). Retire smoke-test.yml and the random/
all-extensions combination workflows.

Also split extension categories (ci/containers/database/editor) and fix
fastapi-typed-starter mypy issues so L1 type-check is honest.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .github/workflows/ci-extensions.yml           |  78 +++++
 .github/workflows/ci-integrity.yml            |  35 ++
 .github/workflows/ci-profiles.yml             |  86 +++++
 .github/workflows/ci-templates.yml            |  65 ++++
 .github/workflows/smoke-test.yml              |  86 -----
 .github/workflows/test-combinations.yml       | 309 ------------------
 .gitignore                                    |   1 +
 README.md                                     |   7 +-
 ci/profiles/fastapi-default.json              |   6 +
 ci/profiles/fastapi-devcontainer.json         |   6 +
 ci/profiles/fastapi-typed-default.json        |   6 +
 docs/MAINTENANCE_CI.md                        | 211 ++++--------
 docs/MAINTENANCE_DEPENDENCIES.md              |   2 +-
 docs/MAINTENANCE_RUNBOOK.md                   |  18 +-
 docs/MAINTENANCE_TEMPLATES.md                 |  16 +-
 docs/TESTING.md                               |  64 ++--
 scripts/ci/generate-matrix.py                 | 216 ++++++++++++
 scripts/ci/registry.py                        | 162 +++++++++
 scripts/ci/run-scaffold-check.py              | 203 ++++++++++++
 scripts/ci/validate-registry.py               |  92 ++++++
 templates.json                                | 119 +++++--
 .../app/core/exception_handlers.py            |   4 +-
 .../tests/test_health.py.template             |   5 +-
 23 files changed, 1163 insertions(+), 634 deletions(-)
 create mode 100644 .github/workflows/ci-extensions.yml
 create mode 100644 .github/workflows/ci-integrity.yml
 create mode 100644 .github/workflows/ci-profiles.yml
 create mode 100644 .github/workflows/ci-templates.yml
 delete mode 100644 .github/workflows/smoke-test.yml
 delete mode 100644 .github/workflows/test-combinations.yml
 create mode 100644 .gitignore
 create mode 100644 ci/profiles/fastapi-default.json
 create mode 100644 ci/profiles/fastapi-devcontainer.json
 create mode 100644 ci/profiles/fastapi-typed-default.json
 create mode 100755 scripts/ci/generate-matrix.py
 create mode 100755 scripts/ci/registry.py
 create mode 100755 scripts/ci/run-scaffold-check.py
 create mode 100755 scripts/ci/validate-registry.py

diff --git a/.github/workflows/ci-extensions.yml b/.github/workflows/ci-extensions.yml
new file mode 100644
index 0000000..872dc3e
--- /dev/null
+++ b/.github/workflows/ci-extensions.yml
@@ -0,0 +1,78 @@
+name: CI Extensions (L2)
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  schedule:
+    - cron: "0 0 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  generate:
+    name: Generate extension matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set.outputs.matrix }}
+      count: ${{ steps.set.outputs.count }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate L2 matrix
+        id: set
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="origin/${BASE_REF}"
+            git fetch origin "${BASE_REF}" --depth=1 || true
+            python scripts/ci/generate-matrix.py --layer extensions --changed-only --base-ref "$BASE"
+          else
+            python scripts/ci/generate-matrix.py --layer extensions
+          fi
+
+  extensions:
+    name: ${{ matrix.cell.id }}
+    needs: generate
+    if: needs.generate.outputs.count != '0'
+    strategy:
+      fail-fast: false
+      matrix:
+        cell: ${{ fromJson(needs.generate.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Scaffold check (one extension via uvx/PyPI)
+        env:
+          CI: "true"
+          CPA_SKIP_GIT: "1"
+        run: |
+          ADDON_ARGS=()
+          for url in ${{ join(matrix.cell.addons, ' ') }}; do
+            ADDON_ARGS+=(--addon-url "$url")
+          done
+          python scripts/ci/run-scaffold-check.py \
+            --template-url "${{ matrix.cell.templateUrl }}" \
+            --workdir "${{ runner.temp }}/cpa-l2" \
+            "${ADDON_ARGS[@]}"
diff --git a/.github/workflows/ci-integrity.yml b/.github/workflows/ci-integrity.yml
new file mode 100644
index 0000000..8c4c116
--- /dev/null
+++ b/.github/workflows/ci-integrity.yml
@@ -0,0 +1,35 @@
+name: CI Integrity (L0)
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 0 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  integrity:
+    name: Registry + profiles
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate templates.json (on-disk paths + categories)
+        run: python scripts/ci/validate-registry.py
+
+      - name: Validate curated CI profiles
+        run: python scripts/ci/generate-matrix.py --layer validate-profiles
diff --git a/.github/workflows/ci-profiles.yml b/.github/workflows/ci-profiles.yml
new file mode 100644
index 0000000..f8f4d46
--- /dev/null
+++ b/.github/workflows/ci-profiles.yml
@@ -0,0 +1,86 @@
+name: CI Profiles (L3)
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  schedule:
+    - cron: "0 0 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  generate:
+    name: Generate profile matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set.outputs.matrix }}
+      count: ${{ steps.set.outputs.count }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate L3 matrix
+        id: set
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="origin/${BASE_REF}"
+            git fetch origin "${BASE_REF}" --depth=1 || true
+            python scripts/ci/generate-matrix.py --layer profiles --changed-only --base-ref "$BASE"
+          else
+            python scripts/ci/generate-matrix.py --layer profiles
+          fi
+
+  profiles:
+    name: ${{ matrix.cell.id }}
+    needs: generate
+    if: needs.generate.outputs.count != '0'
+    strategy:
+      fail-fast: false
+      matrix:
+        cell: ${{ fromJson(needs.generate.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Scaffold check (curated profile via uvx/PyPI)
+        env:
+          CI: "true"
+          CPA_SKIP_GIT: "1"
+          PROFILE_SETS: ${{ toJson(matrix.cell.sets) }}
+        run: |
+          EXTRA=()
+          while IFS= read -r line; do
+            [ -n "$line" ] && EXTRA+=(--set "$line")
+          done < <(python -c 'import json,os; s=json.loads(os.environ.get("PROFILE_SETS") or "{}");
+[print(f"{k}={v}") for k,v in s.items()]')
+
+          ADDON_ARGS=()
+          for url in ${{ join(matrix.cell.addons, ' ') }}; do
+            ADDON_ARGS+=(--addon-url "$url")
+          done
+          python scripts/ci/run-scaffold-check.py \
+            --template-url "${{ matrix.cell.templateUrl }}" \
+            --workdir "${{ runner.temp }}/cpa-l3" \
+            "${ADDON_ARGS[@]}" \
+            "${EXTRA[@]}"
diff --git a/.github/workflows/ci-templates.yml b/.github/workflows/ci-templates.yml
new file mode 100644
index 0000000..9a902b2
--- /dev/null
+++ b/.github/workflows/ci-templates.yml
@@ -0,0 +1,65 @@
+name: CI Templates (L1)
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 0 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  generate:
+    name: Generate template matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set.outputs.matrix }}
+      count: ${{ steps.set.outputs.count }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate L1 matrix
+        id: set
+        run: python scripts/ci/generate-matrix.py --layer templates
+
+  templates:
+    name: ${{ matrix.cell.id }}
+    needs: generate
+    if: needs.generate.outputs.count != '0'
+    strategy:
+      fail-fast: false
+      matrix:
+        cell: ${{ fromJson(needs.generate.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Scaffold check (template alone via uvx/PyPI)
+        env:
+          CI: "true"
+          CPA_SKIP_GIT: "1"
+        run: |
+          python scripts/ci/run-scaffold-check.py \
+            --template-url "${{ matrix.cell.templateUrl }}" \
+            --workdir "${{ runner.temp }}/cpa-l1"
diff --git a/.github/workflows/smoke-test.yml b/.github/workflows/smoke-test.yml
deleted file mode 100644
index 8f017dc..0000000
--- a/.github/workflows/smoke-test.yml
+++ /dev/null
@@ -1,86 +0,0 @@
-name: Smoke Test
-
-on:
-  pull_request:
-    branches: [main]
-    types: [opened, synchronize, reopened]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  smoke-test:
-    name: Smoke test scaffolded projects
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - name: fastapi-starter
-            extension: ""
-          - name: fastapi-starter + github-setup
-            extension: github-setup
-          - name: fastapi-starter + docker
-            extension: python-docker
-          - name: fastapi-starter + postgres
-            extension: python-postgres
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout cpa-templates
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - name: Checkout create-python-app
-        uses: actions/checkout@v4
-        with:
-          repository: Create-Python-App/create-python-app
-          path: create-python-app
-          persist-credentials: false
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-
-      - name: Resolve CLI (PyPI preferred, source fallback)
-        id: cli
-        run: |
-          if uv tool install "create-awesome-python-app>=0.1.0"; then
-            echo "mode=pypi" >> "$GITHUB_OUTPUT"
-            echo "bin=create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          else
-            echo "PyPI install failed; using create-python-app source checkout"
-            uv sync --directory create-python-app --group dev
-            echo "mode=source" >> "$GITHUB_OUTPUT"
-            echo "bin=uv run --directory create-python-app create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Scaffold project
-        env:
-          CI: "true"
-          CPA_SKIP_GIT: "1"
-          CPA_TEMPLATES_ROOT: ${{ github.workspace }}
-        run: |
-          ADDON_ARGS=()
-          if [ -n "${{ matrix.extension }}" ]; then
-            ADDON_ARGS+=(--addons "file://${CPA_TEMPLATES_ROOT}?subdir=extensions/${{ matrix.extension }}")
-          fi
-          # Typer requires options before the project-directory argument when
-          # the CLI also exposes subcommands (e.g. `cache`).
-          ${{ steps.cli.outputs.bin }} \
-            --template "file://${CPA_TEMPLATES_ROOT}?subdir=templates/fastapi-starter" \
-            --no-interactive --no-install \
-            "${ADDON_ARGS[@]}" \
-            smoke-test-project
-          echo "Project scaffolded: ${{ matrix.name }} (cli=${{ steps.cli.outputs.mode }})"
-
-      - name: Run basic checks
-        working-directory: smoke-test-project
-        run: |
-          uv sync
-          uv run ruff check .
-          uv run pytest -q
-          if [ -f compose.yml ]; then test -f compose.yml; fi
-          if [ -f docker/postgres/compose.yml ]; then test -f docker/postgres/compose.yml; fi
-          echo "Smoke test passed: ${{ matrix.name }}"
diff --git a/.github/workflows/test-combinations.yml b/.github/workflows/test-combinations.yml
deleted file mode 100644
index 6d48a6a..0000000
--- a/.github/workflows/test-combinations.yml
+++ /dev/null
@@ -1,309 +0,0 @@
-name: Test Template and Extension Combinations
-
-on:
-  push:
-    branches:
-      - main
-  schedule:
-    - cron: "0 0 * * 0" # Weekly full matrix on Sunday at midnight UTC
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  generate-combinations:
-    name: Generate test combinations
-    runs-on: ubuntu-latest
-    outputs:
-      matrix: ${{ steps.set-matrix.outputs.matrix }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - name: Generate random combinations
-        id: set-matrix
-        run: |
-          python3 <<'EOF'
-          import json
-          import os
-          import random
-          import re
-
-          with open("templates.json", encoding="utf-8") as f:
-              data = json.load(f)
-
-          repo_dir = os.getcwd()
-          extensions = data["extensions"]
-
-          def ext_local_url(ext):
-              match = re.search(r"/extensions/([^/]+)(?:/|$)", ext["url"])
-              directory = match.group(1) if match else None
-              return f"file://{repo_dir}?subdir=extensions/{directory}" if directory else None
-
-          def has_incompatibility(selected, candidate):
-              candidate_slugs = {candidate["slug"]}
-              selected_slugs = {ext["slug"] for ext in selected}
-              for ext in selected:
-                  incompatible = ext.get("incompatibleWith") or []
-                  if any(slug in candidate_slugs for slug in incompatible):
-                      return True
-                  candidate_incompatible = candidate.get("incompatibleWith") or []
-                  if any(slug in selected_slugs for slug in candidate_incompatible):
-                      return True
-              return False
-
-          random_combinations = []
-          for template in data["templates"]:
-              compatible_extensions = [
-                  ext
-                  for ext in extensions
-                  if template["type"] in (ext["type"] if isinstance(ext["type"], list) else [ext["type"]])
-              ]
-
-              categories = sorted({ext["category"] for ext in compatible_extensions})
-              selected_extensions = []
-              for category in categories:
-                  category_extensions = [ext for ext in compatible_extensions if ext["category"] == category]
-                  available = [ext for ext in category_extensions if not has_incompatibility(selected_extensions, ext)]
-                  if not available:
-                      continue
-                  selected_extensions.append(random.choice(available))
-
-              tpl_match = re.search(r"/templates/([^/]+)(?:/|$)", template["url"])
-              tpl_dir = tpl_match.group(1) if tpl_match else None
-              template_url = (
-                  f"file://{repo_dir}?subdir=templates/{tpl_dir}" if tpl_dir else template["slug"]
-              )
-
-              random_combinations.append(
-                  {
-                      "template": template["slug"],
-                      "templateUrl": template_url,
-                      "extensions": [url for ext in selected_extensions if (url := ext_local_url(ext))],
-                  }
-              )
-
-          matrix = json.dumps(random_combinations)
-          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as out:
-              out.write(f"matrix={matrix}\n")
-          EOF
-
-  test-combinations:
-    name: Test ${{ matrix.combination.template }}
-    needs: generate-combinations
-    strategy:
-      fail-fast: false
-      matrix:
-        combination: ${{ fromJson(needs.generate-combinations.outputs.matrix) }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout cpa-templates
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - name: Checkout create-python-app
-        uses: actions/checkout@v4
-        with:
-          repository: Create-Python-App/create-python-app
-          path: create-python-app
-          persist-credentials: false
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-
-      - name: Resolve CLI (PyPI preferred, source fallback)
-        id: cli
-        run: |
-          if uv tool install "create-awesome-python-app>=0.1.0"; then
-            echo "mode=pypi" >> "$GITHUB_OUTPUT"
-            echo "bin=create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          else
-            echo "PyPI install failed; using create-python-app source checkout"
-            uv sync --directory create-python-app --group dev
-            echo "mode=source" >> "$GITHUB_OUTPUT"
-            echo "bin=uv run --directory create-python-app create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Scaffold and test combination
-        env:
-          CI: "true"
-          CPA_SKIP_GIT: "1"
-          CPA_TEMPLATES_ROOT: ${{ github.workspace }}
-        run: |
-          echo "Testing template: ${{ matrix.combination.template }}"
-          echo "Template URL: ${{ matrix.combination.templateUrl }}"
-          echo "With extensions: ${{ join(matrix.combination.extensions, ' ') }}"
-
-          ADDON_ARGS=()
-          ADDONS="${{ join(matrix.combination.extensions, ' ') }}"
-          if [ -n "$ADDONS" ]; then
-            read -ra EXT_URLS <<< "$ADDONS"
-            ADDON_ARGS=(--addons "${EXT_URLS[@]}")
-          fi
-
-          # Typer requires options before the project-directory argument when
-          # the CLI also exposes subcommands (e.g. `cache`).
-          ${{ steps.cli.outputs.bin }} \
-            --template "${{ matrix.combination.templateUrl }}" \
-            --no-interactive --no-install \
-            "${ADDON_ARGS[@]}" \
-            combination-test-project
-
-          cd combination-test-project
-          uv sync
-          uv run ruff check .
-          uv run pytest -q
-          echo "Combination test passed: ${{ matrix.combination.template }} (cli=${{ steps.cli.outputs.mode }})"
-
-  generate-full-matrix:
-    name: Generate full test matrix
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    outputs:
-      matrix: ${{ steps.set-matrix.outputs.matrix }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - name: Generate full combinations matrix
-        id: set-matrix
-        run: |
-          python3 <<'EOF'
-          import json
-          import os
-          import re
-
-          with open("templates.json", encoding="utf-8") as f:
-              data = json.load(f)
-
-          repo_dir = os.getcwd()
-          extensions = data["extensions"]
-
-          def ext_local_url(ext):
-              match = re.search(r"/extensions/([^/]+)(?:/|$)", ext["url"])
-              directory = match.group(1) if match else None
-              return f"file://{repo_dir}?subdir=extensions/{directory}" if directory else None
-
-          def has_incompatibility(selected, candidate):
-              candidate_slugs = {candidate["slug"]}
-              selected_slugs = {ext["slug"] for ext in selected}
-              for ext in selected:
-                  incompatible = ext.get("incompatibleWith") or []
-                  if any(slug in candidate_slugs for slug in incompatible):
-                      return True
-                  candidate_incompatible = candidate.get("incompatibleWith") or []
-                  if any(slug in selected_slugs for slug in candidate_incompatible):
-                      return True
-              return False
-
-          combinations = []
-          for template in data["templates"]:
-              compatible_extensions = [
-                  ext
-                  for ext in extensions
-                  if template["type"] in (ext["type"] if isinstance(ext["type"], list) else [ext["type"]])
-              ]
-
-              selected_extensions = []
-              for ext in compatible_extensions:
-                  if not has_incompatibility(selected_extensions, ext):
-                      selected_extensions.append(ext)
-
-              if not selected_extensions:
-                  continue
-
-              tpl_match = re.search(r"/templates/([^/]+)(?:/|$)", template["url"])
-              tpl_dir = tpl_match.group(1) if tpl_match else None
-              template_url = (
-                  f"file://{repo_dir}?subdir=templates/{tpl_dir}" if tpl_dir else template["slug"]
-              )
-
-              combinations.append(
-                  {
-                      "template": template["slug"],
-                      "templateUrl": template_url,
-                      "extensions": [url for ext in selected_extensions if (url := ext_local_url(ext))],
-                  }
-              )
-
-          matrix = json.dumps(combinations)
-          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as out:
-              out.write(f"matrix={matrix}\n")
-          print(f"Generated {len(combinations)} full combinations")
-          EOF
-
-  test-full-matrix:
-    name: Full ${{ matrix.combination.template }}
-    needs: generate-full-matrix
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
-    strategy:
-      fail-fast: false
-      matrix:
-        combination: ${{ fromJson(needs.generate-full-matrix.outputs.matrix) }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout cpa-templates
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - name: Checkout create-python-app
-        uses: actions/checkout@v4
-        with:
-          repository: Create-Python-App/create-python-app
-          path: create-python-app
-          persist-credentials: false
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-
-      - name: Resolve CLI (PyPI preferred, source fallback)
-        id: cli
-        run: |
-          if uv tool install "create-awesome-python-app>=0.1.0"; then
-            echo "mode=pypi" >> "$GITHUB_OUTPUT"
-            echo "bin=create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          else
-            echo "PyPI install failed; using create-python-app source checkout"
-            uv sync --directory create-python-app --group dev
-            echo "mode=source" >> "$GITHUB_OUTPUT"
-            echo "bin=uv run --directory create-python-app create-awesome-python-app" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Scaffold and test full combination
-        env:
-          CI: "true"
-          CPA_SKIP_GIT: "1"
-          CPA_TEMPLATES_ROOT: ${{ github.workspace }}
-        run: |
-          echo "Testing: ${{ matrix.combination.template }}"
-          echo "With ALL extensions: ${{ join(matrix.combination.extensions, ' ') }}"
-
-          ADDON_ARGS=()
-          ADDONS="${{ join(matrix.combination.extensions, ' ') }}"
-          if [ -n "$ADDONS" ]; then
-            read -ra EXT_URLS <<< "$ADDONS"
-            ADDON_ARGS=(--addons "${EXT_URLS[@]}")
-          fi
-
-          ${{ steps.cli.outputs.bin }} \
-            --template "${{ matrix.combination.templateUrl }}" \
-            --no-interactive --no-install \
-            "${ADDON_ARGS[@]}" \
-            combination-test-project
-
-          cd combination-test-project
-          uv sync
-          uv run ruff check .
-          uv run pytest -q
-          echo "Full combination test passed: ${{ matrix.combination.template }} (cli=${{ steps.cli.outputs.mode }})"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..03d6e59
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.ci-scaffold/
diff --git a/README.md b/README.md
index 12947b3..f6f49e2 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,12 @@ The canonical catalog is [`templates.json`](./templates.json), consumed by the C
 
 | Workflow | Trigger | Scope |
 |----------|---------|-------|
-| [Smoke Test](./.github/workflows/smoke-test.yml) | PRs to `main` | Scaffold + basic checks on generated projects |
+| [CI Integrity (L0)](./.github/workflows/ci-integrity.yml) | PR + `main` + weekly | Registry paths + curated profiles |
+| [CI Templates (L1)](./.github/workflows/ci-templates.yml) | PR + `main` + weekly | Every template alone via `uvx` (PyPI) |
+| [CI Extensions (L2)](./.github/workflows/ci-extensions.yml) | PR (changed) + weekly | One extension × canonical template |
+| [CI Profiles (L3)](./.github/workflows/ci-profiles.yml) | PR (changed) + weekly | Curated stacks in `ci/profiles/` |
+
+Scaffolding always uses `uvx create-awesome-python-app@latest` from PyPI (never a source checkout of the CLI). Details: [docs/TESTING.md](./docs/TESTING.md), [#46](https://github.com/Create-Python-App/cpa-templates/issues/46).
 
 ## Related repositories
 
diff --git a/ci/profiles/fastapi-default.json b/ci/profiles/fastapi-default.json
new file mode 100644
index 0000000..1bb87fe
--- /dev/null
+++ b/ci/profiles/fastapi-default.json
@@ -0,0 +1,6 @@
+{
+  "id": "fastapi-default",
+  "description": "Typical FastAPI API: GitHub CI + Docker + Postgres",
+  "templateDir": "fastapi-starter",
+  "addons": ["github-setup", "python-docker", "python-postgres"]
+}
diff --git a/ci/profiles/fastapi-devcontainer.json b/ci/profiles/fastapi-devcontainer.json
new file mode 100644
index 0000000..f509eaf
--- /dev/null
+++ b/ci/profiles/fastapi-devcontainer.json
@@ -0,0 +1,6 @@
+{
+  "id": "fastapi-devcontainer",
+  "description": "FastAPI with GitHub CI and VS Code Dev Container",
+  "templateDir": "fastapi-starter",
+  "addons": ["github-setup", "python-devcontainer"]
+}
diff --git a/ci/profiles/fastapi-typed-default.json b/ci/profiles/fastapi-typed-default.json
new file mode 100644
index 0000000..0a490f0
--- /dev/null
+++ b/ci/profiles/fastapi-typed-default.json
@@ -0,0 +1,6 @@
+{
+  "id": "fastapi-typed-default",
+  "description": "Typed FastAPI API: GitHub CI + Docker + Postgres",
+  "templateDir": "fastapi-typed-starter",
+  "addons": ["github-setup", "python-docker", "python-postgres"]
+}
diff --git a/docs/MAINTENANCE_CI.md b/docs/MAINTENANCE_CI.md
index 35b0382..303ff67 100644
--- a/docs/MAINTENANCE_CI.md
+++ b/docs/MAINTENANCE_CI.md
@@ -8,7 +8,7 @@
 
 ## 1. Workflows overview
 
-### `create-python-app`
+### `create-python-app` (CLI monorepo)
 
 | Workflow | Purpose |
 |---|---|
@@ -18,205 +18,108 @@
 | `mega-linter.yml` | MegaLinter across the repo |
 | `osv-scanner.yml` | Security scanning |
 | `publish.yml` | Tag-triggered PyPI release |
-| `smoke-distribution.yml` | End-to-end install smoke tests |
+| `smoke-distribution.yml` | End-to-end install smoke (`uvx`, Docker, brew, AUR) |
 | `pr-review.yml` | PR automation |
 
-### `cpa-templates`
+### `cpa-templates` (layered trust)
 
 | Workflow | Purpose |
 |---|---|
-| `smoke-test.yml` | Quick end-to-end smoke tests on PRs (scaffold + `uv sync` + ruff + pytest) |
-| `test-combinations.yml` | Random + full matrix of template × extension combinations |
+| `ci-integrity.yml` (L0) | Registry on-disk paths + curated profile validation |
+| `ci-templates.yml` (L1) | Every template alone |
+| `ci-extensions.yml` (L2) | One extension × canonical template |
+| `ci-profiles.yml` (L3) | Curated realistic stacks (`ci/profiles/*.json`) |
 
----
-
-## 2. Reading CI failures
-
-Always start with the failed logs:
+**Hard contract:** scaffolding in `cpa-templates` CI always uses:
 
-```bash
-gh run view <run-id> --repo Create-Python-App/<repo> --log-failed
+```sh
+uvx create-awesome-python-app@latest …
 ```
 
-For long logs, filter:
+Never check out `Create-Python-App/create-python-app`. Never fall back to source. Template CI must exercise the same binary users install from PyPI.
 
-```bash
-gh run view <run-id> --repo Create-Python-App/<repo> --log-failed | grep -iE "error|fail|cannot|unable|resolution"
-```
+Retired: `smoke-test.yml`, `test-combinations.yml` (random + all-extensions stacks). See [#46](https://github.com/Create-Python-App/cpa-templates/issues/46).
 
-List recent runs:
+---
+
+## 2. Reading CI failures
 
 ```bash
-gh run list --repo Create-Python-App/<repo> --limit 20
+gh run view <run-id> --repo Create-Python-App/cpa-templates --log-failed
+gh run list --repo Create-Python-App/cpa-templates --limit 20
 ```
 
+| Red cell pattern | Meaning |
+|---|---|
+| `L1 · <template>` | Baseline template broken (or empty scaffold) |
+| `L2 · <ext> @ <template>` | That extension alone breaks the canonical template |
+| `L3 · <profile>` | Curated stack broken (or profile JSON invalid — usually caught in L0) |
+
 ---
 
 ## 3. Running workflows manually
 
 ```bash
-# cpa-templates smoke test
-gh workflow run "Smoke Test" \
-  --repo Create-Python-App/cpa-templates --ref main
-
-# cpa-templates random + full matrix
-gh workflow run "Test Template and Extension Combinations" \
-  --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Integrity (L0)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Templates (L1)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Extensions (L2)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Profiles (L3)" --repo Create-Python-App/cpa-templates --ref main
 
-# Watch until it finishes
 gh run watch <run-id> --repo Create-Python-App/cpa-templates --exit-status
-
-# create-python-app tests
-gh workflow run "Tests" --repo Create-Python-App/create-python-app --ref main
 ```
 
 Use `--ref <branch>` to test a PR branch before merging.
 
 ---
 
-## 4. The `smoke-test.yml` workflow
-
-This workflow runs on every PR to `main`. It:
-
-1. Checks out `cpa-templates` and `create-python-app`.
-2. Installs the CLI from PyPI (falls back to source checkout).
-3. Scaffolds `fastapi-starter` with selected extensions via `file://` URLs.
-4. Runs `uv sync`, `uv run ruff check .`, and `uv run pytest -q`.
-
-### 4.1 Matrix cases
-
-The workflow matrix covers template-only and common single-extension combinations. When adding a new extension, add a matrix row if it should be smoke-tested on every PR.
-
-### 4.2 Common failures
-
-| Symptom | Likely cause |
-|---|---|
-| Scaffold step fails | Invalid `templates.json`, broken `file://` path, CLI regression |
-| `uv sync` fails | Conflicting `pyproject.toml` merge or bad version pin |
-| `ruff check` fails | Generated code or extension files violate lint rules |
-| `pytest` fails | Broken template tests or missing env defaults |
-
-Reproduce locally using the commands in [docs/TESTING.md](./TESTING.md).
-
----
-
-## 5. The `test-combinations.yml` generator
+## 4. Layer details
 
-This workflow is the deepest validation layer. It mirrors the CNA pattern and has four jobs:
+### L0 — Integrity
 
-1. `generate-combinations` — builds a JSON matrix of random, non-conflicting combinations.
-2. `test-combinations` — runs the random matrix.
-3. `generate-full-matrix` — builds a JSON matrix of every template with **all** compatible extensions.
-4. `test-full-matrix` — runs the full matrix.
+Runs `scripts/ci/validate-registry.py` and `generate-matrix.py --layer validate-profiles`.
 
-### 5.1 Random matrix logic
+### L1 — Templates
 
-For each template:
+Matrix from `templates.json`. Each cell:
 
-- Filter compatible extensions by `type`.
-- Group by `category`.
-- Pick one random extension per category.
-- Skip any extension that conflicts with already-selected ones (`incompatibleWith`).
+1. Asserts `file://…?subdir=templates/<dir>` exists (empty-scaffold guard).
+2. `uvx create-awesome-python-app@latest … --no-install`
+3. `uv sync` → `ruff` → optional `mypy`/`pyright` → `pytest`
 
-### 5.2 Full matrix logic
+### L2 — Extensions
 
-For each template:
+One extension on `fastapi-starter` (canonical for `fastapi-backend`).  
+PRs: `--changed-only` unless `templates.json` / `scripts/ci/` / `ci/profiles/` / `ci-*.yml` change (then full).  
+Weekly / manual: full.
 
-- Filter compatible extensions by `type`.
-- Add every mutually-compatible extension to a single job per template.
+### L3 — Profiles
 
-This is the worst-case scenario and catches dependency blowups when all extensions merge into one `pyproject.toml`.
-
-### 5.3 Validation steps per job
-
-Each combination typically:
-
-1. Scaffolds with `CI=true` and `file://` URLs.
-2. Runs `uv sync`.
-3. Runs `uv run ruff check .` when ruff is configured.
-4. Runs `uv run pytest -q` when tests exist.
-
----
-
-## 6. Common workflow failures
-
-### 6.1 Syntax error in embedded generator script
-
-**Cause:** The Python or shell script embedded in the YAML has a duplicate function or variable declaration, or invalid heredoc escaping.
-
-**Fix:** Remove the duplicate or fix escaping in `.github/workflows/test-combinations.yml`.
-
-When the generator uses JavaScript (CNA parity), validate Node blocks locally before pushing—see section 7.
-
-### 6.2 Empty `templateUrl` like `file://?subdir=templates/`
-
-**Cause:** Escaped template variables (`\${repoDir}`, `\${tplDir}`) are passed as literal strings instead of being interpolated by the embedded script.
-
-**Fix:** Use `${repoDir}` and `${tplDir}` without backslashes. GitHub Actions does not interpolate `${...}`, only `${{ ... }}`, so the heredoc receives raw `${repoDir}` text that Node evaluates correctly.
-
-### 6.3 `uv sync` resolution errors
-
-See [MAINTENANCE_DEPENDENCIES.md](./MAINTENANCE_DEPENDENCIES.md).
-
-### 6.4 Full matrix passes but random fails (or vice versa)
-
-This usually means:
-
-- The random matrix hit an unlucky combination not covered by the all-at-once full matrix.
-- The full matrix selects all extensions, shadowing a per-extension failure.
-
-Re-run the exact combination locally using the failed job's `templateUrl` and `extensions`.
+Curated JSON under `ci/profiles/`. Validator enforces **one extension per category** and type compatibility. Split categories (`ci`, `containers`, `database`, `editor`) so realistic stacks stay attributable.
 
 ---
 
-## 7. Testing embedded generator scripts locally
-
-When `test-combinations.yml` embeds Node code inside `<<EOF` heredocs, validate syntax before pushing:
+## 5. Local runner
 
 ```bash
-node - <<'PY'
-const fs = require('fs');
-const txt = fs.readFileSync('.github/workflows/test-combinations.yml', 'utf8');
-let idx = 0;
-for (const match of txt.matchAll(/node <<EOF\n([\s\S]*?)\n          EOF/g)) {
-  let code = match[1].replace(/^          /gm, '');
-  code = code.replace(/\\\`/g, '`').replace(/\\\$/g, '$');
-  try {
-    new Function(code);
-    console.log(`Block ${idx}: OK`);
-  } catch (e) {
-    console.error(`Block ${idx}: SYNTAX ERROR — ${e.message}`);
-    process.exit(1);
-  }
-  idx++;
-}
-PY
+REPO="$PWD"
+python scripts/ci/run-scaffold-check.py \
+  --template-url "file://$REPO?subdir=templates/fastapi-starter" \
+  --addon-url "file://$REPO?subdir=extensions/python-docker" \
+  --workdir /tmp/cpa-check
 ```
 
-Run this from the `cpa-templates` root.
+Requires `uv` / `uvx` on `PATH`.
 
 ---
 
-## 8. Modifying a workflow safely
+## 6. Common failures
 
-1. Make the change in a branch.
-2. Run the syntax validator above when the workflow embeds generator scripts.
-3. Push and open a PR.
-4. Run the workflow manually on the branch if possible:
-   ```bash
-   gh workflow run "Smoke Test" \
-     --repo Create-Python-App/cpa-templates --ref <branch>
-   gh workflow run "Test Template and Extension Combinations" \
-     --repo Create-Python-App/cpa-templates --ref <branch>
-   ```
-5. Merge only after the manual run succeeds.
-
----
-
-## 9. Checklist
+| Symptom | Likely cause |
+|---|---|
+| Scaffold step fails | Invalid `templates.json`, broken `file://` path, CLI regression on PyPI |
+| Empty-guard fails | Wrong `subdir` / silent no-op copy |
+| `uv sync` fails | Conflicting `pyproject.toml` merge or bad version pin |
+| `ruff` / `mypy` / `pytest` fails | Broken template or extension files |
+| `uvx` cannot resolve package | PyPI outage or yanked release — **do not** work around with a source checkout; fix publish |
 
-- [ ] Embedded generator scripts pass local syntax validation.
-- [ ] Workflow YAML is valid (visual check or YAML linter).
-- [ ] Manual workflow run on the branch passes.
-- [ ] The full matrix is green for risky changes.
-- [ ] Changes do not introduce new secret exposure or permissions escalation.
+Reproduce with [docs/TESTING.md](./TESTING.md).
diff --git a/docs/MAINTENANCE_DEPENDENCIES.md b/docs/MAINTENANCE_DEPENDENCIES.md
index d0e9d9e..059d16a 100644
--- a/docs/MAINTENANCE_DEPENDENCIES.md
+++ b/docs/MAINTENANCE_DEPENDENCIES.md
@@ -94,7 +94,7 @@ A major dependency update is high-risk. For each major:
 
 1. Read the changelog or migration guide.
 2. Check `requires-python` and transitive requirements.
-3. Test with the full matrix of the affected template.
+3. Test with L2 isolation for the affected extension(s) and the relevant curated L3 profile(s).
 4. If breaking changes affect generated code, update template `.template` files or extension files.
 
 ---
diff --git a/docs/MAINTENANCE_RUNBOOK.md b/docs/MAINTENANCE_RUNBOOK.md
index 482db4b..40e830c 100644
--- a/docs/MAINTENANCE_RUNBOOK.md
+++ b/docs/MAINTENANCE_RUNBOOK.md
@@ -13,7 +13,7 @@ The project is two repositories that must stay in sync:
 - `create-python-app` — the CLI scaffolding tool, published to PyPI as `create-awesome-python-app`.
 - `cpa-templates` — the template and extension bank consumed by the CLI.
 
-Both have automated CI, automated releases, and a growing surface area of dependencies. A change in one repo (a new FastAPI version, a conflicting extra in an extension, a Python requirement bump) can break the full matrix in the other. This runbook makes that work repeatable and traceable.
+Both have automated CI, automated releases, and a growing surface area of dependencies. A change in one repo (a new FastAPI version, a conflicting extra in an extension, a Python requirement bump) can break layered CI in the other. This runbook makes that work repeatable and traceable.
 
 ---
 
@@ -65,9 +65,7 @@ Use this to decide which procedure to follow:
 
 ```text
 CI is red
-├── Failure is in .github/workflows/test-combinations.yml
-│   └── Read MAINTENANCE_CI.md
-├── Failure is in .github/workflows/smoke-test.yml
+├── Failure is in .github/workflows/ci-*.yml (L0–L3)
 │   └── Read MAINTENANCE_CI.md
 ├── Failure is dependency resolution (uv sync, version conflict, Python requirement)
 │   └── Read MAINTENANCE_DEPENDENCIES.md
@@ -104,7 +102,7 @@ Every task should follow these phases:
 
 - Decide the fix strategy.
 - Identify affected templates/extensions and the CI matrix.
-- Estimate risk. If the change is high-risk, run the full matrix manually before merging.
+- Estimate risk. If the change is high-risk, run L2 for touched extensions and the relevant L3 profile(s) before merging.
 
 ### 5.3 Implement
 
@@ -142,7 +140,7 @@ Every task should follow these phases:
 | Repo | What it is | Critical files | Critical CI |
 |---|---|---|---|
 | `create-python-app` | CLI + monorepo | `packages/*/pyproject.toml`, `.github/workflows/publish.yml` | `test.yml`, `lint.yml`, `type-check.yml`, `publish.yml`, `osv-scanner.yml` |
-| `cpa-templates` | Template/extension bank | `templates.json`, `templates.schema.json`, `templates/`, `extensions/` | `smoke-test.yml`, `test-combinations.yml` |
+| `cpa-templates` | Template/extension bank | `templates.json`, `templates.schema.json`, `templates/`, `extensions/`, `ci/profiles/` | `ci-integrity.yml`, `ci-templates.yml`, `ci-extensions.yml`, `ci-profiles.yml` |
 
 ---
 
@@ -167,10 +165,10 @@ uv run pytest -q
 gh run view <run-id> --repo Create-Python-App/<repo> --log-failed
 
 # --- Run cpa-templates CI manually ---
-gh workflow run "Smoke Test" \
-  --repo Create-Python-App/cpa-templates --ref main
-gh workflow run "Test Template and Extension Combinations" \
-  --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Integrity (L0)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Templates (L1)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Extensions (L2)" --repo Create-Python-App/cpa-templates --ref main
+gh workflow run "CI Profiles (L3)" --repo Create-Python-App/cpa-templates --ref main
 gh run watch <run-id> --repo Create-Python-App/cpa-templates --exit-status
 
 # --- Inspect package versions on PyPI ---
diff --git a/docs/MAINTENANCE_TEMPLATES.md b/docs/MAINTENANCE_TEMPLATES.md
index 1167997..74b29b3 100644
--- a/docs/MAINTENANCE_TEMPLATES.md
+++ b/docs/MAINTENANCE_TEMPLATES.md
@@ -153,7 +153,7 @@ Remove extensions one at a time until the project passes. Then fix the last remo
 4. Add an entry to `templates.json` under `templates`.
 5. Ensure the `url` matches the directory structure (`?subdir=templates/<directory>`).
 6. Run local validation against the new template.
-7. Run smoke test and full matrix after merge.
+7. After merge, confirm L1 (and L2 if applicable) are green on `main`.
 
 ### 5.2 Directory naming caveat
 
@@ -168,7 +168,7 @@ The directory name in `templates/` and the slug in `templates.json` may differ.
 1. Re-scaffold the template with a representative set of extensions.
 2. Apply the change.
 3. Validate ruff and pytest.
-4. Re-scaffold with **all** compatible extensions (full matrix worst case) to detect conflicts.
+4. Re-scaffold with the relevant **curated L3 profile** (or L2 isolation for each touched extension) — do not stack every extension at once.
 
 ---
 
@@ -181,16 +181,16 @@ The directory name in `templates/` and the slug in `templates.json` may differ.
 3. Add files, templates, or appends as needed.
 4. Add the extension to `templates.json` under `extensions`.
 5. Set `type` to match compatible template types.
-6. Set `category` to avoid selecting multiple extensions from the same category in random CI.
+6. Set `category` so curated L3 profiles can pick one extension per category (`ci`, `containers`, `database`, `editor`, …).
 7. Define `incompatibleWith` if it cannot coexist with other extensions.
-8. Validate locally with **each** compatible template.
-9. Validate the full matrix after merge.
+8. Validate locally with **each** compatible template (L2-style isolation).
+9. Confirm L2/L3 stay green after merge.
 
 ### 6.2 Modifying an extension
 
 1. Identify all templates compatible with the extension (`type` match).
 2. Test the extension against **at least one** template locally.
-3. If the change affects dependencies, also test the full matrix of that template (all extensions at once) to detect merge conflicts.
+3. If the change affects dependencies, also test the relevant curated L3 profile(s) for that template — not an all-extensions stack.
 
 ---
 
@@ -209,7 +209,7 @@ In `templates.json`, add `incompatibleWith` to both extensions:
 }
 ```
 
-The CI generator reads this and never selects both in the same combination. The full matrix generator also respects it.
+The CI profile validator and L2 isolation honor `incompatibleWith`. Do not rely on stacking every extension.
 
 ### 7.2 Via dependency constraints
 
@@ -269,4 +269,4 @@ If any step fails, fix the template or extension, then regenerate from scratch.
 - [ ] `incompatibleWith` is defined for mutually exclusive extensions.
 - [ ] `.template` files use available scaffold variables.
 - [ ] Local validation passes.
-- [ ] Full matrix worst case (all compatible extensions) is tested for risky changes.
+- [ ] Risky changes are covered by L2 isolation + relevant L3 profile(s), not an all-extensions stack.
diff --git a/docs/TESTING.md b/docs/TESTING.md
index ec30930..c75b06f 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -20,25 +20,19 @@ Use `file://` URLs to test unpublished templates or extensions without pushing t
 ```sh
 REPO=/absolute/path/to/cpa-templates
 
-# Local template only
-CI=true uv run create-awesome-python-app my-app \
+# Local template only (always use published CLI via uvx)
+CI=true uvx create-awesome-python-app my-app \
   --template "file://$REPO?subdir=templates/fastapi-starter" \
   --no-interactive
 
 # Local template + local extensions
-CI=true uv run create-awesome-python-app my-app \
+CI=true uvx create-awesome-python-app my-app \
   --template "file://$REPO?subdir=templates/fastapi-starter" \
   --addons \
     "file://$REPO?subdir=extensions/github-setup" \
     "file://$REPO?subdir=extensions/python-docker" \
   --no-interactive
 cd my-app && uv sync && uv run pytest
-
-# Remote template slug + local extension (extension-only development)
-CI=true uvx create-awesome-python-app my-app \
-  --template fastapi-starter \
-  --addons "file://$REPO?subdir=extensions/my-new-extension" \
-  --no-interactive
 ```
 
 ### Environment variables
@@ -49,52 +43,38 @@ CI=true uvx create-awesome-python-app my-app \
 | `CPA_SKIP_GIT=1` | Skip `git init` after scaffold |
 | `CPA_CACHE_DIR` | Override template download cache |
 
-### Debug output
-
-Add `--verbose` to scaffold commands when supported by the CLI.
-
-## Smoke test CI
-
-`.github/workflows/smoke-test.yml` runs on pull requests to `main`. It scaffolds projects with `file://` URLs from the PR checkout and runs `uv sync`, lint, and tests.
-
-## Combination matrix CI
+## Layered CI (L0–L3)
 
-`.github/workflows/test-combinations.yml` exercises template × extension combinations from `templates.json`:
+CI must always scaffold with **`uvx create-awesome-python-app@latest` from PyPI**. It never checks out `create-python-app` and never falls back to source.
 
-- **Push to `main`**: one randomly selected extension per category per template (respecting `incompatibleWith`).
-- **Weekly schedule / manual dispatch**: all mutually compatible extensions applied together per template.
+| Layer | Workflow | What green means |
+|-------|----------|------------------|
+| **L0** | `ci-integrity.yml` | Registry paths exist; categories valid; curated profiles valid |
+| **L1** | `ci-templates.yml` | Every template scaffolds alone + `uv sync` + ruff (+ mypy/pyright when configured) + pytest |
+| **L2** | `ci-extensions.yml` | Each extension alone on the canonical template (`fastapi-starter`) |
+| **L3** | `ci-profiles.yml` | Curated one-per-category stacks in `ci/profiles/*.json` |
 
-Each job scaffolds with `file://` URLs, then runs `uv sync`, `uv run ruff check .`, and `uv run pytest -q`.
+**Not run:** stacking every compatible extension at once (that is not a user journey and hides attribution).
 
-To reproduce locally:
+### Local reproduction of CI
 
 ```sh
 REPO="$PWD"
-CI=true CPA_SKIP_GIT=1 uvx create-awesome-python-app combo-test-app \
-  --template "file://$REPO?subdir=templates/fastapi-starter" \
-  --addons \
-    "file://$REPO?subdir=extensions/github-setup" \
-    "file://$REPO?subdir=extensions/python-docker" \
-  --no-interactive --no-install
-cd combo-test-app && uv sync && uv run ruff check . && uv run pytest -q
-```
+python scripts/ci/validate-registry.py
+python scripts/ci/generate-matrix.py --layer validate-profiles
 
-## Smoke test local reproduction
-
-To reproduce the PR smoke test locally:
-
-```sh
-REPO="$PWD"
-CI=true CPA_SKIP_GIT=1 uvx create-awesome-python-app smoke-test-app \
-  --template "file://$REPO?subdir=templates/fastapi-starter" \
-  --no-interactive --no-install
-cd smoke-test-app && uv sync && uv run ruff check . && uv run pytest
+# Same runner the Actions use
+python scripts/ci/run-scaffold-check.py \
+  --template-url "file://$REPO?subdir=templates/fastapi-starter" \
+  --workdir /tmp/cpa-check
 ```
 
 ## Checklist before opening a PR
 
-- [ ] Scaffold succeeds with `file://` URL
+- [ ] Scaffold succeeds with `file://` URL via `uvx` (PyPI CLI)
 - [ ] `uv sync` completes without errors
 - [ ] `uv run ruff check .` passes (when ruff is configured)
+- [ ] Typed templates: `uv run mypy .` / `uv run pyright` pass
 - [ ] `uv run pytest` passes (when tests exist)
 - [ ] Entry added or updated in `templates.json`
+- [ ] New extension has a distinct `category` (ci / containers / database / editor / …)
diff --git a/scripts/ci/generate-matrix.py b/scripts/ci/generate-matrix.py
new file mode 100755
index 0000000..fca79eb
--- /dev/null
+++ b/scripts/ci/generate-matrix.py
@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Generate GitHub Actions matrices for layered CI (see #46)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from registry import (  # noqa: E402
+    REPO_ROOT,
+    as_types,
+    assert_profile_valid,
+    canonical_template_dir_for_type,
+    extension_dir,
+    extension_file_url,
+    find_template_by_dir,
+    load_profiles,
+    load_registry,
+    template_dir,
+    template_file_url,
+)
+
+
+def changed_paths(base_ref: str) -> list[str]:
+    try:
+        out = subprocess.check_output(
+            ["git", "diff", "--name-only", f"{base_ref}...HEAD"],
+            cwd=REPO_ROOT,
+            text=True,
+        )
+        return [line.strip() for line in out.splitlines() if line.strip()]
+    except subprocess.CalledProcessError:
+        # Fail closed: treat as "everything changed" so PR CI does not go green
+        # with an empty matrix when git history is shallow/broken.
+        print(
+            f"⚠ git diff {base_ref}...HEAD failed — forcing full matrix",
+            file=sys.stderr,
+        )
+        return ["templates.json"]
+
+
+def force_full_matrix(changed: list[str]) -> bool:
+    triggers = (
+        "templates.json",
+        "scripts/ci/",
+        "ci/profiles/",
+        ".github/workflows/ci-",
+    )
+    return any(path == t or path.startswith(t) for path in changed for t in triggers)
+
+
+def matrix_templates(registry: dict) -> list[dict]:
+    cells = []
+    for template in registry["templates"]:
+        directory = template_dir(template)
+        cells.append(
+            {
+                "id": f"L1 · {directory}",
+                "slug": template["slug"],
+                "templateDir": directory,
+                "templateUrl": template_file_url(REPO_ROOT, template),
+                "addons": [],
+            }
+        )
+    return cells
+
+
+def matrix_extensions(registry: dict, changed_only: bool, base_ref: str) -> list[dict]:
+    changed = changed_paths(base_ref) if changed_only else []
+    full = (not changed_only) or force_full_matrix(changed)
+    changed_ext_dirs = {
+        path.split("/")[1]
+        for path in changed
+        if path.startswith("extensions/") and len(path.split("/")) > 1
+    }
+
+    cells: list[dict] = []
+    seen: set[str] = set()
+    missing_canonical: list[str] = []
+
+    for extension in registry["extensions"]:
+        directory = extension_dir(extension)
+        if not full and directory not in changed_ext_dirs:
+            continue
+
+        for type_name in as_types(extension.get("type")):
+            canonical_dir = canonical_template_dir_for_type(type_name)
+            if not canonical_dir:
+                missing_canonical.append(f"{extension['slug']} type={type_name}")
+                continue
+            template = find_template_by_dir(registry, canonical_dir)
+            if not template:
+                missing_canonical.append(
+                    f"{extension['slug']} type={type_name} → missing {canonical_dir}"
+                )
+                continue
+
+            key = f"{extension['slug']}@@{canonical_dir}"
+            if key in seen:
+                continue
+            seen.add(key)
+
+            cells.append(
+                {
+                    "id": f"L2 · {extension['slug']} @ {canonical_dir}",
+                    "slug": extension["slug"],
+                    "extensionDir": directory,
+                    "templateDir": canonical_dir,
+                    "templateUrl": template_file_url(REPO_ROOT, template),
+                    "addons": [extension_file_url(REPO_ROOT, extension)],
+                    "type": type_name,
+                }
+            )
+
+    if missing_canonical:
+        raise SystemExit(
+            "Extensions without a canonical L2 template:\n  - "
+            + "\n  - ".join(missing_canonical)
+        )
+    return cells
+
+
+def matrix_profiles(registry: dict, changed_only: bool, base_ref: str) -> list[dict]:
+    profiles = load_profiles()
+    changed = changed_paths(base_ref) if changed_only else []
+    full = (not changed_only) or force_full_matrix(changed)
+
+    cells: list[dict] = []
+    for profile in profiles:
+        template, addons = assert_profile_valid(registry, profile)
+
+        if not full:
+            touched_template = any(
+                path.startswith(f"templates/{profile['templateDir']}/") for path in changed
+            )
+            touched_addon = any(
+                any(
+                    path.startswith(f"extensions/{extension_dir(ext)}/")
+                    for path in changed
+                )
+                for ext in addons
+            )
+            touched_profile = any(
+                path == f"ci/profiles/{profile['_file']}" for path in changed
+            )
+            if not (touched_template or touched_addon or touched_profile):
+                continue
+
+        cells.append(
+            {
+                "id": f"L3 · {profile['id']}",
+                "profileId": profile["id"],
+                "templateDir": profile["templateDir"],
+                "templateUrl": template_file_url(REPO_ROOT, template),
+                "addons": [extension_file_url(REPO_ROOT, ext) for ext in addons],
+                "sets": profile.get("sets") or {},
+            }
+        )
+    return cells
+
+
+def validate_all_profiles(registry: dict) -> list[dict]:
+    profiles = load_profiles()
+    for profile in profiles:
+        assert_profile_valid(registry, profile)
+        print(f"✅ profile {profile['id']}", file=sys.stderr)
+    print(f"Validated {len(profiles)} profiles", file=sys.stderr)
+    return []
+
+
+def write_output(matrix: list[dict]) -> None:
+    payload = json.dumps(matrix)
+    sys.stdout.write(payload + "\n")
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output:
+        delim = "MATRIX_EOF"
+        with Path(github_output).open("a", encoding="utf-8") as handle:
+            handle.write(f"matrix<<{delim}\n{payload}\n{delim}\n")
+            handle.write(f"count={len(matrix)}\n")
+    print(f"Generated {len(matrix)} matrix cell(s)", file=sys.stderr)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate layered CI matrices for cpa-templates"
+    )
+    parser.add_argument(
+        "--layer",
+        required=True,
+        choices=["templates", "extensions", "profiles", "validate-profiles"],
+    )
+    parser.add_argument("--changed-only", action="store_true")
+    parser.add_argument("--base-ref", default="origin/main")
+    args = parser.parse_args()
+
+    registry = load_registry()
+    if args.layer == "templates":
+        matrix = matrix_templates(registry)
+    elif args.layer == "extensions":
+        matrix = matrix_extensions(registry, args.changed_only, args.base_ref)
+    elif args.layer == "profiles":
+        matrix = matrix_profiles(registry, args.changed_only, args.base_ref)
+    else:
+        matrix = validate_all_profiles(registry)
+
+    write_output(matrix)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/ci/registry.py b/scripts/ci/registry.py
new file mode 100755
index 0000000..5c45733
--- /dev/null
+++ b/scripts/ci/registry.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Registry helpers for layered CI (see #46)."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+TEMPLATES_JSON = REPO_ROOT / "templates.json"
+PROFILES_DIR = REPO_ROOT / "ci" / "profiles"
+
+# Canonical template directory per extension `type`.
+CANONICAL_TEMPLATE_BY_TYPE: dict[str, str] = {
+    "fastapi-backend": "fastapi-starter",
+}
+
+
+def load_registry() -> dict[str, Any]:
+    return json.loads(TEMPLATES_JSON.read_text(encoding="utf-8"))
+
+
+def dir_from_url(url: str, kind: str) -> str | None:
+    """Resolve on-disk directory name from a registry URL.
+
+    CPA registry URLs look like:
+      https://github.com/Create-Python-App/cpa-templates?subdir=templates/fastapi-starter
+    (subdir lives in the query string, not the path).
+    """
+    prefix = "templates" if kind == "template" else "extensions"
+    # Query-string form (canonical for CPA)
+    match = re.search(rf"[?&]subdir={prefix}/([^/&]+)(?:/|&|$)", url or "")
+    if match:
+        return match.group(1)
+    # Path form (compat)
+    match = re.search(rf"/{prefix}/([^/]+)(?:/|$)", url or "")
+    return match.group(1) if match else None
+
+
+def template_dir(template: dict[str, Any]) -> str | None:
+    return dir_from_url(template.get("url", ""), "template")
+
+
+def extension_dir(extension: dict[str, Any]) -> str | None:
+    return dir_from_url(extension.get("url", ""), "extension")
+
+
+def as_types(type_field: Any) -> list[str]:
+    if isinstance(type_field, list):
+        return list(type_field)
+    return [type_field]
+
+
+def cpa_file_url(repo_root: Path, relative_subdir: str) -> str:
+    """CPA CLI expects file://<repo>?subdir=<path> (not a bare dir URL)."""
+    return f"file://{repo_root.resolve()}?subdir={relative_subdir}"
+
+
+def template_file_url(repo_root: Path, template: dict[str, Any]) -> str:
+    directory = template_dir(template)
+    if not directory:
+        raise ValueError(f"Cannot resolve directory for template slug={template.get('slug')}")
+    return cpa_file_url(repo_root, f"templates/{directory}")
+
+
+def extension_file_url(repo_root: Path, extension: dict[str, Any]) -> str:
+    directory = extension_dir(extension)
+    if not directory:
+        raise ValueError(f"Cannot resolve directory for extension slug={extension.get('slug')}")
+    return cpa_file_url(repo_root, f"extensions/{directory}")
+
+
+def canonical_template_dir_for_type(type_name: str) -> str | None:
+    return CANONICAL_TEMPLATE_BY_TYPE.get(type_name)
+
+
+def find_template_by_dir(registry: dict[str, Any], directory: str) -> dict[str, Any] | None:
+    for template in registry.get("templates", []):
+        if template_dir(template) == directory:
+            return template
+    return None
+
+
+def has_incompatibility(selected: list[dict[str, Any]], candidate: dict[str, Any]) -> bool:
+    candidate_slugs = {candidate["slug"]}
+    selected_slugs = {ext["slug"] for ext in selected}
+    for ext in selected:
+        incompatible = ext.get("incompatibleWith") or []
+        if any(slug in candidate_slugs for slug in incompatible):
+            return True
+        candidate_incompatible = candidate.get("incompatibleWith") or []
+        if any(slug in selected_slugs for slug in candidate_incompatible):
+            return True
+    return False
+
+
+def load_profiles() -> list[dict[str, Any]]:
+    if not PROFILES_DIR.is_dir():
+        return []
+    profiles: list[dict[str, Any]] = []
+    for path in sorted(PROFILES_DIR.glob("*.json")):
+        profile = json.loads(path.read_text(encoding="utf-8"))
+        profiles.append({**profile, "_file": path.name})
+    return profiles
+
+
+def resolve_profile_addons(
+    registry: dict[str, Any], profile: dict[str, Any]
+) -> list[dict[str, Any]]:
+    addons: list[dict[str, Any]] = []
+    for slug in profile.get("addons") or []:
+        ext = next((e for e in registry.get("extensions", []) if e["slug"] == slug), None)
+        if not ext:
+            raise ValueError(f'Profile {profile.get("id")}: unknown addon slug "{slug}"')
+        addons.append(ext)
+    return addons
+
+
+def assert_profile_valid(
+    registry: dict[str, Any], profile: dict[str, Any]
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    template = find_template_by_dir(registry, profile["templateDir"])
+    if not template:
+        raise ValueError(
+            f'Profile {profile.get("id")}: unknown templateDir "{profile.get("templateDir")}"'
+        )
+    addons = resolve_profile_addons(registry, profile)
+    categories: dict[str, str] = {}
+    for ext in addons:
+        category = ext.get("category")
+        if category in categories:
+            raise ValueError(
+                f'Profile {profile.get("id")}: category "{category}" used twice '
+                f'({categories[category]} and {ext["slug"]})'
+            )
+        categories[category] = ext["slug"]
+
+        template_types = as_types(template.get("type"))
+        ext_types = as_types(ext.get("type"))
+        if not any(t in ext_types for t in template_types):
+            raise ValueError(
+                f'Profile {profile.get("id")}: addon "{ext["slug"]}" does not support '
+                f'template type(s) {template_types}'
+            )
+
+    selected: list[dict[str, Any]] = []
+    for ext in addons:
+        if has_incompatibility(selected, ext):
+            raise ValueError(
+                f'Profile {profile.get("id")}: incompatible addons involving {ext["slug"]}'
+            )
+        selected.append(ext)
+    return template, addons
+
+
+def on_disk_path_for_entry(kind: str, entry: dict[str, Any]) -> Path | None:
+    directory = template_dir(entry) if kind == "template" else extension_dir(entry)
+    if not directory:
+        return None
+    return REPO_ROOT / ("templates" if kind == "template" else "extensions") / directory
diff --git a/scripts/ci/run-scaffold-check.py b/scripts/ci/run-scaffold-check.py
new file mode 100755
index 0000000..ce4b215
--- /dev/null
+++ b/scripts/ci/run-scaffold-check.py
@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Scaffold a template (+ optional addons) via uvx from PyPI and run health checks.
+
+Hard constraint (#46): always invoke the published CLI with `uvx create-awesome-python-app`.
+Never check out create-python-app source. Never fall back to a local install.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import unquote, urlparse, parse_qs
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from registry import REPO_ROOT  # noqa: E402
+
+CLI_PACKAGE = "create-awesome-python-app"
+# Pin to the published distribution channel users get; `@latest` refreshes on runners.
+UVX_SPEC = f"{CLI_PACKAGE}@latest"
+
+
+def fail(phase: str, message: str, code: int = 1) -> None:
+    print(f"\n❌ [{phase}] {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def run(phase: str, cmd: list[str], *, cwd: Path | None = None, env: dict | None = None) -> None:
+    print(f"\n▶ [{phase}] {' '.join(cmd)}")
+    merged = {
+        **os.environ,
+        "CI": "true",
+        "CPA_SKIP_GIT": os.environ.get("CPA_SKIP_GIT", "1"),
+        "FORCE_COLOR": "0",
+        **(env or {}),
+    }
+    result = subprocess.run(cmd, cwd=cwd, env=merged)
+    if result.returncode != 0:
+        fail(phase, f"command failed with exit code {result.returncode}", result.returncode)
+
+
+def resolve_file_target(file_url: str) -> Path:
+    if not file_url.startswith("file://"):
+        fail("scaffold", f"URL must be file://, got: {file_url}")
+    parsed = urlparse(file_url)
+    pathname = unquote(parsed.path)
+    subdir_list = parse_qs(parsed.query).get("subdir")
+    if subdir_list:
+        return Path(pathname) / subdir_list[0]
+    return Path(pathname)
+
+
+def assert_template_url_exists(template_url: str) -> None:
+    target = resolve_file_target(template_url)
+    if not target.exists():
+        fail(
+            "scaffold",
+            f"template path does not exist: {target}\n"
+            "  (refusing to continue — this is how empty scaffolds go green)",
+        )
+    if not target.is_dir():
+        fail("scaffold", f"template path is not a directory: {target}")
+    print(f"✅ [scaffold] template path exists: {target}")
+
+
+def assert_non_empty_project(project_root: Path) -> None:
+    pyproject = project_root / "pyproject.toml"
+    if not pyproject.is_file():
+        fail("empty-guard", f"missing pyproject.toml in {project_root}")
+
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    project = data.get("project") or {}
+    deps = list(project.get("dependencies") or [])
+    groups = data.get("dependency-groups") or {}
+    group_dep_count = sum(len(v) for v in groups.values() if isinstance(v, list))
+    dep_count = len(deps) + group_dep_count
+
+    entries = [
+        name
+        for name in os.listdir(project_root)
+        if name not in {".git", ".venv", ".ci-meta.json", "__pycache__"}
+    ]
+
+    if len(entries) < 3 and dep_count == 0:
+        fail(
+            "empty-guard",
+            f"scaffold looks empty ({len(entries)} entries, 0 deps). "
+            "Likely wrong template path / silent no-op copy.",
+        )
+
+    if dep_count == 0:
+        fail(
+            "empty-guard",
+            "pyproject.toml has no dependencies / dependency-groups — refusing green CI",
+        )
+
+    print(
+        f"✅ [empty-guard] project ok ({len(entries)} top-level entries, {dep_count} deps)"
+    )
+
+
+def has_tool_config(project_root: Path, tool: str) -> bool:
+    pyproject = project_root / "pyproject.toml"
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    tools = data.get("tool") or {}
+    if tool in tools:
+        return True
+    groups = data.get("dependency-groups") or {}
+    for group_deps in groups.values():
+        if not isinstance(group_deps, list):
+            continue
+        for dep in group_deps:
+            if isinstance(dep, str) and dep.split(">")[0].split("=")[0].split("[")[0] == tool:
+                return True
+    return False
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="CPA layered CI scaffold check (uvx/PyPI only)")
+    parser.add_argument("--template-url", required=True)
+    parser.add_argument("--addon-url", action="append", default=[])
+    parser.add_argument("--set", dest="sets", action="append", default=[])
+    parser.add_argument("--workdir", default=str(REPO_ROOT / ".ci-scaffold"))
+    parser.add_argument("--project-name", default="scaffold-check")
+    parser.add_argument("--skip-test", action="store_true")
+    parser.add_argument("--skip-lint", action="store_true")
+    parser.add_argument("--skip-type-check", action="store_true")
+    parser.add_argument("--keep", action="store_true")
+    args = parser.parse_args()
+
+    for assignment in args.sets:
+        if assignment.startswith("projectName="):
+            args.project_name = assignment.split("=", 1)[1]
+
+    if shutil.which("uvx") is None:
+        fail("scaffold", "uvx not found on PATH — install uv (https://docs.astral.sh/uv/)")
+
+    assert_template_url_exists(args.template_url)
+
+    workdir = Path(args.workdir)
+    if workdir.exists():
+        shutil.rmtree(workdir)
+    workdir.mkdir(parents=True)
+
+    project_root = workdir / args.project_name
+
+    scaffold_cmd = [
+        "uvx",
+        UVX_SPEC,
+        "--template",
+        args.template_url,
+        "--no-interactive",
+        "--no-install",
+    ]
+    if args.addon_url:
+        scaffold_cmd.append("--addons")
+        scaffold_cmd.extend(args.addon_url)
+    for assignment in args.sets:
+        scaffold_cmd.extend(["--set", assignment])
+    scaffold_cmd.append(args.project_name)
+
+    run("scaffold", scaffold_cmd, cwd=workdir)
+
+    if not project_root.is_dir():
+        fail("scaffold", f"expected project at {project_root}")
+
+    assert_non_empty_project(project_root)
+
+    run("install", ["uv", "sync"], cwd=project_root)
+
+    if not args.skip_lint and has_tool_config(project_root, "ruff"):
+        run("lint", ["uv", "run", "ruff", "check", "."], cwd=project_root)
+    elif not args.skip_lint:
+        print("ℹ [lint] skipped (ruff not configured)")
+
+    if not args.skip_type_check:
+        if has_tool_config(project_root, "mypy"):
+            run("type-check", ["uv", "run", "mypy", "."], cwd=project_root)
+        if has_tool_config(project_root, "pyright"):
+            run("type-check", ["uv", "run", "pyright"], cwd=project_root)
+
+    if not args.skip_test:
+        if has_tool_config(project_root, "pytest") or (project_root / "tests").is_dir():
+            run("test", ["uv", "run", "pytest", "-q"], cwd=project_root)
+        else:
+            print("ℹ [test] skipped (no pytest / tests/)")
+
+    print("\n✅ scaffold-check passed")
+    if not args.keep:
+        shutil.rmtree(workdir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/ci/validate-registry.py b/scripts/ci/validate-registry.py
new file mode 100755
index 0000000..e7afd0f
--- /dev/null
+++ b/scripts/ci/validate-registry.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""L0 integrity: registry paths on disk + schema shape."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from registry import (  # noqa: E402
+    REPO_ROOT,
+    TEMPLATES_JSON,
+    as_types,
+    extension_dir,
+    load_registry,
+    on_disk_path_for_entry,
+    template_dir,
+)
+
+
+def main() -> None:
+    registry = load_registry()
+    errors: list[str] = []
+
+    if not TEMPLATES_JSON.is_file():
+        errors.append(f"missing {TEMPLATES_JSON}")
+
+    schema_path = REPO_ROOT / "templates.schema.json"
+    if schema_path.is_file():
+        # Structural presence only; full JSON Schema validation is optional.
+        json.loads(schema_path.read_text(encoding="utf-8"))
+
+    category_slugs = {c["slug"] for c in registry.get("categories", [])}
+
+    for template in registry.get("templates", []):
+        directory = template_dir(template)
+        if not directory:
+            errors.append(f"template {template.get('slug')}: cannot parse url")
+            continue
+        path = on_disk_path_for_entry("template", template)
+        if path is None or not path.is_dir():
+            errors.append(f"template {template.get('slug')}: missing on-disk path {path}")
+        category = template.get("category")
+        if category not in category_slugs:
+            errors.append(f"template {template.get('slug')}: unknown category {category}")
+
+    for extension in registry.get("extensions", []):
+        directory = extension_dir(extension)
+        if not directory:
+            errors.append(f"extension {extension.get('slug')}: cannot parse url")
+            continue
+        path = on_disk_path_for_entry("extension", extension)
+        if path is None or not path.is_dir():
+            errors.append(f"extension {extension.get('slug')}: missing on-disk path {path}")
+        category = extension.get("category")
+        if category not in category_slugs:
+            errors.append(f"extension {extension.get('slug')}: unknown category {category}")
+        if not as_types(extension.get("type")):
+            errors.append(f"extension {extension.get('slug')}: empty type")
+
+        # Bidirectional incompatibleWith when declared
+        for other_slug in extension.get("incompatibleWith") or []:
+            other = next(
+                (e for e in registry["extensions"] if e["slug"] == other_slug), None
+            )
+            if other is None:
+                errors.append(
+                    f"extension {extension['slug']}: incompatibleWith unknown slug {other_slug}"
+                )
+            elif extension["slug"] not in (other.get("incompatibleWith") or []):
+                errors.append(
+                    f"extension {extension['slug']}: incompatibleWith {other_slug} "
+                    "is not symmetric"
+                )
+
+    if errors:
+        print("Registry integrity failed:", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        raise SystemExit(1)
+
+    print(
+        f"✅ registry ok "
+        f"({len(registry.get('templates', []))} templates, "
+        f"{len(registry.get('extensions', []))} extensions)"
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/templates.json b/templates.json
index 0c627e7..c4259c0 100644
--- a/templates.json
+++ b/templates.json
@@ -5,15 +5,55 @@
       "slug": "backend-applications",
       "name": "Backend Applications",
       "description": "API and service starters for FastAPI and similar Python backends.",
-      "details": "Use when the deliverable is an HTTP API or background worker — FastAPI for async APIs with OpenAPI docs.",
-      "labels": ["Backend", "API", "Python", "FastAPI"]
+      "details": "Use when the deliverable is an HTTP API or background worker \u2014 FastAPI for async APIs with OpenAPI docs.",
+      "labels": [
+        "Backend",
+        "API",
+        "Python",
+        "FastAPI"
+      ]
     },
     {
-      "slug": "tooling",
-      "name": "Tooling",
-      "description": "Extensions that add CI, containers, databases, and developer ergonomics.",
-      "details": "Layer these on top of a compatible template after choosing your base stack.",
-      "labels": ["DevOps", "CI", "Docker", "Tooling"]
+      "slug": "ci",
+      "name": "CI",
+      "description": "Continuous integration and repository automation.",
+      "details": "GitHub Actions, Dependabot, and related repository workflows.",
+      "labels": [
+        "CI",
+        "GitHub",
+        "DevOps"
+      ]
+    },
+    {
+      "slug": "containers",
+      "name": "Containers",
+      "description": "Docker and Compose packaging for the app.",
+      "details": "Add when you want container images and compose stacks for the API.",
+      "labels": [
+        "Docker",
+        "Compose",
+        "DevOps"
+      ]
+    },
+    {
+      "slug": "database",
+      "name": "Database",
+      "description": "Database services and connection scaffolding.",
+      "details": "Pair with the app when you need Postgres (or similar) locally/in compose.",
+      "labels": [
+        "PostgreSQL",
+        "Database"
+      ]
+    },
+    {
+      "slug": "editor",
+      "name": "Editor",
+      "description": "Editor and remote development ergonomics.",
+      "details": "Dev Containers and related IDE integrations.",
+      "labels": [
+        "DevContainer",
+        "VS Code"
+      ]
     }
   ],
   "templates": [
@@ -24,7 +64,13 @@
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=templates/fastapi-starter",
       "type": "fastapi-backend",
       "category": "backend-applications",
-      "labels": ["FastAPI", "API", "Python", "uv", "Backend"]
+      "labels": [
+        "FastAPI",
+        "API",
+        "Python",
+        "uv",
+        "Backend"
+      ]
     },
     {
       "name": "FastAPI Typed Starter",
@@ -33,7 +79,14 @@
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=templates/fastapi-typed-starter",
       "type": "fastapi-backend",
       "category": "backend-applications",
-      "labels": ["FastAPI", "API", "Python", "Type Hints", "mypy", "pyright"]
+      "labels": [
+        "FastAPI",
+        "API",
+        "Python",
+        "Type Hints",
+        "mypy",
+        "pyright"
+      ]
     }
   ],
   "extensions": [
@@ -42,36 +95,60 @@
       "slug": "github-setup",
       "description": "GitHub Actions CI, Dependabot, issue templates, and PR template",
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=extensions/github-setup",
-      "type": ["fastapi-backend"],
-      "category": "tooling",
-      "labels": ["GitHub", "CI", "DevOps"]
+      "type": [
+        "fastapi-backend"
+      ],
+      "category": "ci",
+      "labels": [
+        "GitHub",
+        "CI",
+        "DevOps"
+      ]
     },
     {
       "name": "Python Docker",
       "slug": "python-docker",
       "description": "Dockerfile, compose.yml, and compose.prod.yml for local and containerized runs",
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=extensions/python-docker",
-      "type": ["fastapi-backend"],
-      "category": "tooling",
-      "labels": ["Docker", "DevOps", "Container"]
+      "type": [
+        "fastapi-backend"
+      ],
+      "category": "containers",
+      "labels": [
+        "Docker",
+        "DevOps",
+        "Container"
+      ]
     },
     {
       "name": "Python Postgres",
       "slug": "python-postgres",
       "description": "PostgreSQL service under docker/postgres/compose.yml plus env examples",
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=extensions/python-postgres",
-      "type": ["fastapi-backend"],
-      "category": "tooling",
-      "labels": ["PostgreSQL", "Database", "Docker"]
+      "type": [
+        "fastapi-backend"
+      ],
+      "category": "database",
+      "labels": [
+        "PostgreSQL",
+        "Database",
+        "Docker"
+      ]
     },
     {
       "name": "Python Dev Container",
       "slug": "python-devcontainer",
       "description": "VS Code Dev Container with Python 3.12 and uv",
       "url": "https://github.com/Create-Python-App/cpa-templates?subdir=extensions/python-devcontainer",
-      "type": ["fastapi-backend"],
-      "category": "tooling",
-      "labels": ["DevContainer", "VS Code", "uv"]
+      "type": [
+        "fastapi-backend"
+      ],
+      "category": "editor",
+      "labels": [
+        "DevContainer",
+        "VS Code",
+        "uv"
+      ]
     }
   ]
 }
diff --git a/templates/fastapi-typed-starter/app/core/exception_handlers.py b/templates/fastapi-typed-starter/app/core/exception_handlers.py
index 091f8e6..3b259e8 100644
--- a/templates/fastapi-typed-starter/app/core/exception_handlers.py
+++ b/templates/fastapi-typed-starter/app/core/exception_handlers.py
@@ -55,5 +55,7 @@ async def unexpected_error_handler(request: Request, exc: Exception) -> JSONResp
 
 def register_exception_handlers(app: FastAPI) -> None:
     """Register application exception handlers."""
-    app.add_exception_handler(RequestValidationError, request_validation_handler)
+    # Starlette's add_exception_handler types handlers as Exception-wide; FastAPI
+    # still dispatches the concrete exception type at runtime.
+    app.add_exception_handler(RequestValidationError, request_validation_handler)  # type: ignore[arg-type]
     app.add_exception_handler(Exception, unexpected_error_handler)
diff --git a/templates/fastapi-typed-starter/tests/test_health.py.template b/templates/fastapi-typed-starter/tests/test_health.py.template
index 06a2a85..a048a81 100644
--- a/templates/fastapi-typed-starter/tests/test_health.py.template
+++ b/templates/fastapi-typed-starter/tests/test_health.py.template
@@ -37,5 +37,8 @@ def test_ping_returns_ok(client: TestClient) -> None:
 
 
 def test_cors_middleware_matches_scaffold_option() -> None:
-    middleware_names = [middleware.cls.__name__ for middleware in app.user_middleware]
+    middleware_names = [
+        getattr(middleware.cls, "__name__", type(middleware.cls).__name__)
+        for middleware in app.user_middleware
+    ]
     assert ("CORSMiddleware" in middleware_names) is settings.enable_cors

From 0f313a327076f261b371db8a01cff1555018cb40 Mon Sep 17 00:00:00 2001
From: ulises-jeremias <ulisescf.24@gmail.com>
Date: Fri, 17 Jul 2026 01:45:14 -0300
Subject: [PATCH 2/3] ci: fix L3 workflow YAML (single-line PROFILE_SETS
 parser)

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .github/workflows/ci-profiles.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/ci-profiles.yml b/.github/workflows/ci-profiles.yml
index f8f4d46..7e216cc 100644
--- a/.github/workflows/ci-profiles.yml
+++ b/.github/workflows/ci-profiles.yml
@@ -72,8 +72,7 @@ jobs:
           EXTRA=()
           while IFS= read -r line; do
             [ -n "$line" ] && EXTRA+=(--set "$line")
-          done < <(python -c 'import json,os; s=json.loads(os.environ.get("PROFILE_SETS") or "{}");
-[print(f"{k}={v}") for k,v in s.items()]')
+          done < <(python -c 'import json,os; s=json.loads(os.environ.get("PROFILE_SETS") or "{}"); [print(f"{k}={v}") for k,v in s.items()]')
 
           ADDON_ARGS=()
           for url in ${{ join(matrix.cell.addons, ' ') }}; do

From e345fd697991934a9bda5140e38634f58988e10f Mon Sep 17 00:00:00 2001
From: ulises-jeremias <ulisescf.24@gmail.com>
Date: Fri, 17 Jul 2026 01:47:26 -0300
Subject: [PATCH 3/3] ci: pass each addon as its own --addons flag for Typer

A single --addons followed by multiple URLs makes Typer treat later URLs
as project_directory / COMMAND (e.g. No such command 'scaffold-check').

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 scripts/ci/run-scaffold-check.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/scripts/ci/run-scaffold-check.py b/scripts/ci/run-scaffold-check.py
index ce4b215..49620b5 100755
--- a/scripts/ci/run-scaffold-check.py
+++ b/scripts/ci/run-scaffold-check.py
@@ -161,9 +161,10 @@ def main() -> None:
         "--no-interactive",
         "--no-install",
     ]
-    if args.addon_url:
-        scaffold_cmd.append("--addons")
-        scaffold_cmd.extend(args.addon_url)
+    # Typer list options take one value per flag. Passing multiple URLs after a
+    # single --addons makes later URLs look like project_directory / COMMAND.
+    for addon_url in args.addon_url:
+        scaffold_cmd.extend(["--addons", addon_url])
     for assignment in args.sets:
         scaffold_cmd.extend(["--set", assignment])
     scaffold_cmd.append(args.project_name)