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

package/skills/shared/render/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: render
+description: "Use when deploying or fixing an app on Render — web services, background workers, cron jobs, private services, managed Postgres and Key-Value, and especially the render.yaml Blueprint. Covers deploys that fail with no open ports detected, 502s on first deploy, free-tier cold starts, and a free Postgres about to expire with its data. NOT the generic ship and release flow (that is `deployment`), NOT another PaaS such as `railway` or `fly-io`."
+tags: [render, paas, deployment, render-yaml, cron, background-worker, infrastructure-as-code]
+recommends: [deployment, postgresdb, docker, domains-dns, github-actions, scaling]
+origin: ai-hub
+---
+
+# Render — make this repo deploy correctly, wired as code
+
+Take any repo and make it deploy on **Render** (render.com) in one pass: pick the right
+service type, declare everything in a version-controlled `render.yaml` Blueprint, bind the
+port the way Render expects, and wire `DATABASE_URL` / secrets across services so they
+survive rotation. Steer clear of the four traps that eat first deploys: the
+"no open ports detected" 502, the free-tier spin-down, the 30-day free-Postgres expiry,
+and the 12-hour cron kill.
+
+```text
+pick service type → render.yaml at repo root → bind 0.0.0.0:$PORT → wire env across services → push (auto-deploy)
+        │                                                                                            │
+   web|worker|cron|pserv|static|keyvalue                                       full key surface → references/blueprint-reference.md
+```
+
+Facts here are dated to **2026-06-02** against render.com/docs. Render ships changes; if a
+key or limit looks off, confirm against the live Blueprint spec before betting a deploy on it.
+
+## The one decision that decides everything: service type
+
+Pick the type **before** you write a line of YAML. The type sets the billing model, whether
+the process gets a public URL, and whether Render expects it to bind a port. Choosing wrong
+means a worker that never starts because Render waited for a port, or a 12-hour job that dies
+silently as a cron.
+
+| The process… | Type | `runtime` required? | Gets a public URL? |
+| --- | --- | --- | --- |
+| serves HTTP/WebSocket traffic | `web` | yes | yes |
+| runs forever, no inbound URL (queue consumer, Celery) | `worker` | yes | no |
+| runs, does work, exits — on a schedule | `cron` | yes | no |
+| internal-only API, reachable only inside Render's network | `pserv` | yes | no (internal host only) |
+| pre-built static assets (SPA, docs) | `web` + `runtime: static` | yes (`static`) | yes |
+| cache / queue / Redis-compatible store | `keyvalue` | **no** | no (internal) |
+
+`runtime` enum (everything except `keyvalue`): `node`, `python`, `docker`, `image`,
+`static`, `go`, `ruby`, `elixir`, `rust`.
+
+## Blueprint-first: everything lives in render.yaml
+
+**Rule: declare every service, database, and env var group in `render.yaml` at the repo
+root. Touch the dashboard only for `sync: false` secrets and one-off debugging.** Why: the
+Blueprint is the reproducible, reviewable source of truth — it powers preview environments
+and a clean re-deploy, while dashboard-only config is invisible state that drifts and can't
+be code-reviewed.
+
+Top-level keys: `services`, `databases`, `envVarGroups`, `projects`, `previews`.
+
+## Minimal correct render.yaml (annotated)
+
+A multi-service app — a Node web service, a Python worker, a nightly cron, a Postgres db,
+and a shared env group. Every load-bearing key is commented.
+
+```yaml
+databases:
+  - name: app-db
+    plan: starter            # NOT free for anything you care about — free expires in 30 days
+    postgresMajorVersion: "17"
+    region: frankfurt
+
+envVarGroups:
+  - name: app-shared
+    envVars:
+      - key: LOG_LEVEL
+        value: info
+      - key: SENTRY_DSN
+        sync: false          # prompt once at setup; never stored in git
+
+services:
+  - type: web
+    name: api
+    runtime: node
+    region: frankfurt
+    plan: starter            # $7/mo — avoids the free-tier 15-min spin-down on an API
+    buildCommand: npm ci && npm run build
+    startCommand: npm start  # MUST bind 0.0.0.0 and read $PORT — see next section
+    healthCheckPath: /healthz # gates zero-downtime rollout; new instance must pass first
+    preDeployCommand: npm run migrate  # runs before the new instance serves traffic
+    autoDeployTrigger: commit          # commit | checksPass | off
+    envVars:
+      - fromGroup: app-shared
+      - key: DATABASE_URL
+        fromDatabase:
+          name: app-db
+          property: connectionString   # never hardcode the URL
+      - key: SESSION_SECRET
+        generateValue: true            # Render generates a random secret
+
+  - type: worker
+    name: jobs
+    runtime: python
+    plan: starter
+    buildCommand: pip install -r requirements.txt
+    startCommand: celery -A app worker -l info  # no port — workers don't bind one
+    envVars:
+      - fromGroup: app-shared
+      - key: DATABASE_URL
+        fromDatabase: { name: app-db, property: connectionString }
+      - key: API_URL
+        fromService:                   # reference another service
+          name: api
+          type: web
+          property: hostport
+
+  - type: cron
+    name: nightly-cleanup
+    runtime: python
+    schedule: "0 3 * * *"              # required for cron; 03:00 UTC daily
+    buildCommand: pip install -r requirements.txt
+    startCommand: python -m app.cleanup
+    envVars:
+      - key: DATABASE_URL
+        fromDatabase: { name: app-db, property: connectionString }
+```
+
+## Port binding — do this first (the #1 first-deploy failure)
+
+**Rule: a `web` service MUST listen on host `0.0.0.0` and read the `PORT` env var (Render
+sets it, default `10000`).** If Render detects no bound port within its window, the deploy
+**fails with "no open ports detected"** and visitors get a **502**. This is the single most
+common first-deploy break — binding `localhost`/`127.0.0.1` or a hardcoded port does it.
+
+```javascript
+// Bad — binds the wrong host and ignores Render's PORT → "no open ports detected"
+app.listen(3000);
+
+// Good — bind 0.0.0.0 and honor $PORT
+app.listen(process.env.PORT || 3000, "0.0.0.0");
+```
+
+```bash
+# Bad — gunicorn on a fixed local port
+gunicorn app:app --bind 127.0.0.1:8000
+
+# Good — bind 0.0.0.0 and Render's $PORT
+gunicorn app:app --bind 0.0.0.0:$PORT
+```
+
+Only `web` services need this. A `worker`/`cron` that tries to bind a port is fine but
+pointless; a `web` service that doesn't is broken.
+
+## Wiring env vars across services
+
+**Rule: never hardcode `DATABASE_URL`, `REDIS_URL`, or shared secrets as literal `value:`
+strings. Reference the resource** so the value survives a rotation, recreate, or region
+move, and so secrets never land in git.
+
+| Form | Use it for |
+| --- | --- |
+| `fromDatabase: { name, property: connectionString }` | the Postgres connection string |
+| `fromService: { name, type, property }` | another service's host/port/URL (`property: hostport`, `host`, or `port`) |
+| `fromGroup: <group-name>` | pull a whole shared env var group |
+| `generateValue: true` | a random secret Render generates and stores (session keys) |
+| `sync: false` | a secret you type once at setup; not stored in the repo |
+
+For a Key Value store, reference its connection string the same way you reference Postgres,
+via `fromService` against the `keyvalue` service.
+
+## Migrations and zero-downtime deploys
+
+- `preDeployCommand` — runs **once**, before the new instance starts serving traffic. Put
+  migrations here, not in `startCommand` (a startCommand migration runs on every instance
+  and races under multiple replicas).
+- `healthCheckPath` — Render polls it on the new instance and only shifts traffic once it
+  passes, giving zero-downtime rollout. Point it at a route that checks real readiness.
+- `autoDeployTrigger` — `commit` (deploy every push), `checksPass` (wait for CI status),
+  or `off` (manual / deploy-hook only).
+
+## Free-tier traps
+
+Render's free tier is generous for hobby work and a landmine for anything you care about.
+
+| Trap | What happens | Fix |
+| --- | --- | --- |
+| Free web spin-down | after **15 min** of no inbound traffic the instance sleeps; next request waits **30–60s** to wake | Starter at **$7/mo** per service |
+| 750 free instance-hrs/mo | shared across the workspace; spun-down time doesn't count toward it | budget it, or pay Starter |
+| Free Postgres expiry | **deleted 30 days after creation** (14-day grace to upgrade), all data gone; only **one** free Postgres per workspace | Starter Postgres ($7/mo) from day one for anything real |
+| Free Key Value | no disk persistence — data is lost on restart | paid plan if you need durability |
+
+## Cron specifics
+
+- `schedule:` (standard cron expression) is **required** for `type: cron`.
+- Render guarantees **at most one active run at a time** — runs don't overlap.
+- **A run is killed after 12 hours.** Anything that can exceed that must be a `worker` with
+  its own scheduler/queue, not a cron. A long cron fails silently mid-job — partial work,
+  no clean error.
+
+## Scaling and disk knobs
+
+This is the concrete Render surface, not capacity strategy (that's `scaling`).
+
+```yaml
+services:
+  - type: web
+    name: api
+    runtime: node
+    scaling:
+      minInstances: 1
+      maxInstances: 4
+      targetCPUPercent: 70
+      targetMemoryPercent: 80   # autoscale between min/max on CPU/mem
+    disk:
+      name: data
+      mountPath: /var/data
+      sizeGB: 10                # a disk PINS the service to ONE instance — blocks horizontal scale
+```
+
+Use `numInstances` for a fixed replica count instead of `scaling` when you don't want
+autoscaling. A persistent `disk` and horizontal scaling are mutually exclusive — pick one.
+
+Regions: `oregon`, `ohio`, `virginia`, `frankfurt`, `singapore`. Plans: `free`, `starter`,
+`standard`, `pro`, `pro plus`, `pro max`, `pro ultra`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Hardcoding a port (`listen(3000)`) | "no open ports detected" → deploy fails / 502 | bind `0.0.0.0` and `$PORT` |
+| Hardcoding `DATABASE_URL` | breaks on rotation / db recreate | `fromDatabase` reference |
+| A long job as a `cron` | killed at 12h, silent partial work | `worker` + its own scheduler/queue |
+| Free Postgres for production | deleted 30 days after creation | Starter ($7/mo) from day one |
+| Secrets as literal `value:` in render.yaml | leaked in git history | `sync: false` or `generateValue: true` |
+| Migrations in `startCommand` | runs on every instance, races under replicas | `preDeployCommand` |
+| Free web service for a real API | cold-start 502s after idle | Starter, or accept it only for a hobby toy |
+| Dashboard-only config | invisible drift, no preview envs, no review | declare in `render.yaml` |
+
+## When to hand off
+
+- Schema design, queries, indexing, tuning → `../postgresdb/SKILL.md`. This skill only
+  *provisions and connects* Render's managed Postgres.
+- Writing the `Dockerfile` Render consumes via `runtime: docker` → `docker`.
+- Registrar-side DNS records for a custom domain → `domains-dns`. (The Render `domains:`
+  block and verification stay here.)
+- Cross-platform release strategy, promotion, rollback flow → `../deployment/SKILL.md` and
+  `ship`. This skill is Render config and platform mechanics.
+- Build steps Render's native build doesn't run (custom CI) → `github-actions`. Render
+  auto-deploys on push; only reach for Actions when you genuinely need it.
+- Capacity/load strategy beyond the `scaling:` knobs → `scaling`.
+- A different PaaS → its own sibling: `../fly-io/SKILL.md`, `railway`, `vercel`,
+  `../netlify/SKILL.md`, `coolify`, `digitalocean`.
+
+## Full key surface
+
+The exhaustive `render.yaml` key tables per service type, all database keys
+(`postgresMajorVersion`, `diskSizeGB`, `readReplicas`, `highAvailability`, `previewPlan`),
+every env-var reference form, region/plan enums, and four complete copy-paste recipes
+(Next.js web+pg; FastAPI web+worker+cron+keyvalue; Docker monorepo with `rootDir`; static
+SPA with `routes` rewrites) live in `references/blueprint-reference.md` — pull it open when
+you need a key this body didn't cover.

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

@@ -0,0 +1,12 @@
+# render evals
+
+These cases are routing-and-capability fixtures, not an automated test runner. Feed
+`cases.yaml` through the repo's eval harness, which uses an LLM judge. `should_trigger`
+and `should_not_trigger` check that the SKILL.md `description` routes the right prompts in
+(Render deploys, render.yaml authoring, the port/502/cron/free-tier traps) and the wrong
+ones out to the named sibling (`fly-io`, `docker`, `deployment`, `postgresdb`,
+`domains-dns`). The `capability` case is graded against its `must_include` rubric to confirm
+the SKILL.md body actually produces a correct, trap-free `render.yaml` — right service
+types, `0.0.0.0:$PORT` binding, referenced (not hardcoded) env vars, and the cron/Postgres
+warnings. There is nothing to `npm test` here; the judge reads SKILL.md and scores the
+output against the rubric.

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

@@ -0,0 +1,45 @@
+skill: render
+
+should_trigger:
+  - prompt: "Write a render.yaml that deploys my Express API plus a background worker and a Postgres database."
+    why: "Core Blueprint authoring across multiple service types (web + worker + Postgres) — the central job this skill owns."
+  - prompt: "My Render deploy keeps failing with 'no open ports detected'. What's wrong?"
+    why: "Non-obvious symptom phrasing that maps directly to the port-binding trap (must bind 0.0.0.0:$PORT) — the #1 first-deploy failure this skill leads with."
+  - prompt: "How do I run a nightly cleanup job on Render?"
+    why: "Service-type selection: a scheduled run-and-exit job is a `type: cron` with a `schedule:`, not a worker — a decision this skill teaches without naming the type."
+  - prompt: "Wire DATABASE_URL from my Render Postgres into both my web service and my worker without hardcoding it."
+    why: "Cross-service env reference via fromDatabase — the wiring rule (never hardcode the URL) is a signature concern of this skill."
+  - prompt: "Mi web service en Render devuelve 502 después del primer deploy, ¿qué pasa?"
+    why: "Spanish trigger; first-deploy 502 is the port-binding / no-open-ports symptom this skill diagnoses."
+  - prompt: "Should this email-sending job be a Render worker or a cron job?"
+    why: "Non-obvious worker-vs-cron boundary; the answer hinges on the 12h cron kill and run-then-exit semantics, both core to this skill."
+  - prompt: "Why does my free Render service take 30 seconds to respond after no one's hit it for a while?"
+    why: "Free-tier spin-down / cold-start trap described by symptom, not by name — squarely a free-tier mechanic this skill explains."
+
+should_not_trigger:
+  - prompt: "Deploy this app to Fly.io with a Dockerfile and set up volumes."
+    route_to: "fly-io"
+    why: "A different PaaS — Fly.io has its own config surface and sibling skill; this skill is Render-specific."
+  - prompt: "Write the Dockerfile for my Node app with a small multi-stage runtime image."
+    route_to: "docker"
+    why: "Container authoring. Render only consumes a Dockerfile via runtime: docker; writing it is docker's job."
+  - prompt: "Design our blue/green release and rollback strategy across staging and production."
+    route_to: "deployment"
+    why: "Platform-agnostic release flow and promotion strategy belongs to deployment; this skill is Render config and mechanics."
+  - prompt: "Optimize this slow Postgres query and add the right indexes."
+    route_to: "postgresdb"
+    why: "Schema and query tuning is postgresdb; this skill only provisions and connects Render's managed Postgres."
+  - prompt: "Point my custom domain's DNS A and CNAME records at the host at my registrar."
+    route_to: "domains-dns"
+    why: "Registrar-side DNS records belong to domains-dns; only the Render domains: block stays here."
+
+capability:
+  - scenario: "Given a Python FastAPI repo with a Celery worker and a job that must email users every 5 minutes, produce a render.yaml and fix the start command so it deploys correctly on Render."
+    must_include:
+      - "Web service binds 0.0.0.0 and reads $PORT (e.g. gunicorn/uvicorn --bind 0.0.0.0:$PORT), not a hardcoded port"
+      - "The Celery process declared as type: worker (no port binding)"
+      - "The 5-minute email job declared as type: cron with a schedule: expression (e.g. */5 * * * *)"
+      - "DATABASE_URL wired via fromDatabase (and Redis via fromService), never a hardcoded connection string"
+      - "Secrets handled with sync: false or generateValue: true rather than literal value: strings"
+      - "Migrations placed in preDeployCommand, not startCommand"
+      - "Calls out the 12h cron kill (use a worker for longer jobs) and the free-Postgres 30-day expiry trap"

package/skills/shared/render/references/blueprint-reference.md

@@ -0,0 +1,203 @@
+# render.yaml — full key reference and recipes
+
+The exhaustive Blueprint surface. Dated 2026-06-02 against render.com/docs/blueprint-spec.
+Pull the key you need; copy a recipe and adapt.
+
+## Top-level keys
+
+| Key | What |
+| --- | --- |
+| `services` | every web / pserv / worker / cron / keyvalue service |
+| `databases` | managed Postgres instances |
+| `envVarGroups` | named, reusable env var bundles shared across services |
+| `projects` | group services into a Render project |
+| `previews` | preview-environment config (`generation: automatic \| manual \| off`) |
+
+## Common service keys (web / pserv / worker / cron)
+
+| Key | Notes |
+| --- | --- |
+| `type` | `web` \| `pserv` \| `worker` \| `cron` \| `keyvalue` |
+| `name` | unique within the workspace |
+| `runtime` | `node` \| `python` \| `docker` \| `image` \| `static` \| `go` \| `ruby` \| `elixir` \| `rust` (required except `keyvalue`) |
+| `region` | `oregon` \| `ohio` \| `virginia` \| `frankfurt` \| `singapore` |
+| `plan` | `free` \| `starter` \| `standard` \| `pro` \| `pro plus` \| `pro max` \| `pro ultra` |
+| `buildCommand` | build step (native runtimes) |
+| `startCommand` | process entrypoint |
+| `preDeployCommand` | runs once before the new instance serves traffic — migrations |
+| `healthCheckPath` | path Render polls to gate zero-downtime rollout (web only) |
+| `autoDeployTrigger` | `commit` \| `checksPass` \| `off` |
+| `numInstances` | fixed replica count |
+| `scaling` | `{ minInstances, maxInstances, targetCPUPercent, targetMemoryPercent }` |
+| `disk` | `{ name, mountPath, sizeGB }` — pins to a single instance |
+| `rootDir` | subdirectory to treat as the build root (monorepos) |
+| `buildFilter` | `{ paths, ignoredPaths }` — only deploy when matching files change |
+| `envVars` | env var list (see reference forms below) |
+
+### Docker-runtime keys
+
+| Key | Notes |
+| --- | --- |
+| `runtime: docker` | build from a Dockerfile in the repo |
+| `dockerfilePath` | path to the Dockerfile (e.g. `./apps/api/Dockerfile`) |
+| `dockerContext` | build context directory |
+| `runtime: image` | deploy a prebuilt image — `image: { url, creds }` |
+
+### Static-site keys (`runtime: static`)
+
+| Key | Notes |
+| --- | --- |
+| `staticPublishPath` | directory of built assets (e.g. `dist`, `build`, `out`) |
+| `routes` | rewrite/redirect rules: `{ type: rewrite \| redirect, source, destination }` |
+| `headers` | `{ path, name, value }` custom response headers |
+
+### Cron-only keys
+
+| Key | Notes |
+| --- | --- |
+| `schedule` | **required** cron expression; run killed after 12h; one active run at a time |
+
+## envVars reference forms
+
+| Form | Resolves to |
+| --- | --- |
+| `{ key, value }` | a literal (avoid for secrets) |
+| `{ key, sync: false }` | typed once at setup, not stored in the repo |
+| `{ key, generateValue: true }` | random secret Render generates and stores |
+| `{ key, fromDatabase: { name, property } }` | `property`: `connectionString`, `host`, `port`, `user`, `password`, `database` |
+| `{ key, fromService: { name, type, property } }` | `property`: `hostport`, `host`, `port` (and for keyvalue, `connectionString`) |
+| `{ fromGroup: <name> }` | pull a whole env var group |
+
+## Database keys (`databases:`)
+
+| Key | Notes |
+| --- | --- |
+| `name` | unique name |
+| `plan` | `free` (expires 30 days after creation, 14-day grace, one per workspace) \| `starter` \| `standard` \| … |
+| `postgresMajorVersion` | e.g. `"17"` |
+| `region` | same enum as services |
+| `diskSizeGB` | storage size |
+| `databaseName` / `user` | optional explicit names |
+| `readReplicas` | `[{ name }]` read-replica list |
+| `highAvailability` | `{ enabled: true }` (paid) |
+| `previewPlan` | plan used for preview-env databases |
+| `ipAllowList` | `[{ source, description }]` — `0.0.0.0/0` for public, omit for internal-only |
+
+## Recipe 1 — Next.js web + Postgres
+
+```yaml
+databases:
+  - name: web-db
+    plan: starter
+    postgresMajorVersion: "17"
+
+services:
+  - type: web
+    name: nextjs-app
+    runtime: node
+    plan: starter
+    buildCommand: npm ci && npm run build
+    startCommand: npm start           # next start binds 0.0.0.0:$PORT by default
+    healthCheckPath: /api/health
+    preDeployCommand: npx prisma migrate deploy
+    envVars:
+      - key: DATABASE_URL
+        fromDatabase: { name: web-db, property: connectionString }
+      - key: NEXTAUTH_SECRET
+        generateValue: true
+      - key: NODE_ENV
+        value: production
+```
+
+## Recipe 2 — FastAPI web + worker + cron + Key Value
+
+```yaml
+databases:
+  - name: api-db
+    plan: starter
+    postgresMajorVersion: "17"
+
+services:
+  - type: keyvalue
+    name: cache
+    plan: starter
+    ipAllowList: []                   # internal only
+
+  - type: web
+    name: api
+    runtime: python
+    plan: starter
+    buildCommand: pip install -r requirements.txt
+    startCommand: gunicorn -k uvicorn.workers.UvicornWorker app.main:app --bind 0.0.0.0:$PORT
+    healthCheckPath: /health
+    preDeployCommand: alembic upgrade head
+    envVars:
+      - key: DATABASE_URL
+        fromDatabase: { name: api-db, property: connectionString }
+      - key: REDIS_URL
+        fromService: { name: cache, type: keyvalue, property: connectionString }
+
+  - type: worker
+    name: tasks
+    runtime: python
+    plan: starter
+    buildCommand: pip install -r requirements.txt
+    startCommand: celery -A app.worker worker -l info
+    envVars:
+      - key: DATABASE_URL
+        fromDatabase: { name: api-db, property: connectionString }
+      - key: REDIS_URL
+        fromService: { name: cache, type: keyvalue, property: connectionString }
+
+  - type: cron
+    name: send-digest
+    runtime: python
+    schedule: "*/5 * * * *"           # every 5 minutes
+    buildCommand: pip install -r requirements.txt
+    startCommand: python -m app.jobs.digest
+    envVars:
+      - key: DATABASE_URL
+        fromDatabase: { name: api-db, property: connectionString }
+```
+
+## Recipe 3 — Docker monorepo (rootDir + dockerfilePath + buildFilter)
+
+```yaml
+services:
+  - type: web
+    name: api
+    runtime: docker
+    rootDir: apps/api
+    dockerfilePath: apps/api/Dockerfile
+    buildFilter:
+      paths:
+        - apps/api/**
+        - packages/shared/**          # only redeploy when these change
+    plan: starter
+    healthCheckPath: /healthz
+    envVars:
+      - key: PORT
+        value: "10000"                # your Dockerfile CMD must bind 0.0.0.0:$PORT
+```
+
+## Recipe 4 — static SPA with rewrites and headers
+
+```yaml
+services:
+  - type: web
+    name: spa
+    runtime: static
+    buildCommand: npm ci && npm run build
+    staticPublishPath: dist
+    routes:
+      - type: rewrite
+        source: /*
+        destination: /index.html      # SPA fallback so client routing works
+    headers:
+      - path: /*
+        name: X-Frame-Options
+        value: DENY
+      - path: /assets/*
+        name: Cache-Control
+        value: public, max-age=31536000, immutable
+```

package/skills/shared/render/scripts/verify.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# verify.sh — lint every render.yaml Blueprint in a target directory against the
+# correctness rules that cause real Render deploy failures. Read-only: parses YAML,
+# checks rules, prints findings. No network, no Render account.
+#
+# Usage:
+#   bash scripts/verify.sh [TARGET_DIR]   # default: current directory
+#
+# Checks per service:
+#   - has `name` and a valid `type` (web|pserv|worker|cron|keyvalue)
+#   - `runtime` present for every non-keyvalue service and is a valid enum
+#   - `schedule` present iff `type: cron`
+#   - `plan` / `region` (if set) are valid enums
+#   - WARN if a `web` service `startCommand` hardcodes a numeric port without $PORT
+#
+# Exit codes: 0 = clean OR no render.yaml found (never a false failure);
+#             1 = at least one hard error. Warnings never fail the run.
+#
+# Portable to macOS bash 3.2 and CI bash 5. NO_COLOR=1 disables color.
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -n "${NO_COLOR:-}" ] || [ ! -t 1 ]; then
+  RED=""; YEL=""; GRN=""; RST=""
+else
+  RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Discover render.yaml / render.yml files. No matches -> clean exit 0.
+FILES=""
+while IFS= read -r f; do
+  FILES="$FILES$f
+"
+done < <(find "$TARGET" -type f \( -name 'render.yaml' -o -name 'render.yml' \) 2>/dev/null)
+
+if [ -z "${FILES%$'\n'}" ]; then
+  echo "${GRN}OK${RST} no render.yaml found under '$TARGET' — nothing to verify."
+  exit 0
+fi
+
+ERRORS=0
+
+if have python3; then
+  while IFS= read -r FILE; do
+    [ -z "$FILE" ] && continue
+    echo "→ $FILE"
+    OUT="$(
+      RENDER_FILE="$FILE" python3 - <<'PY'
+import os, sys
+try:
+    import yaml
+except Exception:
+    print("WARN\tPyYAML not installed; skipped deep checks (heuristics only)")
+    sys.exit(3)
+
+path = os.environ["RENDER_FILE"]
+try:
+    with open(path) as fh:
+        doc = yaml.safe_load(fh) or {}
+except Exception as e:
+    print(f"ERROR\tYAML parse failed: {e}")
+    sys.exit(0)
+
+VALID_TYPE = {"web", "pserv", "worker", "cron", "keyvalue"}
+VALID_RUNTIME = {"node","python","docker","image","static","go","ruby","elixir","rust"}
+VALID_PLAN = {"free","starter","standard","pro","pro plus","pro max","pro ultra"}
+VALID_REGION = {"oregon","ohio","virginia","frankfurt","singapore"}
+
+services = doc.get("services") or []
+if not isinstance(services, list):
+    print("ERROR\t`services` must be a list")
+    services = []
+
+for i, svc in enumerate(services):
+    if not isinstance(svc, dict):
+        print(f"ERROR\tservices[{i}] is not a mapping")
+        continue
+    label = svc.get("name") or f"services[{i}]"
+    stype = svc.get("type")
+
+    if not svc.get("name"):
+        print(f"ERROR\t{label}: missing `name`")
+    if stype not in VALID_TYPE:
+        print(f"ERROR\t{label}: invalid/missing `type` ({stype!r}); expected one of {sorted(VALID_TYPE)}")
+
+    if stype != "keyvalue":
+        rt = svc.get("runtime")
+        if not rt:
+            print(f"ERROR\t{label}: missing `runtime` (required for type {stype!r})")
+        elif rt not in VALID_RUNTIME:
+            print(f"ERROR\t{label}: invalid `runtime` ({rt!r})")
+
+    if stype == "cron" and not svc.get("schedule"):
+        print(f"ERROR\t{label}: type cron requires a `schedule:`")
+    if stype and stype != "cron" and svc.get("schedule"):
+        print(f"WARN\t{label}: `schedule:` is only used by type cron; ignored here")
+
+    plan = svc.get("plan")
+    if plan is not None and plan not in VALID_PLAN:
+        print(f"ERROR\t{label}: invalid `plan` ({plan!r})")
+    region = svc.get("region")
+    if region is not None and region not in VALID_REGION:
+        print(f"ERROR\t{label}: invalid `region` ({region!r})")
+
+    if stype == "web":
+        cmd = str(svc.get("startCommand") or "")
+        import re
+        if cmd and "$PORT" not in cmd and "${PORT}" not in cmd and re.search(r":\d{2,5}\b", cmd):
+            print(f"WARN\t{label}: web startCommand looks like it hardcodes a port without $PORT — Render may report 'no open ports detected'")
+
+dbs = doc.get("databases") or []
+if not isinstance(dbs, list):
+    print("ERROR\t`databases` must be a list")
+    dbs = []
+for i, db in enumerate(dbs):
+    if isinstance(db, dict) and db.get("plan") == "free":
+        print(f"WARN\tdatabase {db.get('name', i)!r}: free Postgres is deleted 30 days after creation — use starter for production")
+PY
+    )" || true
+
+    # Surface findings; count hard errors.
+    if [ -n "$OUT" ]; then
+      while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        case "$line" in
+          ERROR*) echo "  ${RED}${line}${RST}"; ERRORS=$((ERRORS + 1)) ;;
+          WARN*)  echo "  ${YEL}${line}${RST}" ;;
+          *)      echo "  $line" ;;
+        esac
+      done <<EOF
+$OUT
+EOF
+    else
+      echo "  ${GRN}OK${RST}"
+    fi
+  done <<EOF
+$FILES
+EOF
+else
+  # No python3: fall back to a shallow grep-based sanity pass (heuristic only).
+  echo "${YEL}WARN${RST} python3 not found — running shallow grep checks only."
+  while IFS= read -r FILE; do
+    [ -z "$FILE" ] && continue
+    echo "→ $FILE"
+    if grep -Eq '^\s*type:\s*cron' "$FILE" && ! grep -Eq '^\s*schedule:' "$FILE"; then
+      echo "  ${RED}ERROR\ta cron service appears to be missing a schedule:${RST}"
+      ERRORS=$((ERRORS + 1))
+    fi
+    if grep -Eq 'startCommand:.*:[0-9]{2,5}\b' "$FILE" && ! grep -q '\$PORT' "$FILE"; then
+      echo "  ${YEL}WARN\tstartCommand may hardcode a port without \$PORT${RST}"
+    fi
+    echo "  ${GRN}OK${RST} (shallow)"
+  done <<EOF
+$FILES
+EOF
+fi
+
+echo
+if [ "$ERRORS" -gt 0 ]; then
+  echo "${RED}FAIL${RST} $ERRORS error(s) found."
+  exit 1
+fi
+echo "${GRN}PASS${RST} render.yaml checks clean."
+exit 0