feat: poblar scaffold inicial del shape rest-api/python

Reemplaza el placeholder mínimo previo por el scaffold canónico del
golden path rest-api/python (entry point para tier free-trial):

- code/app/main.py — FastAPI con /health (sin DB), /metrics, middleware
  correlation_id, settings Pydantic
- code/tests/ — pytest + httpx TestClient (sin testcontainers, sin Docker)
- helm/APP_NAME/ — chart minimal: Deployment, Service, IngressRoute,
  NetworkPolicy. SIN Job Alembic, SIN ServiceMonitor, SIN claim de BD
- coralware-shape.yaml — shapeVersion 1.0.0, minTier free-trial,
  promotionPath -> web-backend-python cuando se requiera persistencia
- .gitea/workflows/APP_NAME-build.yaml — invoca reusable workflow ADR-038
  + job helm-deploy con KUBECONFIG_TENANT_B64

Diferencias con web-backend/python: sin alembic, sin BD, sin
testcontainers, NetworkPolicy sin acceso a ns-addons.

Placeholders __APP_NAME__, __TIER__, __TENANT_ID__, __TENANT_ID_NODASHES__
serán sustituidos server-side por repo-provisioner.

El openspec/ del golden path NO se sincroniza al repo Gitea (gobernanza
interna de Coralware).

Refs: ADR-027 (Golden Paths), ADR-038 (CI), ADR-053 (referencia anatomía).

README.md

@@ -1,3 +1,100 @@
-# template-rest-api-python
+# __APP_NAME__ — REST API Python (FastAPI)
 
-Template Golden Path — REST API con Python (FastAPI)
+App generada desde el Golden Path **`rest-api/python`** de Coralware Cove IDP.
+
+Scaffold para API HTTP stateless en FastAPI. **Sin persistencia por
+diseño** — si tu app necesita base de datos, migra al shape
+`web-backend/python` (que incluye Alembic + MariaDB).
+
+> **Contrato del shape:** ver `coralware-shape.yaml`. Define los endpoints
+> obligatorios y la versión del shape. No elimines ese archivo — la
+> plataforma lo lee.
+
+---
+
+## Estructura
+
+```
+.
+├── coralware-shape.yaml          ← contrato con la plataforma
+├── catalog-info.yaml             ← entidad Backstage
+├── code/
+│   ├── app/main.py               ← FastAPI app
+│   ├── tests/                    ← pytest + httpx TestClient
+│   ├── pyproject.toml
+│   ├── requirements.txt
+│   └── Dockerfile
+├── helm/__APP_NAME__/            ← Helm chart minimal (sin hooks)
+└── .gitea/workflows/             ← CI: tests + build + deploy
+```
+
+---
+
+## Endpoints obligatorios
+
+| Path | Auth | Propósito |
+|------|------|-----------|
+| `/health` | none | Liveness + readiness; devuelve `{status: "ok"}` |
+| `/docs` | configurable | Swagger UI |
+| `/openapi.json` | configurable | Schema OpenAPI |
+| `/metrics` | restringido vía NetworkPolicy | Métricas Prometheus |
+
+---
+
+## Variables de entorno
+
+| Variable | Default | Descripción |
+|----------|---------|-------------|
+| `LOG_LEVEL` | `INFO` | `DEBUG` para troubleshooting |
+| `CORRELATION_ID_HEADER` | `X-Correlation-ID` | Header de trazabilidad |
+| `OPENAPI_REQUIRE_AUTH` | `false` | Activar JWT en `/docs` |
+| `KEYCLOAK_ISSUER` | — | URL del realm cuando auth activado |
+
+---
+
+## Desarrollo local
+
+```bash
+cd code
+pip install -r requirements-dev.txt
+uvicorn app.main:app --reload --port 8000
+```
+
+Probar:
+
+```bash
+curl http://localhost:8000/health
+curl http://localhost:8000/docs
+```
+
+---
+
+## Plan de salida
+
+Sin lock-in técnico:
+
+| Componente | Cómo lo exportas |
+|-----------|------------------|
+| Código | `git remote add github && git push github main` |
+| Imagen | `docker pull` desde Harbor + push a tu registry |
+| Manifests | Ya están en `helm/` — `helm template` genera YAML aplicable |
+
+---
+
+## Cuándo migrar a `web-backend/python`
+
+Si tu app empieza a:
+- Necesitar persistencia (base de datos relacional)
+- Usar migraciones de schema
+- Servir frontend estático en `/demo`
+- Manejar sesiones o estado entre requests
+
+→ migra al shape `web-backend/python` (un repo nuevo, un nuevo template).
+
+---
+
+## Referencias
+
+- `docs/adr-027-product-design-golden-paths.md` — Golden Paths Fase 5
+- `docs/adr-053-shape-web-backend-python.md` — anatomía de shapes (referencia)
+- `docs/adr-038-ci-cd-standardization.md` — pipeline Python