@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/deployment/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: deployment
+description: "Use when taking an app from source to live: choosing the deploy target from requirements (Hetzner+Coolify vs Vercel vs a third), then wiring container → CI → registry → host with build secrets, healthchecks and rollback. NOT one platform's mechanics (that is `coolify`, `vercel`, `railway`, `render`), NOT the Dockerfile alone (that is `docker`)."
+tags: [deploy, docker, ci, github-actions, coolify]
+recommends: [secure-coding]
+origin: ai-hub
+---
+
+# Ship it — Docker, GitHub Actions, and a deploy target (Coolify · Vercel · Hetzner)
+
+Take any app in this repo from source → hardened container → green CI/CD → live on the right
+host, with secrets that never leak into image layers or logs, and a defined rollback path.
+
+```text
+source → Dockerfile (multi-stage) → CI (lint·test·build·scan) → registry (ghcr) → target (Coolify·Vercel·Hetzner, rolling) → live + rollback
+                                                                                     ▲
+                                                              choose via references/hosting-targets.md
+```
+
+**Out of scope — say so and stop:** Kubernetes / Helm / ECS / Nomad orchestration; cloud IaC
+(Terraform, Pulumi, CloudFormation — only the GHA↔cloud **OIDC handshake** is covered, not
+provisioning); application runtime code and DB schema/migration logic (the per-stack skills at the
+bottom own what runs *inside* the container).
+
+## Decision rules
+
+Consult these first. They settle 90% of choices before you write a line.
+
+**Table A — Base image by stack**
+
+| Stack | Base image | Notes |
+| --- | --- | --- |
+| FastAPI / Python | `gcr.io/distroless/python3-debian12:nonroot` (or `python:3.13-slim`) | UID 65532, no shell |
+| Go | `gcr.io/distroless/static-debian12:nonroot` | `CGO_ENABLED=0` static, ~10 MB |
+| Next.js | `node:24-bookworm-slim` | Active LTS; `output: "standalone"` |
+| Flutter web | `nginxinc/nginx-unprivileged:1.27-alpine` | static SPA + `try_files` fallback |
+| Postgres | `postgres:18-alpine` | managed/official — do NOT build a custom image |
+
+**Table B — Coolify build pack**
+
+| Situation | Pick |
+| --- | --- |
+| Repo has a Dockerfile | Dockerfile pack (always — CI/prod parity) |
+| No Dockerfile, standard stack | Nixpacks / Railpack |
+| Static SPA, no server | Static |
+| Multi-service local parity | Docker Compose |
+| CI already builds & pushes | Docker Image (deploy prebuilt ghcr image) |
+
+**If it has a Dockerfile, use the Dockerfile pack.**
+
+**Table C — Deploy strategy**
+
+| Change type | Strategy |
+| --- | --- |
+| Backward-compatible | Rolling (Coolify default, healthcheck-gated) |
+| Breaking / instant cutover / risky migration | Blue-green: two Coolify resources + domain swap |
+| Want gradual % traffic (canary) | Canary = release to a small subset, watch metrics, then ramp. Vanilla Coolify has no traffic split — emulate with feature flags (in-app % gating) or a blue-green pair behind a flagged path |
+
+**Table D — Secret delivery**
+
+| Secret kind | Mechanism |
+| --- | --- |
+| Build-time non-secret | `ARG` |
+| Build-time secret (private dep token) | BuildKit `--mount=type=secret` (NEVER `ARG`) |
+| Runtime secret | Coolify env (Is Secret) / GHA `secrets` |
+| Cloud auth | OIDC — never a stored key |
+
+## Docker — the canonical multi-stage shape
+
+One process per container: no supervisord-managed bundles, let the orchestrator scale.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+# ---- builder: full toolchain, deps cached before source ----
+FROM <builder-base> AS builder
+WORKDIR /app
+COPY <lockfile> <manifest> ./           # lockfile FIRST → cached dep layer
+RUN <install-deps-from-lockfile>        # changes only when the lockfile changes
+COPY . .                                # source last
+RUN <build>
+
+# ---- runtime: minimal, non-root, no toolchain ----
+FROM <runtime-base>                      # distroless / -slim / unprivileged nginx
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /app/<artifact> ./
+USER nonroot:nonroot
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["<readiness-probe>"]             # exec-form (distroless has no shell)
+CMD ["<entrypoint>", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+```dockerfile
+# GOOD: secret consumed in-layer, never persisted
+RUN --mount=type=secret,id=npm_token \
+    NPM_TOKEN="$(cat /run/secrets/npm_token)" npm ci
+# BAD: ARG bakes the token into image history forever
+ARG NPM_TOKEN
+RUN npm ci   # token now visible in `docker history`
+```
+
+```text
+# .dockerignore — write this before your first build
+.git
+node_modules
+.env*
+dist
+.next
+__pycache__
+*.log
+coverage
+Dockerfile*
+compose*
+README.md
+.github
+```
+
+```bash
+DOCKER_BUILDKIT=1 docker build --secret id=npm_token,env=NPM_TOKEN -t app:dev .
+```
+
+→ full per-stack Dockerfiles: `references/dockerfiles-by-stack.md` · image-authoring depth
+(shrinking, base-image choice, cache busting): `../docker/SKILL.md`
+
+## docker-compose for local dev + Postgres
+
+```yaml
+# compose.yaml — Compose Spec, no `version:` key
+services:
+  app:
+    build:
+      context: .
+      target: dev                       # dev stage of the multi-stage Dockerfile
+    ports:
+      - "127.0.0.1:8000:8000"
+    volumes:
+      - .:/app                          # bind mount → hot reload
+      - /app/.venv                      # anonymous volume guards container deps
+    environment:
+      DATABASE_URL: postgres://postgres:postgres@db:5432/app_dev
+    develop:
+      watch:
+        - { path: ./pyproject.toml, action: rebuild }
+        - { path: ./app, action: sync, target: /app/app }
+    depends_on:
+      db:
+        condition: service_healthy
+  db:
+    image: postgres:18-alpine
+    ports:
+      - "127.0.0.1:5432:5432"           # host-only; NEVER 0.0.0.0 in prod
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app_dev
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d app_dev"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+- GOOD: bind-mount source for dev hot reload; BAD: bind-mount source over a prod image (it shadows the baked build).
+- GOOD: bind Postgres to `127.0.0.1`; BAD: bind it to `0.0.0.0` in prod (publicly reachable DB).
+
+→ prod overlay + mailpit: `references/dockerfiles-by-stack.md`
+
+## GitHub Actions — least-privilege pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read                        # default-deny; escalate per job
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/verify.sh
+  build-push:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=sha
+            type=semver,pattern={{version}}
+      - uses: docker/build-push-action@v7
+        with:
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: true
+      - uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # v0.35.0
+        with:
+          image-ref: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
+          exit-code: "1"
+          severity: "HIGH,CRITICAL"
+          ignore-unfixed: true
+```
+
+- GOOD: scoped per-job `permissions` (only `build-push` gets `packages: write` / `id-token: write`).
+- BAD: blanket `permissions: write-all` — any compromised step can push images or mint tokens.
+- GOOD: third-party actions pinned to a full commit SHA with a version comment (`@<sha> # v0.35.0`). In the March 2026 `trivy-action` supply-chain incident ([GHSA-69fq-xp46-6x23](https://github.com/aquasecurity/trivy/security/advisories/GHSA-69fq-xp46-6x23) / CVE-2026-33634), 76 of 77 tags were force-pushed to credential-stealing malware; the advisory's named known-safe ref is `v0.35.0` (commit `57a97c7e7821a5776cebc9bb87c984fa69cba8f1`), the one clean tag still pointing at the real `master` HEAD. A moving tag would have pulled the malware; this SHA pin does not. Let Dependabot bump the SHA once upstream re-tags cleanly.
+
+→ matrix, reusable workflows, OIDC-to-cloud, environments/approvals, releases: `references/github-actions.md` ·
+workflow-syntax depth: `../github-actions/SKILL.md`
+
+## Choosing a deploy target (3 options)
+
+Never recommend a single host. **Gather requirements → recommend exactly three targets with
+trade-offs**, so the choice is made with eyes open. The canonical slate:
+
+1. **Hetzner VPS + Coolify** — cheapest control, EU residency, sustained/always-on/stateful;
+   you own ops. (The combo `references/coolify.md` runs on; see below.)
+2. **Vercel** — zero-ops serverless/edge, ideal Next.js, scales to zero for spiky traffic;
+   metered cost climbs at sustained scale, US-default region.
+3. **A third that fits the case's sharpest constraint** — Railway (tiny/simple, predictable
+   bill), Fly.io (true global edge, 30+ regions), or a hyperscaler (enterprise compliance).
+
+Requirements to gather first: expected total/concurrent users · traffic shape (steady vs
+spiky) · budget ceiling · data region/residency & compliance · team ops comfort · scaling
+needs (scale-to-zero, global latency) · stateful needs (own DB/queue/websockets).
+
+**Quick steer:** Next.js + spiky traffic + ops-averse → Vercel. Cost-sensitive / EU-resident /
+sustained / own stateful services → Hetzner+Coolify. The Dockerfile this skill produces is the
+escape hatch — start on Vercel, move to Hetzner+Coolify when the bill grows, same artifact.
+
+→ deep coverage (limits, regions, pricing, decision matrix, worked examples): `references/hosting-targets.md`
+
+## Coolify — wiring the chosen target
+
+Only the parts that touch the pipeline; the platform walkthrough lives elsewhere.
+
+- Pick the **Dockerfile** build pack when a Dockerfile exists — same artifact CI builds, full control, prod/CI parity.
+- Set **Ports Exposes** to the container port your app listens on (e.g. `8000`); Traefik routes the domain to it.
+- Set the **Health Check** path/port → this is what gates the rolling swap to the new container.
+- Mark sensitive env vars **Is Secret** — encrypted at rest, masked in logs and UI.
+- Enable **GitHub App auto-deploy** on push, OR call the deploy webhook from CI (one or the other, not both).
+- **Rollback** = redeploy a previously stored image in one click; pair with backward-compatible migrations.
+
+```bash
+curl --fail -X POST \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  "https://coolify.example.com/api/v1/deploy?uuid=$APP_UUID&force=false"
+```
+
+→ persistent storage, custom domains + Let's Encrypt, per-PR previews, CPU/memory limits, blue-green:
+`references/coolify.md` and `../coolify/SKILL.md`
+
+## Secrets flow (GitHub → registry → Coolify)
+
+```text
+GitHub secrets / OIDC ──mint short-lived creds──▶ build pushes to ghcr.io (no key stored)
+     │                                                        │
+     └──── nothing long-lived in a workflow file             ▼
+                                       Coolify pulls (deploy-scoped registry cred)
+                                                     │
+                                                     ▼
+                                runtime env injected by Coolify (encrypted at rest)
+```
+
+- A secret crosses **at most one** trust boundary per hop — never forward a GHA secret into the running container; let Coolify inject runtime env.
+- Nothing long-lived lives in a workflow file: `GITHUB_TOKEN` and OIDC tokens are minted per run and expire.
+- `${{ }}` secrets are masked in logs, but `set -x` and `echo "$SECRET"` defeat the mask — forbid both.
+
+## 12-factor config & observability
+
+Config from env, validated at boot, fail-fast — a bad config crashes on startup, never at request
+time. Idiom per stack: pydantic-settings `BaseSettings` (raises at import), zod `envSchema.parse(process.env)`
+(throws at boot), `env.Must(env.ParseAs[Config]())` for Go (exits at boot).
+
+Log JSON to stdout (slog for Go, structlog/uvicorn JSON for FastAPI, pino for Next.js); never log
+secrets; expose `/healthz` (liveness, no deps) + `/readyz` (checks deps).
+
+```python
+# FastAPI: liveness is dependency-free; readiness probes the DB so a node that
+# can't reach Postgres never takes traffic during the rolling swap.
+@app.get("/healthz")
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+@app.get("/readyz")
+async def readyz() -> dict[str, str]:
+    await db.execute("SELECT 1")   # raises 500 if the DB is unreachable
+    return {"status": "ready"}
+```
+
+## Anti-patterns — rationalizations → STOP
+
+| Rationalization | STOP — do this instead |
+| --- | --- |
+| `:latest` is fine for now | Pin tag+digest (`FROM img@sha256:…`); `:latest` breaks reproducibility and rollback |
+| I'll pass the token as `ARG` | BuildKit `--mount=type=secret`; `ARG` persists in `docker history` |
+| `permissions: write-all` is simpler | Default-deny; grant per job (`packages: write`, `id-token: write`) |
+| Store a registry password in GHA secrets | Use OIDC / `GITHUB_TOKEN`; no long-lived key |
+| Run as root, it's just a container | Non-root UID + read-only rootfs + `cap_drop: ALL` (add back only `NET_BIND_SERVICE` to bind <1024) |
+| Skip the healthcheck, the app boots fast | No healthcheck = no rolling gate = downtime / bad version live |
+| Copy the whole repo then `RUN install` | Copy the lockfile first; cache the deps layer |
+| Nixpacks is easier than my Dockerfile | If a Dockerfile exists, use it — CI/prod parity |
+| Secrets in `compose.yaml` env | `.env` (gitignored) / Coolify secret env |
+| Migrate the DB destructively in deploy | Backward-compatible migrations, or rolling breaks |
+| `echo $SECRET` to debug CI | Never; masked vars still leak via `set -x` and logs |
+| Build once per env with different secrets | Build one image; inject config at runtime (12-factor) |
+
+## Quick reference
+
+| Task | Command / file |
+| --- | --- |
+| Build with secret | `DOCKER_BUILDKIT=1 docker build --secret id=npm_token,env=NPM_TOKEN -t app:dev .` |
+| Scan image | `trivy image --severity HIGH,CRITICAL --exit-code 1 IMG` |
+| Lint Dockerfile | `hadolint Dockerfile` |
+| Lint workflows | `actionlint` |
+| Run verify gate | `bash scripts/verify.sh` (hadolint+actionlint+trivy+build smoke, local and CI) |
+| Local up | `docker compose up --watch` |
+| Trigger Coolify deploy | `curl --fail -X POST …/api/v1/deploy?uuid=…&force=false` |
+| Roll back | Coolify → redeploy prior image |
+
+**Pre-ship checklist**
+
+- [ ] Runs as non-root
+- [ ] Base image pinned (tag + digest)
+- [ ] `.dockerignore` present
+- [ ] `HEALTHCHECK` hits a real readiness path
+- [ ] No secrets in layers or logs
+- [ ] Least-privilege `GITHUB_TOKEN`
+- [ ] trivy clean (no HIGH/CRITICAL)
+- [ ] Rollback path known
+
+## Project grounding (02-DOCS)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/deployment.md` first and stay consistent with it. Create or update it with this
+project's real choices — base-image/container choices, the CI pipeline, the target config, the
+secrets flow, the rollback strategy — index it in `02-DOCS/wiki/index.md` (the Knowledge map root
+`CLAUDE.md` points to), and bump its `Updated` date in the same change. No `02-DOCS/` layer? Skip
+silently (optionally suggest `harness`) — technical conventions are *recorded, not gated*; never
+block the task on this.
+
+## Hand off
+
+- Platform mechanics once the target is chosen: `../coolify/SKILL.md`, `../vercel/SKILL.md`, `../railway/SKILL.md`, `../render/SKILL.md`, `../fly-io/SKILL.md`, `../hetzner/SKILL.md`.
+- `../secure-coding/SKILL.md` — input validation, authn/z, and secret-handling this skill assumes the app already does.
+- `../harness/SKILL.md` — 01-TOOLS provider creds (Stripe, Postgres, OAuth…) that become runtime env on the target.
+- `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md` — the application code that runs inside the container; this skill stops at that boundary.

package/skills/shared/deployment/evals/README.md

@@ -0,0 +1,50 @@
+# Eval harness — `deployment`
+
+This is an **agent-run** eval, not a shell script. You drive a Claude Code agent and judge
+its behavior against `cases.yaml`. Two things are measured: **triggering** (does the skill
+fire on the right prompts and stay silent on near-misses) and **capability** (does loading the
+skill measurably improve the answer).
+
+## Setup
+
+- `cases.yaml` defines `should_trigger`, `should_not_trigger`, and `capability` blocks.
+- "Load the skill" = make `skills/deployment/SKILL.md` (and its `references/`) available to the
+  agent. "Without the skill" = the same agent with no deployment skill in context.
+- Run each prompt in a fresh session (no carryover between cases).
+
+## A. Triggering
+
+For trigger tests, load the **full catalog** of skills (deployment + all siblings: fastapi,
+nextjs, go, postgresdb, flutter, design, marketing, presentations, course-storytelling,
+building-agents, secure-coding, harness, init) so routing is realistic.
+
+1. For each `should_trigger` prompt: feed it to the agent, run **3–5 trials**.
+   - PASS if the agent invokes the `deployment` skill.
+2. For each `should_not_trigger` prompt: run **3–5 trials**.
+   - PASS if `deployment` does **not** fire. If `route_to` names a sibling, confirm the agent
+     routes there (or asks to); if `route_to: none`, confirm it declines / calls it out of scope.
+3. Record fires / trials per prompt.
+
+**Pass bar:** ≥90% trigger accuracy across all trials — i.e. `should_trigger` fires ≥90% of
+the time AND `should_not_trigger` fires deployment <10% of the time. A near-miss leaking into
+deployment is a harder failure than a missed trigger; investigate any leak.
+
+## B. Capability
+
+For each `capability` scenario, run the agent **twice**: once **with** the skill loaded, once
+**without**. Grade each output against that scenario's `must_include` checklist (one point per
+checkable item, scored by a human or a judge agent).
+
+1. Score = covered items / total `must_include` items.
+2. **Pass bar:** with the skill ≥80% covered; AND the with-skill score beats the without-skill
+   score by a clear margin (the skill must *measurably* improve the answer — if both score the
+   same, the skill is adding no value on that scenario).
+3. Spot-check that the with-skill answer follows the skill's hard rules (non-root, secrets via
+   BuildKit not ARG, default-deny `GITHUB_TOKEN`, SHA-pinned actions, three hosting options).
+
+## Reporting
+
+For each run, capture: per-prompt fire rate, the routing target on near-misses, and the
+with/without capability scores. The eval passes when **both** bars (A and B) are met. These are
+judgment calls made by an agent/human reviewer — note any borderline cases rather than hiding
+them; honest near-misses are more useful than a green checkmark.

package/skills/shared/deployment/evals/cases.yaml

@@ -0,0 +1,53 @@
+skill: deployment
+
+should_trigger:
+  - prompt: "Write a Dockerfile for my FastAPI service and a GitHub Actions workflow that lints, tests, scans the image, and pushes it to ghcr."
+    why: "Core scope: authoring a multi-stage Dockerfile plus a least-privilege GHA build/test/scan/push pipeline — exactly the source→container→CI→registry path this skill owns."
+  - prompt: "We're paying too much on Vercel for our Next.js app. Where should we move it to cut the bill while keeping deploys easy?"
+    why: "Hosting-decision question (Vercel vs Hetzner+Coolify vs a third option) is explicitly the 'where should I host this' / decision-matrix scope, including the start-on-Vercel-move-to-Coolify escape hatch."
+  - prompt: "How do I get a private npm token into my Docker build without it ending up in the image history?"
+    why: "Doesn't name the skill or 'Docker' as a topic per se, but this is the BuildKit --mount=type=secret vs ARG decision — a signature build-secrets concern of this skill."
+  - prompt: "Set up zero-downtime deploys for my service on our self-hosted PaaS, with a healthcheck that gates the swap and a way to roll back fast."
+    why: "Rolling/blue-green strategy, healthcheck-gated swap, and rollback path on Coolify-class hosting — squarely the deploy-target wiring this skill covers, even though 'Coolify' isn't named."
+  - prompt: "My GitHub Actions workflow uses permissions: write-all and stores a registry password as a secret. Can you harden it?"
+    why: "Least-privilege GITHUB_TOKEN (default-deny, per-job escalation) plus replacing a long-lived registry key with OIDC/GITHUB_TOKEN — both are explicit hardening targets of this skill."
+  - prompt: "Can you give me a compose file so I can run my app plus Postgres locally with hot reload?"
+    why: "docker-compose for local dev with a Postgres service, host-only port binding, and watch/hot-reload is an explicit 'When to use' item (compose.yaml authoring)."
+  - prompt: "Ship it — the app's ready, I just need it live somewhere with CI doing the build."
+    why: "'Ship it' is a named trigger phrase; the under-specified deploy + CI build intent is exactly what this skill operationalizes (and it will gather hosting requirements)."
+
+should_not_trigger:
+  - prompt: "Write the SQLAlchemy migration to add a nullable email_verified column and backfill it."
+    route_to: "postgresdb"
+    why: "DB schema/migration logic is application/data-layer work; this skill explicitly defers runtime/migration logic to the per-stack/DB skills and stops at the container boundary."
+  - prompt: "Add a rate limiter and validate the JWT on my FastAPI auth endpoints before they hit the handler."
+    route_to: "secure-coding"
+    why: "Input validation and authn/z hardening is secure-coding's domain; this skill assumes the app already does this and does not author runtime auth code."
+  - prompt: "Convert my Docker Compose stack to a Kubernetes Helm chart with an HPA and an ingress."
+    route_to: "none"
+    why: "Kubernetes/Helm orchestration is explicitly out of scope ('say so and stop'); no sibling covers it, so it should not route into deployment."
+  - prompt: "Build my Next.js page that streams server components and add the data-fetching layer for the dashboard."
+    route_to: "nextjs"
+    why: "Application runtime code for the Next.js stack — the nextjs skill owns code that runs inside the container; deployment only containerizes/ships it."
+  - prompt: "Provision a Hetzner server, VPC, and firewall rules using Terraform."
+    route_to: "none"
+    why: "Cloud IaC (Terraform/Pulumi/CloudFormation) provisioning is explicitly out of scope; only the GHA↔cloud OIDC handshake is covered, not infrastructure provisioning."
+
+capability:
+  - scenario: "Dockerize a FastAPI app and add a GitHub Actions pipeline that builds, tests, scans, and pushes to ghcr with no long-lived secrets."
+    must_include:
+      - "Multi-stage Dockerfile: full-toolchain builder stage + minimal runtime stage (distroless python3 or python:3.13-slim), never shipping the build toolchain"
+      - "Lockfile + manifest copied and deps installed BEFORE copying source, so source edits don't bust the dependency cache layer"
+      - "Runs as non-root (USER nonroot / UID 65532) and includes a HEALTHCHECK hitting a real readiness path like /readyz, not /"
+      - "A .dockerignore (excluding .git, .env*, __pycache__, etc.) written before the first build"
+      - "GHA workflow with top-level permissions: contents: read (default-deny) and per-job escalation (packages: write, id-token: write) only on build-push"
+      - "Pushes to ghcr.io using GITHUB_TOKEN/OIDC (no stored registry password) and runs a trivy image scan failing on HIGH/CRITICAL"
+      - "Third-party actions pinned to a commit SHA (not a moving tag) and a verify/lint+test gate before build"
+  - scenario: "User asks where to host a steady-traffic, EU-resident SaaS with its own Postgres and websockets, on a tight budget."
+    must_include:
+      - "Gathers requirements first: traffic shape (steady vs spiky), concurrent users, budget ceiling, data region/residency & compliance, ops comfort, stateful needs"
+      - "Recommends exactly THREE targets with trade-offs rather than a single host"
+      - "Names Hetzner VPS + Coolify as the fit for cost-sensitive / EU-resident / sustained / self-hosted-stateful workloads"
+      - "Names Vercel as the zero-ops serverless/edge option (best for Next.js + spiky, scale-to-zero) and notes its cost climbs at sustained scale / US-default region"
+      - "Offers a fitting third option (e.g. Railway for simple/predictable, Fly.io for global edge, or a hyperscaler for enterprise compliance)"
+      - "Notes the Dockerfile is the portability escape hatch — same artifact lets you move hosts later"