rsc-universal 0.1.1

package/skills/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/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

package/skills/replicate/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: replicate
+description: "Use when running, packaging, deploying or scaling a model on the Replicate platform from code — choosing blocking run vs async predictions, handling FileOutput, wiring deployments with warm/private endpoints and autoscaling, packaging with Cog, verifying webhooks, or cutting GPU spend. Triggers: 'run flux on Replicate from Python', 'my prediction takes 8 minutes and my request times out', 'keep an instance warm so users don't hit cold starts', 'cog push fails', 'verify the webhook came from Replicate', 'desplegar mi modelo en Replicate con endpoint privado', 'empaquetar mi modelo con Cog'. NOT crafting image prompts/params or picking image model families (that is replicate-images)."
+tags: [replicate, cog, deployments, webhooks, model-serving, gpu, ai-infra]
+recommends: [replicate-images, modal, runpod, huggingface, webhooks, cost-tracking, docker]
+origin: risco
+---
+
+# Replicate platform operations
+
+This skill is about **how a model runs in production on Replicate** — clients, async, deployments,
+Cog packaging, webhooks, scaling, and spend. It is the platform-engineering counterpart to image
+prompt craft. If the question is *what prompt, aspect ratio, or model family produces a good image*,
+that is `replicate-images`, not this skill. Here the mental model is: **a prediction is a job. You
+either wait for it, poll it, or get pinged about it — and where it runs (shared cold pool vs a private
+warm deployment) is a cost-and-latency dial you set deliberately.**
+
+Pinned facts (verified 2026-06-02): Python client `replicate` 1.x (latest 1.0.7), Python 3.8+;
+JS client `replicate` on npm; auth via `REPLICATE_API_TOKEN`. A `2.0.0aN` alpha exists on PyPI but
+is NOT the default — pin `replicate>=1,<2` so a fresh install never silently pulls it.
+
+## Decision: how should this model run?
+
+Pick the row by latency tolerance and whether your process can block. Do not default to `run()` for
+everything — a 10-minute job inside a web request will time out and burn a worker.
+
+| Pattern | Latency | Blocks your process? | Cost shape | Use when |
+|---|---|---|---|---|
+| `replicate.run(...)` | seconds | Yes — waits to completion | per-prediction, shared pool | interactive/quick calls, scripts, CLIs |
+| `predictions.create()` + poll | minutes | Yes, but you control the loop | per-prediction, shared pool | long job, a worker can babysit it |
+| `predictions.create(webhook=...)` | minutes+ | No — fire and forget | per-prediction, shared pool | long job, the request must return now |
+| Deployment (private endpoint) | low + steady | depends on call style above | warm floor + per-prediction | sustained traffic, need warm/private/autoscale cap |
+
+Rule: if a human or HTTP request is waiting longer than a few seconds, do not block on `run()` —
+switch to predictions + webhook. Why: synchronous timeouts kill the request but the GPU job keeps
+running and billing.
+
+## Auth & install
+
+```bash
+export REPLICATE_API_TOKEN=r8_...           # clients read this env var automatically
+pip install 'replicate>=1,<2'               # pin: 2.0.0aN is alpha; unpinned can pull it
+npm install replicate                        # Node client
+```
+
+Python 3.8+ is required. Never `pip install replicate` unpinned in a Dockerfile or requirements
+file — a rebuild months later can resolve to the 2.0 alpha and break your imports. Why: the alpha is
+a full Stainless/httpx rewrite with a different surface.
+
+## Run a model
+
+```python
+import replicate
+
+output = replicate.run(
+    "black-forest-labs/flux-schnell",
+    input={"prompt": "a red bicycle", "num_outputs": 1},
+)
+```
+
+Since client 1.0.0, file outputs come back as **`FileOutput`** objects, not URL strings. Treating one
+as a string is the single most common bug.
+
+```python
+# Bad — output[0] is a FileOutput, not a str; this writes the repr, not the bytes
+open("out.png", "w").write(output[0])
+
+# Good — read the bytes, or take the URL explicitly
+with open("out.png", "wb") as f:
+    f.write(output[0].read())          # bytes
+print(output[0].url)                    # hosted URL if you'd rather link
+```
+
+Rule: call `.read()` for bytes or `.url` for the link. Why: silently coercing a `FileOutput` to a
+string corrupts the file and the error surfaces far from the cause.
+
+## Long-running & async
+
+For jobs over a few seconds, create a prediction instead of blocking:
+
+```python
+client = replicate.Client()
+prediction = client.predictions.create(
+    model="owner/model",
+    input={"prompt": "..."},
+)
+prediction.reload()                      # refresh status from the API
+while prediction.status not in ("succeeded", "failed", "canceled"):
+    time.sleep(2)
+    prediction.reload()
+```
+
+Set a **deadline** so a stuck job auto-cancels instead of billing forever, and `cancel()` on cleanup
+paths. Why: a hung prediction with no deadline is silent, open-ended GPU spend. Poll with a small
+backoff, not a tight loop — you are charged for the prediction, not the polling, but a tight loop
+wastes your own process and rate budget. Full polling loop with backoff and 5xx handling is in
+`references/webhooks-and-async.md`.
+
+## Webhooks
+
+For fire-and-forget, hand Replicate a URL and filter to the events you care about:
+
+```python
+client.predictions.create(
+    model="owner/model",
+    input={"prompt": "..."},
+    webhook="https://your.app/hooks/replicate",
+    webhook_events_filter=["completed"],   # not every intermediate "logs" event
+)
+```
+
+Rule: ALWAYS verify the signature before trusting a webhook body. Why: the URL is public — anyone can
+POST forged completions to it. Replicate signs each delivery; the secret has a **`whsec_`** prefix.
+Reconstruct signed content as `{webhook-id}.{webhook-timestamp}.{body}`, HMAC-SHA256 with the
+base64-decoded secret, base64-encode, and constant-time compare against the `webhook-signature`
+header (a space-separated `v1,<sig>` list). The clients expose a verification helper; the full
+Python and Node recipe (including idempotency via `webhook-id`) is in
+`references/webhooks-and-async.md`.
+
+## Deployments
+
+A **deployment** is a private, dedicated API endpoint for one model version that autoscales from zero
+to hundreds of instances. Reach for it when you need warm instances, a private endpoint, or a hard
+spend cap — not for one-off runs.
+
+- `min_instances` — the **warm floor**. Set >0 to kill cold starts for latency-sensitive traffic;
+  every warm instance bills whether or not it serves a request.
+- `max_instances` — the **spend cap**. The ceiling on concurrent instances; protects you from a
+  traffic spike turning into a surprise bill.
+- Hardware (NVIDIA T4, A100, H100, ...) is switchable **without touching code** — change the
+  deployment config, not `predict.py`.
+- Rolling updates ship a new version with no downtime; built-in monitoring covers latency,
+  throughput, error rate, and GPU memory.
+
+You still call a deployment with `run()` / `predictions.create()` — it just routes to your private
+instances. Create/update via HTTP API, the clients, or CLI; fields and the rolling-update flow are in
+`references/deployments-api.md`.
+
+## Package a custom model with Cog
+
+Cog packages a model into a production container. You need two files; Replicate builds the API server
+for you on push.
+
+```yaml
+# cog.yaml
+build:
+  gpu: true
+  python_version: "3.11"
+  python_packages:
+    - "torch==2.4.0"
+predict: "predict.py:Predictor"
+```
+
+```python
+# predict.py
+from cog import BasePredictor, Input, Path
+
+class Predictor(BasePredictor):
+    def setup(self):
+        # load weights ONCE here, not per request
+        self.model = load_model("weights.pth")
+
+    def predict(self, prompt: str = Input(description="text prompt")) -> Path:
+        result = self.model(prompt)
+        return Path(result)            # Cog uploads the file
+```
+
+```bash
+cog predict -i prompt="hello"          # run locally (needs Docker)
+cog push r8.im/owner/model             # build + push; Replicate hosts it
+```
+
+Rule: load weights in `setup()`, never in `predict()`. Why: `setup()` runs once per instance;
+`predict()` runs every request — loading weights per request makes every call pay the model-load cost.
+Full `cog.yaml` (system packages, run steps), typed `Input(...)`, GPU config, version pinning, and
+common build failures are in `references/cog-packaging.md`. Building requires Docker.
+
+## Cost & scaling levers
+
+- **Scale to zero** is the default — idle deployments stop billing. Only raise `min_instances` above
+  zero when cold-start latency actually hurts users, and treat the warm floor as a line item.
+- **Deadlines** on predictions cap the worst case so a stuck job cannot bill open-ended.
+- **Right-size the GPU**: do not run a 1B model on an H100. Hardware is a deployment-config change.
+- **Cache weights in `setup()`** so per-request work is just inference.
+
+This skill covers Replicate-specific levers only. Tracking total AI spend across many providers as a
+discipline is `cost-tracking`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Treating a `FileOutput` as a URL string | Corrupts files / writes a repr; error surfaces far away | `.read()` for bytes, `.url` for the link |
+| Blocking `run()` for a 10-min job in a web request | Request times out; the GPU job keeps running and billing | `predictions.create(webhook=...)`, return now |
+| Webhook handler with no signature check | The URL is public; anyone can forge completions | Verify HMAC-SHA256 against `whsec_` secret |
+| High `min_instances` "just in case" | Every warm instance bills 24/7 idle | Scale to zero; raise floor only when cold starts hurt |
+| Loading weights inside `predict()` | Every request pays the model-load cost | Load once in `setup()` |
+| `pip install replicate` unpinned | A rebuild can pull the 2.0 alpha and break imports | Pin `replicate>=1,<2` |
+| A deployment for a one-off run | Pays for a private endpoint you call once | Use the shared pool via `run()` |
+| No deadline on a long prediction | A hung job bills open-ended, silently | Set a deadline; `cancel()` on cleanup |
+
+## References
+
+- `references/cog-packaging.md` — full `cog.yaml` + `predict.py`, GPU config, build/push, version pinning, build failures.
+- `references/webhooks-and-async.md` — signature verification (Python + Node), event filters, idempotency, polling with backoff, 5xx retries.
+- `references/deployments-api.md` — create/update/get deployment via HTTP + clients, autoscaling fields, rolling updates, monitoring metrics, CLI.
+
+`scripts/verify.sh` statically checks an emitted artifact dir: a `cog.yaml` declaring `build:` and
+`predict:`, a `predict.py` `Predictor` with `setup` + `predict`, and warns on an unpinned `replicate`
+dependency or a `FileOutput` written as a string. Presence + key checks only — it does not run Docker.

package/skills/replicate/evals/README.md

@@ -0,0 +1,9 @@
+# Evals — replicate
+
+`cases.yaml` is a trigger/routing and capability rubric, not an executable test of the Replicate API.
+`should_trigger` lists prompts (with a non-obvious symptom and a Spanish one) that must route here;
+`should_not_trigger` lists near-miss prompts that must route to a named sibling (`replicate-images`,
+`modal`, `runpod`, `webhooks`, `cost-tracking`) so the boundary stays sharp. The `capability` case is
+a scored rubric: feed the scenario to an agent loaded with this skill and check the response covers
+every `must_include` item. Run it through whatever eval harness scores the skills repo; no Replicate
+token, GPU, or network call is required to grade these.

package/skills/replicate/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: replicate
+
+should_trigger:
+  - prompt: "Run flux-schnell from my Python script and save the image to disk"
+    why: "Core run + FileOutput handling — the most common entry point."
+  - prompt: "My Replicate prediction takes 8 minutes and my web request keeps timing out"
+    why: "Non-obvious symptom that routes to async predictions + webhook, not blocking run()."
+  - prompt: "Package my fine-tuned PyTorch model with Cog and push it to Replicate"
+    why: "Cog packaging — cog.yaml + predict.py + cog push."
+  - prompt: "How do I keep an instance warm so users don't hit a cold start on Replicate?"
+    why: "Non-obvious phrasing for deployments min_instances / warm floor."
+  - prompt: "Desplegar mi propio modelo en Replicate con un endpoint privado y autoescalado"
+    why: "Spanish phrasing for a deployment with a private endpoint and autoscaling."
+  - prompt: "How do I verify a webhook actually came from Replicate before trusting it?"
+    why: "Signature verification with the whsec_ secret — a security-critical ops task."
+  - prompt: "cog push fails with a CUDA/torch mismatch — how do I fix the build?"
+    why: "Cog build troubleshooting, covered in the cog-packaging reference."
+
+should_not_trigger:
+  - prompt: "What prompt and aspect ratio give the best product photo on flux?"
+    route_to: replicate-images
+    why: "Image prompt/param craft, not platform operations."
+  - prompt: "Run my own arbitrary Python on a serverless GPU, not a packaged Replicate model"
+    route_to: modal
+    why: "General serverless GPU containers, not the Replicate platform."
+  - prompt: "Rent a raw GPU box by the hour to train a model"
+    route_to: runpod
+    why: "Raw rented GPU infrastructure, not Replicate model serving."
+  - prompt: "Design a generic webhook receiver with retries and dedupe for Stripe events"
+    route_to: webhooks
+    why: "Provider-agnostic webhook consumer design, unrelated to Replicate signing."
+  - prompt: "Track our total AI spend across OpenAI, Anthropic, and Replicate as a discipline"
+    route_to: cost-tracking
+    why: "Cross-provider spend tracking; this skill covers only Replicate-specific levers."
+
+capability:
+  - scenario: "A team has a custom PyTorch model and wants it on Replicate as a private, autoscaling endpoint that fires webhooks on completion, while controlling GPU cost."
+    must_include:
+      - "cog.yaml declaring both build (gpu/python_version/python_packages) and predict"
+      - "predict.py with a Predictor whose setup() loads weights once and a typed predict()"
+      - "cog push r8.im/owner/model to publish a version"
+      - "a deployment configured with min_instances and max_instances and a hardware choice"
+      - "predictions.create with webhook= plus webhook_events_filter, and signature verification against the whsec_ secret"
+      - "cost guidance: scale-to-zero default vs warm-floor trade-off, prediction deadlines, right-sizing the GPU"
+      - "pins replicate>=1,<2 and treats file output as FileOutput (.read()/.url), not a string"