rsc-universal 0.1.1

package/skills/coolify/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: coolify
+
+should_trigger:
+  - prompt: "Install Coolify on my fresh Ubuntu 24.04 VPS and deploy my app from a GitHub repo."
+    why: "Core install + Git deploy path: install one-liner as root, first-admin lockdown, build-pack + source wiring."
+  - prompt: "My Vercel bill exploded this month. I want to move everything onto a box I own and pay a flat rate instead. How do I set that up?"
+    why: "Non-obvious cost/sovereignty trigger — user never says Coolify, but 'box I own + flat rate' instead of a metered PaaS is exactly the own-the-box value prop."
+  - prompt: "Set up nightly Postgres backups to Cloudflare R2 for the database I run in Coolify."
+    why: "In-product scheduled backup to S3-compatible storage (R2) with cron — a named core capability, including the restore-drill rule."
+  - prompt: "Montar mi propio PaaS en un VPS barato con Coolify y desplegar varias apps con SSL automático."
+    why: "Spanish trigger; self-hosting your own PaaS on a cheap VPS with multiple apps and automatic SSL is squarely this skill."
+  - prompt: "Vull autoallotjar les meves apps amb Coolify i una base de dades gestionada al meu servidor."
+    why: "Catalan trigger; self-hosting apps + a managed database on your own server is the provision-and-connect core."
+  - prompt: "I already have a server running. I just want a self-hosted control plane to manage my deploys, env vars and SSL certs from one dashboard."
+    why: "Non-obvious 'control plane on my own server' phrasing — the box exists, the user wants the orchestration layer, which is precisely what Coolify is."
+
+should_not_trigger:
+  - prompt: "Which Hetzner plan should I pick and how do I harden SSH and the firewall on the box itself?"
+    route_to: "hetzner"
+    why: "VPS hardware sizing + OS/SSH/firewall hardening is the box layer, not the control plane Coolify runs on."
+  - prompt: "Help me write a multi-stage Dockerfile and optimize my image layer caching."
+    route_to: "docker"
+    why: "Generic Docker image authoring — Coolify runs images but doesn't teach how to author/optimize them."
+  - prompt: "I just want a managed PaaS where I git push and they run it — I don't want to own or maintain any server."
+    route_to: "railway"
+    why: "Push-and-forget managed PaaS is the exact inverse of Coolify's own-the-box premise."
+  - prompt: "My Postgres query is doing a seq scan and is slow — which index should I add?"
+    route_to: "postgresdb"
+    why: "SQL/index/query tuning is engine-level work; Coolify only provisions and backs up the DB, it doesn't tune it."
+  - prompt: "Set up the A record and nameservers for my domain at the registrar."
+    route_to: "domains-dns"
+    why: "DNS records / registrar / propagation is the domains-dns layer; Coolify consumes the resolved hostname, it doesn't manage DNS."
+
+capability:
+  - scenario: "Stand up Coolify on a fresh Ubuntu 24.04 VPS, deploy a Next.js app from a GitHub repo with a managed Postgres, and configure nightly backups to S3-compatible storage with a custom domain + automatic SSL."
+    must_include:
+      - "Runs the install one-liner (curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash) AS ROOT, noting non-root is not fully supported"
+      - "Calls out first-admin lockdown: register at http://<ip>:8000 immediately because the first account permanently owns the instance"
+      - "Gives the port/firewall matrix: 8000 (and 6001/6002) restricted to the operator, 80/443 public"
+      - "Picks a build pack (Nixpacks default) and connects the GitHub source with a branch"
+      - "Sets app secrets as Coolify env vars / secrets injected at runtime, never baked into the image or committed"
+      - "Provisions managed Postgres and connects the app over the INTERNAL Docker hostname, with the DB port NOT publicly exposed"
+      - "Ensures the database has a named volume so data survives recreate, and the service has a healthcheck"
+      - "Adds the custom domain and gets automatic Let's Encrypt SSL via the Traefik proxy on 80/443"
+      - "Configures the S3 backup destination + cron schedule + retention AND an explicit restore-test/drill step"
+      - "Acknowledges the boundary that VPS sizing/firewall/SSH hardening is hetzner/digitalocean, not this skill"

package/skills/coolify/references/databases-and-backups.md

@@ -0,0 +1,99 @@
+# Managed databases & backups — deep dive
+
+Source facts: coolify.io/docs/databases/backups and database docs, accessed 2026-06-02.
+
+Coolify provisions Postgres, MySQL, MariaDB, MongoDB, Redis (and more) in-product with generated
+credentials. This skill provisions and backs up; SQL/schema/tuning is the `postgresdb` skill; backup
+strategy/RPO/RTO doctrine across systems is the `backups` skill. Here we wire the concrete in-product job.
+
+## Connection wiring
+
+Each managed database gets an **internal Docker network hostname** (the service name Coolify assigns).
+Connect apps to it over that private hostname — never a public IP.
+
+```text
+# GOOD — app env var points at the internal hostname on the private network:
+DATABASE_URL=postgres://<user>:<password>@<internal-db-hostname>:5432/<db>
+
+# Inject <password> as a Coolify secret, not a committed literal.
+```
+
+Do **not** enable the database's "public port" toggle unless an external client genuinely needs it. An
+open 5432/3306/27017/6379 is scanned within minutes. If you must expose it, bind deliberately and firewall
+to known source IPs at the cloud layer.
+
+**Every database service needs a named volume.** Recreating a service with only an anonymous volume wipes
+the data — the most common Coolify data-loss incident. Coolify's managed DBs set this up; verify it before
+trusting the instance with real data.
+
+## Scheduled backups
+
+Coolify runs the engine's native dump on a cron expression, stores it locally, and optionally pushes to
+S3-compatible storage.
+
+| Engine | Dump command Coolify runs | Restore = |
+| --- | --- | --- |
+| PostgreSQL | `pg_dump` | download → decompress → `psql`/`pg_restore` replay |
+| MySQL / MariaDB | `mysqldump` | download → decompress → `mysql <` replay |
+| MongoDB | `mongodump` | download → `mongorestore` |
+
+Configure per database:
+
+1. **Enable scheduled backup** on the resource.
+2. **Cron schedule** — e.g. `0 3 * * *` nightly 03:00; `0 */6 * * *` every 6h. Match to your tolerable
+   data loss (RPO).
+3. **Retention** — keep N copies/days so storage doesn't grow unbounded.
+4. **Destination** — local only, or local + an S3-compatible target (below).
+
+## S3-compatible destinations
+
+Add these as Coolify storage destinations. Provide endpoint + region + bucket + access key/secret — always
+as Coolify secrets, never in a committed file.
+
+| Provider | Endpoint shape | Notes |
+| --- | --- | --- |
+| AWS S3 | `s3.<region>.amazonaws.com` | Standard region + bucket |
+| Cloudflare R2 | `https://<accountid>.r2.cloudflarestorage.com` | Region usually `auto`; zero egress fees |
+| Backblaze B2 | `https://s3.<region>.backblazeb2.com` | S3-compatible endpoint, cheap storage |
+| MinIO (self-hosted) | `https://minio.example.com` | Your own object store; force path-style if needed |
+| Wasabi | `https://s3.<region>.wasabisys.com` | Flat-rate storage |
+
+Off-box storage is the entire point: a dump sitting on the same disk as the database dies with the disk.
+
+## The restore runbook — run it before you need it
+
+A backup you have never restored is a guess. Do this once now, and on a recurring drill.
+
+```bash
+# 1. Pull the latest dump from the destination (UI download, or via the S3 client).
+#    e.g. from R2/B2/MinIO/S3 with the AWS CLI pointed at the endpoint:
+aws --endpoint-url "$S3_ENDPOINT" s3 cp "s3://$BUCKET/<path>/dump.sql.gz" ./dump.sql.gz
+
+# 2. Decompress.
+gunzip dump.sql.gz
+
+# 3. Replay into a THROWAWAY database (never the live one during a drill).
+#    Postgres:
+psql "postgres://user:pass@host:5432/restore_test" < dump.sql
+#    MySQL/MariaDB:
+mysql -h host -u user -p restore_test < dump.sql
+#    MongoDB (from a mongodump archive/dir):
+mongorestore --uri "mongodb://user:pass@host:27017/restore_test" ./dump
+
+# 4. VERIFY: compare row counts / key tables against production expectations.
+#    e.g. Postgres:
+psql "postgres://.../restore_test" -c "SELECT count(*) FROM orders;"
+
+# 5. Drop the throwaway DB. Record the drill date in 02-DOCS/wiki/stack/coolify.md.
+```
+
+## Consistency caveats
+
+- These dumps are **logical, point-in-time snapshots at dump start**, not continuous PITR. Between dumps,
+  writes are unprotected — size the cron to your RPO.
+- For true point-in-time recovery (WAL archiving / continuous replication) you need engine-level setup
+  beyond Coolify's scheduled dump — that is `postgresdb` / `backups` territory.
+- For a large/active database, a logical dump can take time and add load; schedule it off-peak and watch
+  that the dump window doesn't overlap the next one.
+- Test restores against the **same major engine version**; cross-version replays can fail or silently
+  change behavior.

package/skills/coolify/references/deploy-recipes.md

@@ -0,0 +1,105 @@
+# Deploy recipes — build packs & a lint-clean compose
+
+Source facts: Coolify GitHub + v4.1 release notes, accessed 2026-06-02.
+
+## Build-pack decision
+
+| Build pack | Reach for it when | Trade-off |
+| --- | --- | --- |
+| **Nixpacks** (default) | Standard app; want zero config | Auto-detects runtime; least control over the build |
+| **Railpack** (v4.1, beta) | Need build-time env vars, config merge, or multi-stage control Nixpacks can't express | Newer/beta; expect rougher edges than Nixpacks |
+| **Dockerfile** | You already have (or want to own) the build | You maintain the Dockerfile; pin the base image |
+| **docker-compose** | Multi-service app deployed as one unit | You own the compose — keep it lint-clean (below) |
+
+Start with Nixpacks. Escalate to Railpack only when a build-time env var or multi-stage step is required.
+Drop to a Dockerfile when you need full control of the build. Use compose when one deploy is several
+services. For image-authoring depth (multi-stage layering, cache mounts) that is the `docker` skill.
+
+## Git source & env
+
+1. Connect the Git provider (GitHub/GitLab app, or a deploy key) and pick the branch.
+2. Enable auto-deploy on push, or trigger the deploy from CI (that's the `github-actions` skill).
+3. Set every secret as a **Coolify environment variable / secret**, injected at runtime. Never bake a
+   secret into the image and never commit it to the compose — a baked secret ships in every layer.
+4. Add a **named volume** for any path that must survive a redeploy (uploads, sqlite, caches you care
+   about). Anonymous volumes are wiped on recreate.
+5. Add the domain (`app.example.com`), point its A record at the box (`domains-dns`), and Traefik issues
+   the Let's Encrypt cert automatically on 80/443.
+
+## A worked, lint-clean compose (the verify.sh target)
+
+This is the shape `scripts/verify.sh` asserts: secrets are env-refs (no literals), every DB has a named
+volume, services have a `healthcheck:`, and the build-context app does not float on `:latest`. Coolify
+injects the `${...}` values from its secrets store.
+
+```yaml
+# docker-compose.yml — GOOD: env-ref secrets, named volume, healthchecks, pinned db image.
+services:
+  web:
+    build:
+      context: .            # build-context service: pinned via the Dockerfile's FROM, not :latest here
+    restart: unless-stopped
+    environment:
+      # Secrets are REFERENCES, injected by Coolify — never literals committed to git.
+      DATABASE_URL: ${DATABASE_URL}
+      APP_SECRET: ${APP_SECRET}
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    labels:
+      # Coolify/Traefik routing + auto-SSL is wired from the UI domain field; labels shown for reference.
+      - "traefik.enable=true"
+
+  db:
+    image: postgres:16          # pinned major tag, not :latest
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}   # env-ref, injected by Coolify
+    volumes:
+      - pgdata:/var/lib/postgresql/data         # NAMED volume — survives recreate
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    # NOTE: no `ports:` mapping — db is reached over the internal network, not exposed publicly.
+
+volumes:
+  pgdata:                        # declared named volume
+```
+
+```yaml
+# BAD — every line here is a verify.sh failure or a production incident:
+services:
+  web:
+    image: myapp:latest                 # floating tag — irreproducible redeploys
+    environment:
+      DATABASE_URL: postgres://app:hunter2@db:5432/app   # hardcoded secret literal in git
+    # no healthcheck
+  db:
+    image: postgres:latest              # floating tag
+    environment:
+      POSTGRES_PASSWORD: hunter2         # hardcoded secret literal
+    ports:
+      - "5432:5432"                     # DB port exposed to the public internet
+    # no volume — data is wiped on every recreate
+```
+
+## Why each rule earns its place
+
+- **Pinned image** — `:latest` silently changes the base; a redeploy you can't reproduce is a redeploy you
+  can't roll back.
+- **Named volume on the DB** — recreate without it and the data is gone. This is the top Coolify footgun.
+- **Healthcheck** — Coolify/Traefik use it to know when the container is actually ready; without it,
+  traffic hits a half-started app and `depends_on: service_healthy` can't gate startup.
+- **Env-ref secrets** — a literal in the compose leaks in git history and image layers. Inject from
+  Coolify's secret store.
+- **No public DB port** — reach the database over the internal hostname; an exposed port is scanned in
+  minutes.

package/skills/coolify/references/install-and-proxy.md

@@ -0,0 +1,80 @@
+# Install & proxy — deep dive
+
+Source facts: coolify.io/docs/get-started/installation and proxy docs, accessed 2026-06-02. Coolify 4.x.
+
+## Full install transcript (Ubuntu 22.04/24.04 LTS)
+
+```bash
+# Provision the box first (hetzner / digitalocean). Floor: 2 CPU / 2 GB / 30 GB.
+# Comfortable multi-app production: 4 vCPU / 8 GB / 100 GB NVMe. Coolify idles ~1 GB RAM.
+
+ssh root@<server-ip>            # root required; non-root is not fully supported
+
+# Optional sanity: confirm OS + free disk before install
+cat /etc/os-release
+df -h /
+
+# Install (downloads + runs the official script; installs Docker + Coolify's own stack)
+curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
+# Some docs show `| sudo bash` when piping; on a root shell `| bash` is correct.
+```
+
+The script takes ~2–5 minutes. When it finishes it prints the dashboard URL: `http://<server-ip>:8000`.
+
+### Claim the admin account (do this immediately)
+
+Open `http://<server-ip>:8000` and register. The **first** account created becomes the permanent root
+admin of the instance — there is no later ownership-claim or admin-invite recovery flow. Until you
+register, anyone who can reach `:8000` can take the instance. Do not pause between the install finishing
+and this step.
+
+After registering, in the dashboard:
+
+1. Settings → Instance: set the **FQDN** (e.g. `coolify.example.com`) and enable **force HTTPS** so the
+   dashboard itself gets a Let's Encrypt cert and you stop using the raw `:8000` IP.
+2. Point the dashboard FQDN's DNS A record at the box (DNS records are the `domains-dns` skill).
+
+## Other OS / non-LTS notes
+
+- **Ubuntu non-LTS** (e.g. interim releases): supported but the installer may need manual Docker repo
+  steps — install Docker Engine first, then re-run the Coolify script.
+- **Debian / Fedora / AlmaLinux / Rocky / CentOS / SUSE / Arch / Alpine**: supported. On distros where the
+  script can't add the Docker repo automatically, install Docker Engine via the distro's official method,
+  then run the Coolify script.
+- **Raspberry Pi OS**: 64-bit only.
+- General rule: if the one-liner fails partway, the usual cause is Docker not installing cleanly. Install
+  Docker by hand, verify `docker run --rm hello-world`, then re-run the Coolify script (it is idempotent).
+
+## Proxy: Traefik (default) vs Caddy
+
+Coolify ships **Traefik** as the default reverse proxy and can use **Caddy** instead. The proxy owns ports
+80/443, routes hostnames to containers, and provisions Let's Encrypt certificates automatically.
+
+- **Traefik (default)**: keep it unless you have a specific reason. Most templates and docs assume it.
+- **Caddy**: switch in Settings → Proxy if you prefer Caddy's config model. Don't switch mid-flight on a
+  busy instance without a maintenance window — the proxy restarts.
+
+You rarely hand-edit proxy config; Coolify generates labels/routes from each resource's domain settings.
+For a per-resource custom rule, use the resource's "Custom Traefik/Caddy labels" field rather than editing
+the proxy container directly (your edit would be overwritten on regeneration).
+
+## Wildcard domain + DNS-01 challenge
+
+For `*.apps.example.com` (one cert for many subdomains) Let's Encrypt requires the **DNS-01** challenge,
+which needs API access to your DNS provider so the proxy can create the `_acme-challenge` TXT record.
+
+1. Create a scoped DNS API token at your provider (Cloudflare, etc.).
+2. Configure the DNS provider + token in the proxy/ACME settings.
+3. Request the wildcard cert. The HTTP-01 challenge (the default for single hosts) cannot issue wildcards.
+
+Single-host certs use HTTP-01 and need only port 80 reachable + the A record pointing at the box.
+
+## Common SSL failures and fixes
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Cert never issues, "connection refused" in ACME logs | Port 80 not reachable from the internet | Open 80 at the cloud firewall; HTTP-01 needs it even for HTTPS-only sites |
+| "DNS problem: NXDOMAIN" | A record missing or not propagated | Confirm the A record points at the box; wait for propagation (domains-dns) |
+| Wildcard cert fails on HTTP-01 | Wildcards require DNS-01 | Configure the DNS provider token and use DNS-01 |
+| Rate-limit / "too many certificates" | Hit Let's Encrypt issuance limit by retrying | Wait out the limit; use staging while debugging, then switch to production |
+| Dashboard at `:8000` has no cert | FQDN + force HTTPS not set | Set the instance FQDN and enable force HTTPS in Settings |

package/skills/coolify/scripts/verify.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — coolify skill gate. Run from your PROJECT root (or this skill's dir).
+#
+# Static, read-only lint of any committed docker-compose artifact (docker-compose.yml/.yaml,
+# compose.yml/.yaml) plus a check that this skill's SKILL.md documents the canonical port matrix.
+# It NEVER writes, NEVER connects to the network, and NEVER deploys.
+#
+# Per compose file it asserts:
+#   (a) no hardcoded secret literal — values for *PASSWORD*/*SECRET*/*TOKEN*/*_KEY*/DATABASE_URL
+#       must be env-refs (${...}) , not inline literals.
+#   (b) any database service (postgres/mysql/mariadb/mongo) is backed by a NAMED volume (data-loss guard).
+#   (c) at least one healthcheck: present.
+#   (d) no floating ":latest" image tag, and no image without an explicit tag (also "floating").
+# And once: SKILL.md mentions every canonical port (8000 80 443 6001 6002).
+#
+# Exit code: non-zero ONLY on a hard failure (a/b/c/d or a missing port). An EMPTY/CLEAN target
+# (no compose files found) exits 0 with a skip — never a false failure. Missing optional context
+# (no SKILL.md to check) is advisory, not fatal.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays). Arrays are initialised so
+# they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# --- discover compose files (skip vendor dirs) ---
+COMPOSE_FILES=()
+while IFS= read -r -d '' f; do
+  COMPOSE_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -name 'docker-compose.yml' -o -name 'docker-compose.yaml' \
+               -o -name 'compose.yml' -o -name 'compose.yaml' \) -print0 2>/dev/null
+)
+
+lint_compose() {
+  file="$1"
+  base="$(basename "$file")"
+
+  # (a) hardcoded secrets: a *PASSWORD/SECRET/TOKEN/_KEY/DATABASE_URL key whose value is NOT a ${...} ref
+  #     and is not empty. We look at "key: value" pairs (env blocks are key: value in compose).
+  if grep -Eiq '^[[:space:]]*[A-Za-z_]*(password|secret|token|_key|database_url)[A-Za-z_]*[[:space:]]*:[[:space:]]*[^$[:space:]"'"'"'].*' "$file"; then
+    # exclude the case where the value is an env-ref like ${FOO}
+    if grep -Ei '^[[:space:]]*[A-Za-z_]*(password|secret|token|_key|database_url)[A-Za-z_]*[[:space:]]*:[[:space:]]*' "$file" \
+       | grep -Eiv ':[[:space:]]*("?\$\{|\$[A-Za-z_])' \
+       | grep -Eq ':[[:space:]]*[^[:space:]$]'; then
+      err "$base: hardcoded secret literal — use an env-ref (\${VAR}) injected by Coolify, not an inline value"
+    fi
+  fi
+
+  # (b) named volume for any database service. If a db image is present, require a top-level `volumes:` map.
+  if grep -Eiq 'image:[[:space:]]*("?)(postgres|mysql|mariadb|mongo)' "$file"; then
+    if grep -Eq '^volumes:' "$file"; then
+      ok "$base: database service has a named volume declaration"
+    else
+      err "$base: database service without a named volume — data is wiped on recreate"
+    fi
+  fi
+
+  # (c) at least one healthcheck
+  if grep -Eq '^[[:space:]]*healthcheck:' "$file"; then
+    ok "$base: healthcheck present"
+  else
+    err "$base: no healthcheck: — Coolify/Traefik can't tell when the container is ready"
+  fi
+
+  # (d) floating tags: image: foo:latest, or image: foo with no tag at all
+  while IFS= read -r line; do
+    img="$(printf '%s' "$line" | sed -E 's/^[[:space:]]*image:[[:space:]]*"?//; s/"?[[:space:]]*$//')"
+    case "$img" in
+      \$*) : ;;                                   # env-ref image, skip
+      *:latest) err "$base: floating ':latest' tag on image '$img' — pin a tag or digest" ;;
+      *@sha256:*) : ;;                            # digest-pinned, fine
+      *:*) : ;;                                   # has an explicit tag, fine
+      *) err "$base: image '$img' has no tag (floating) — pin a tag or digest" ;;
+    esac
+  done < <(grep -E '^[[:space:]]*image:[[:space:]]*' "$file" || true)
+}
+
+if [ "${#COMPOSE_FILES[@]}" -eq 0 ]; then
+  skip "no docker-compose files found — nothing to lint (clean)"
+else
+  for f in "${COMPOSE_FILES[@]}"; do
+    lint_compose "$f"
+  done
+fi
+
+# --- port matrix documented in SKILL.md (look next to this script, then under ROOT) ---
+SKILL_MD=""
+if [ -f "$SCRIPT_DIR/../SKILL.md" ]; then
+  SKILL_MD="$SCRIPT_DIR/../SKILL.md"
+else
+  cand="$(find "$ROOT" -type f -name 'SKILL.md' -path '*coolify*' -print 2>/dev/null | head -n1 || true)"
+  [ -n "$cand" ] && SKILL_MD="$cand"
+fi
+
+if [ -n "$SKILL_MD" ] && [ -f "$SKILL_MD" ]; then
+  missing=""
+  for p in 8000 80 443 6001 6002; do
+    grep -Eq "(^|[^0-9])$p([^0-9]|$)" "$SKILL_MD" || missing="$missing $p"
+  done
+  if [ -n "$missing" ]; then
+    err "SKILL.md missing canonical port(s):$missing"
+  else
+    ok "SKILL.md documents the canonical port matrix (8000/80/443/6001/6002)"
+  fi
+else
+  skip "no coolify SKILL.md found to check the port matrix"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/cost-tracking/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: cost-tracking
+description: "Use when you need to track and cap what an AI or cloud app spends — capturing per-request tokens, pricing them against a current rate table, ledgering spend per user/feature/model/tenant, and firing budget alerts or a hard cap before the bill lands instead of after. Triggers: 'track token costs per request', 'cap our OpenAI/Claude spend', 'budget alert before we blow the bill', 'attribute cost per user or tenant', 'a runaway agent loop just burned $X', 'is prompt caching actually cheaper and where is the break-even', 'why is our bill 3x the estimate', 'reconcile billed usage against the response usage object', 'cuánto gastamos en tokens este mes', 'pon un tope de gasto a la API y avísame al 80%', 'controlar el cost de la IA'. NOT company cash runway or burn (that is finance-ops), NOT cost-per-unit margin (that is unit-economics), NOT the accounting record of the spend (that is bookkeeping)."
+tags: ["cost-tracking", "token-accounting", "llm-spend", "budgets", "alerts", "prompt-caching", "billing-guardrails", "finops"]
+recommends: ["finance-ops", "unit-economics", "analytics", "stripe", "aws-essentials", "gcp-essentials"]
+origin: risco
+---
+
+# Cost tracking
+
+You are building the money meter for an AI or cloud app: every model call gets a token count, a price, a ledger row, and a budget check — so a cap fires *before* the invoice, not when finance forwards it in a panic. Model-API spend roughly doubled from $3.5B to $8.4B between late 2024 and mid 2025 (firecrawl.dev best-llm-observability-tools, accessed 2026-06-02); the bill is now big enough to need a guardrail, not a spreadsheet at month-end.
+
+The chain you build, in order — each step feeds the next:
+
+1. **Capture** — read tokens from the response, not from a pre-send guess.
+2. **Price** — multiply tokens by a *versioned, dated* rate table.
+3. **Ledger** — append one idempotent row per request, tagged for attribution.
+4. **Budget** — roll the ledger up against a soft and a hard threshold.
+5. **Guard** — alert, degrade, or refuse before the threshold becomes an invoice.
+
+The one rule that organizes everything: **bill against the response `usage` object. Anything you compute before the call is an estimate — good only for the pre-flight cap check, never for the ledger.**
+
+## What this skill produces
+
+A checkable cost setup: a **pricing table** (each model row carries `effective_date` + `source`), an **append-only ledger** schema (idempotency key + attribution keys), and a **budget** with both a soft and a hard threshold. `scripts/verify.sh` lints those artifacts (last section). Prose alone is not a deliverable — emit the config.
+
+## Capture: read `usage`, do not estimate
+
+Pre-send token counts (`tiktoken`, Anthropic `client.messages.count_tokens()`) are estimates. They exist for the *pre-flight cap check* — "will this request likely breach the budget?" — and nothing else. The truth lands in the response: input, output, **cached**, and **reasoning** tokens, plus audio/image tokens where the modality applies. Bill the ledger off that object.
+
+Two provider facts that bite if you assume otherwise:
+- Anthropic `count_tokens()` returns *input* tokens only, is free, has its own rate limit, and is still an estimate. Anthropic is **not** tiktoken-compatible — do not reuse an OpenAI tokenizer to price Claude (platform.claude.com token-counting; github.com/anthropics/anthropic-tokenizer-typescript, accessed 2026-06-02).
+- Output and reasoning tokens are the expensive half — output runs 4-5x the input rate. A meter that only counts input is wrong by most of the bill.
+
+```python
+# Bad: pricing off a pre-send character/word guess. Wrong, and ignores output.
+est_tokens = len(prompt) // 4
+cost = est_tokens * rate_in            # output + reasoning never counted
+
+# Good: capture every field the response actually reports, then price that.
+resp = client.messages.create(model=model, messages=msgs, max_tokens=1024)
+u = resp.usage
+record = {
+    "input_tokens":  u.input_tokens,
+    "output_tokens": u.output_tokens,
+    "cache_read_tokens":     getattr(u, "cache_read_input_tokens", 0),
+    "cache_write_tokens":    getattr(u, "cache_creation_input_tokens", 0),
+    # OpenAI exposes cached as usage.prompt_tokens_details.cached_tokens
+}
+cost = price(model, record)            # see "pricing is data" below
+```
+
+Wrap the SDK call **once** so capture cannot be skipped. A meter you have to remember to call is a meter that's already missing rows (langfuse.com token-and-cost-tracking, accessed 2026-06-02).
+
+## Pricing is data, never literals
+
+Rates drift fast and silently mis-bill when stale. Keep prices in a **versioned table** — one row per model, each with `effective_date` and `source` — loaded as data. Never write a rate as a literal in business logic. Look up by model and **fail loud on an unknown model; never default to $0**, or a new model silently bills as free and the leak is invisible.
+
+```yaml
+# pricing.yaml — perishable. Verify against source before trusting. Dated 2026-06-02.
+models:
+  - model: claude-haiku-4.5
+    effective_date: 2026-06-02
+    source: cloudzero.com/blog/claude-api-pricing
+    input_per_mtok: 1.00
+    output_per_mtok: 5.00
+    cache_read_per_mtok: 0.10
+  - model: claude-sonnet-4.6
+    effective_date: 2026-06-02
+    source: cloudzero.com/blog/claude-api-pricing
+    input_per_mtok: 3.00
+    output_per_mtok: 15.00
+    cache_read_per_mtok: 0.30
+  - model: claude-opus-4.7
+    effective_date: 2026-06-02
+    source: cloudzero.com/blog/claude-api-pricing
+    input_per_mtok: 5.00
+    output_per_mtok: 25.00
+    cache_read_per_mtok: 0.50
+  - model: gpt-5.5
+    effective_date: 2026-06-02
+    source: openai.com/api/pricing
+    input_per_mtok: 5.00
+    output_per_mtok: 40.00
+    cache_read_per_mtok: 0.50   # OpenAI cached input = 90% off standard input
+```
+
+These numbers are a **snapshot, not a constant** — model names and rates move month to month. Dated 2026-06-02 from the sources above. The dated per-provider snapshots, the `usage`-field map per provider, and refresh instructions live in `references/pricing-tables.md`; read it before you trust a rate.
+
+## Ledger: append-only, idempotent, attributed
+
+One row per request, append-only. Two things must be on every row or the ledger lies:
+
+- A **request/idempotency key.** Retries and SDK auto-retries fire the same logical call twice; without a key the row is written twice and you double-count spend.
+- At least one **attribution key** (user, tenant, feature, model). A per-org total can tell you the bill is high; it cannot tell you *which feature or customer* is the leak. Attribution is the difference between "spend is up" and "the summarize-document feature on the enterprise tenant tripled."
+
+```sql
+-- append-only; (request_id) is the idempotency key — upsert, never plain insert
+CREATE TABLE llm_cost_ledger (
+  request_id     TEXT PRIMARY KEY,           -- idempotency: retries collapse to one row
+  ts             TIMESTAMPTZ NOT NULL,
+  model          TEXT NOT NULL,
+  input_tokens   INTEGER NOT NULL,
+  output_tokens  INTEGER NOT NULL,
+  cached_tokens  INTEGER NOT NULL DEFAULT 0,
+  cost_usd       NUMERIC(12,6) NOT NULL,      -- priced from the table above
+  user_id        TEXT,                        -- attribution keys
+  tenant_id      TEXT,
+  feature        TEXT
+);
+```
+
+This is an *operational* ledger, not the accounting record — categorizing the spend into the books is `bookkeeping`.
+
+## Budgets, alerts, caps
+
+A budget needs a **soft** state (alert + degrade) and a **hard** state (refuse). Roll the ledger up per window (day/month) and per attribution key, then branch:
+
+| Spend vs budget | State | Action |
+|---|---|---|
+| < 50% | normal | log only |
+| 50% / 80% | warn | fire alert to the same pipe as cloud alerts; no behavior change |
+| 100% | **soft cap** | degrade — downshift to a cheaper model, drop optional/enrichment calls, shrink context |
+| over hard cap | **hard cap** | refuse the request with a typed error (`BudgetExceededError`), not a silent failure |
+
+Two distinct checks, do not conflate them:
+- **Pre-flight gate** uses the *estimate* (pre-send token count × rate) to refuse a request that would obviously blow the hard cap — this is the only legitimate use of an estimate.
+- **Post-hoc reconciliation** rolls up the *ledger* (real `usage`) against the budget. When someone asks "why is the bill 3x the estimate," you compare provider-billed usage to your ledgered `usage` — the gap is almost always uncounted output/reasoning/cache-write tokens or missing rows from un-wrapped call sites.
+
+## The three levers that move the number
+
+Don't assert savings — show the break-even. Pricing per fact-checked sources accessed 2026-06-02 (platform.claude.com prompt-caching; finout.io anthropic-api-pricing).
+
+- **Prompt caching.** Cache *reads* cost 0.1x base input. The 5-min write costs 1.25x, the 1-hour write 2x. So a 5-min entry pays for itself after roughly **one** cache hit: `1.25 + 0.1·h` (cached) beats `1·(1+h)` (uncached) once `h ≥ 1`. Caching a stable system prompt across a session is almost always net cheaper.
+- **Batch API.** 50% off on both OpenAI and Anthropic, async within 24h, and it **stacks with caching** — combined up to ~95% off. Use it for anything not user-facing-realtime: evals, backfills, nightly summaries.
+- **Model downshift.** The largest lever. Route easy requests to Haiku/cheap models and reserve Opus/GPT-5.5 for hard ones — at 5x the rate, downshifting the routable half of traffic dwarfs a few percent of caching.
+
+"We'll add caching later" without measuring the hit rate is a guess, not a lever. Instrument `cache_read_tokens` in the ledger first, then you know.
+
+## Cloud spend is the slow backstop
+
+App-level metering is your real-time guard. Cloud billing alerts are a **delayed backstop** — useful, but never the thing standing between you and a runaway loop.
+
+- **AWS** Cost Anomaly Detection is ML-based, runs ~3x/day with up to 24h data delay → SNS → Lambda. AWS Budgets adds threshold alerts on the same pipe.
+- **GCP/Azure** are threshold-only. GCP's budget → Pub/Sub → Cloud Function is the one that can actually *pause or throttle* a workload programmatically.
+
+Route every cloud alert into the **same alert pipe** as your app-level budget alerts so there's one place to look. The 24h delay is exactly why the in-app cap exists: by the time AWS notices the anomaly, the loop already spent the money. Recipes and the alert-routing pattern are in `references/cloud-caps.md`.
+
+## Build vs buy
+
+| You want | Use | Trade-off |
+|---|---|---|
+| Zero code change, fastest setup | Helicone (proxy, ~2-min) | adds a network hop / latency |
+| SDK-level capture + a ready cost table | Langfuse (MIT, ships model+tokenizer cost table) | you wire the SDK, but no proxy hop |
+| Full control / custom attribution / typed caps | DIY ledger (this skill) | you own pricing-table freshness and capture coverage |
+
+(firecrawl.dev best-llm-observability-tools; guptadeepak.com top-5-llm-observability-platforms-2026, accessed 2026-06-02.) Buy the proxy/platform when you want spend *visibility* fast; build the ledger when caps and per-feature attribution must live inside your own logic.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Pricing literals in business logic | a rate change silently mis-bills everything | versioned table, each row dated + sourced |
+| Billing off the pre-send estimate | estimates ignore output/reasoning/cache; off by most of the bill | price the response `usage` object |
+| No idempotency key on ledger rows | retries double-count spend | `request_id` PRIMARY KEY, upsert not insert |
+| Unknown model defaults to $0 | a new model bills as free; leak is invisible | fail loud on a model absent from the table |
+| Only a soft alert, no hard cap | alert fires, loop keeps spending | a hard cap that refuses with a typed error |
+| Org-total budget, no attribution | "spend is up" — but you can't find the leak | tag every row by user/tenant/feature |
+| Counting input tokens only | output+reasoning are 4-5x the cost — the expensive half | capture all token fields from `usage` |
+| Trusting cloud alerts for real-time control | ~24h delay; the loop already spent it | app-level cap is the guard; cloud is the backstop |
+| "Add caching later" with no measurement | savings unproven; may not even hit | instrument `cache_read_tokens`, compute break-even |
+
+## Verify the artifact
+
+`scripts/verify.sh [path]` lints a candidate cost config/ledger (yaml/json/ts) and fails if: a pricing entry lacks `effective_date` or `source`; a model referenced in logic is missing from the table; the ledger schema lacks an idempotency/request key or any attribution key; the budget declares no soft+hard pair; or cost looks derived from a `len()`/char estimate instead of a `usage` field. It is read-only and exits 0 on a clean config and on no config found — no false failure.
+
+## Where this hands off
+
+- Company cash runway / burn / forecast → `finance-ops` (cost-tracking is one input line).
+- Cost-per-unit margin, contribution, CAC:LTV → `unit-economics` (this produces the cost numerator).
+- "Cost per active user" behavior side / product telemetry → `analytics`.
+- Billing customers, metered usage charges → `stripe`.
+- The AWS/GCP cap plumbing in depth → `aws-essentials` / `gcp-essentials`.

package/skills/cost-tracking/evals/README.md

@@ -0,0 +1,3 @@
+# Evals for cost-tracking
+
+These cases are eyeballed, not automated. Read `cases.yaml` and check three things by hand. First, every `should_trigger` prompt should make this skill the obvious pick — pay attention to the non-obvious ones (the "bill is 3x the estimate / reconcile billed vs response usage" line and the Spanish budget-cap line), since those are where a thinner trigger set would miss. Second, every `should_not_trigger` prompt should route cleanly to the named sibling (finance-ops, unit-economics, bookkeeping, pricing, analytics) — if any of those feels like it could legitimately land here, the description boundary needs tightening. Third, run the `capability` scenario against a generated answer and confirm each `must_include` rubric item is actually present, not hand-waved (especially: cost read from `usage`, dated+sourced pricing table, idempotency + attribution on the ledger, and a soft *and* hard cap). Note that `scripts/verify.sh` checks the emitted artifact (the pricing/ledger/budget config), not the prose — a great write-up that emits no checkable config has not finished the job.