docs: clarify custom project images vs upstream open-source infrastructure in COMPOSE_CONVENTIONS.md

COMPOSE_CONVENTIONS.md

@@ -60,49 +60,46 @@ across our infrastructure.
 
 ## 3. Container Registries, Mirrors & Image Distribution
 
-Our infrastructure uses a tiered registry architecture to balance local caching,
+Our infrastructure uses a tiered registry architecture to clearly separate
-private custom image hosting, and universal build portability:
+custom application images from upstream cached dependencies:
 
 ### 3.1 Registry Tier Classification
 
 1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):**
-   - Hosts all internally built, project-specific custom images
+   - Hosts all internally built, project-specific custom application images
-     (`${REG}/library/<image>:<tag>`).
+     (`${REG}/library/<app>:<tag>`).
-   - Examples: `${REG}/library/auth-yes-api:latest`,
+   - Example: `${REG}/library/auth-yes-api:latest` (built from project source).
-     `${REG}/library/spire-server:latest`, `${REG}/library/spire-agent:latest`.
+   - Retained **indefinitely** on disk (auto-pruning disabled).
-   - Retention policy is set for **indefinite storage** (auto-pruning disabled).
 2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):**
-   - Proxies and indefinitely caches upstream Docker Hub images on the local
+   - Proxies and indefinitely caches upstream Docker Hub infrastructure images
-     network.
+     on the local network.
    - Examples: `acr.atyg.org/library/postgres:18-alpine`,
      `acr.atyg.org/valkey/valkey:8-alpine`, `acr.atyg.org/library/alpine:3.20`.
 3. **GHCR Pull-Through Mirror (`${GHCR_REG}` $\rightarrow$ `ghcr.atyg.org`):**
-   - Proxies and caches GitHub Container Registry packages.
+   - Proxies and caches upstream GitHub Container Registry infrastructure
+     images.
    - Examples: `${GHCR_REG}/spiffe/spire-server:1.9.3`,
      `${GHCR_REG}/spiffe/spire-agent:1.9.3`.
 
 ### 3.2 Universal Dockerfile Portability (Jules & External CI)
 
-- **Public Upstream Defaults:** Dockerfiles must declare public upstream
+- **Public Upstream Defaults:** Dockerfiles for custom application images or
-  registries by default so external agents (like Jules) and cloud CI runners can
+  wrappers must declare public upstream registries by default so external agents
-  build without private `.atyg.org` DNS:
+  (like Jules) and cloud CI runners can build without private `.atyg.org` DNS:
   ```dockerfile
-  ARG SPIRE_UPSTREAM=ghcr.io/spiffe/spire-server:1.9.3
   ARG BASE_IMAGE=alpine:3.20
-
-  FROM ${SPIRE_UPSTREAM} AS upstream
   FROM ${BASE_IMAGE}
   ```
 - **Local Build Acceleration:** Local builds and CLI scripts (`infra/setup.ts`)
   can optionally pass `--build-arg` to pull through local mirrors
   (`ghcr.atyg.org`, `acr.atyg.org`).
-- **Push Destination:** Custom built images are tagged and pushed to the local
+- **Push Destination:** Custom built application images are tagged and pushed to
-  authority `${REG}/library/...` (`quay.atyg.org`).
+  the local authority `${REG}/library/...` (`quay.atyg.org`).
 
 ### 3.3 Compose Variable Cleanliness
 
 - **No Inline Defaults:** Always write clean variable references in Compose
-  files (`image: ${REG}/library/spire-server:latest`,
+  files (`image: ${REG}/library/auth-yes-api:latest`,
   `image: ${GHCR_REG}/spiffe/spire-server:1.9.3`).
 - **Centralized Values:** Default registry variables belong strictly in `.env`
   and `infra/setup.ts`.