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

package/skills/shared/docker/references/base-images-and-stages.md

@@ -0,0 +1,104 @@
+# Base images & multi-stage templates
+
+Per-language skeletons beyond the three in SKILL.md, plus tag maps and multi-arch notes.
+
+## Tag map (2026)
+
+| Goal | Tag |
+|---|---|
+| Pragmatic glibc default | `debian:bookworm-slim`, `python:3.13-slim-bookworm`, `node:24-bookworm-slim` |
+| Distroless runtime | `gcr.io/distroless/static-debian12:nonroot`, `gcr.io/distroless/nodejs24-debian13:nonroot`, `gcr.io/distroless/python3-debian12:nonroot` |
+| Chainguard / Wolfi | `cgr.dev/chainguard/node:latest`, `cgr.dev/chainguard/python:latest`, `cgr.dev/chainguard/static:latest` (pin the digest in prod) |
+| Fully static binary | `scratch` |
+
+Node tags follow the active LTS (`24` as of mid-2026); `22` is Maintenance LTS — pick it only as
+the conservative choice. Go tags follow the two supported minors (`1.26`/`1.25`); never ship a
+build image off the supported window since it stops getting security patches.
+
+Chainguard images carry SLSA L3 build attestations and track the lowest live CVE counts; real
+scans have found high-severity CVEs in a distroless image where the Chainguard equivalent had zero.
+Distroless is convenient but patches more slowly. Pin by digest for reproducibility.
+
+## Rust → scratch / distroless-static
+
+Pin the build image to your project's MSRV (the minimum Rust your `Cargo.toml` declares), or to a
+current stable minor if you have none — `1.96` is the latest stable as of mid-2026. *Why: a stale
+build image (e.g. `1.83`, ~13 minors back) compiles fine but stops getting toolchain security
+fixes, the same supported-window rule as the Node/Go skeletons.*
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM rust:1.96-bookworm AS build
+WORKDIR /src
+COPY Cargo.toml Cargo.lock ./
+RUN mkdir src && echo "fn main() {}" > src/main.rs
+RUN --mount=type=cache,target=/usr/local/cargo/registry cargo build --release
+COPY . .
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    touch src/main.rs && cargo build --release
+
+FROM gcr.io/distroless/cc-debian12:nonroot
+COPY --from=build /src/target/release/app /app
+USER nonroot
+ENTRYPOINT ["/app"]
+```
+
+Use `distroless/cc` (not `static`) when you link against glibc/`libgcc`. For musl-static, build the
+`x86_64-unknown-linux-musl` target and ship on `scratch`.
+
+## JVM → jlink custom runtime
+
+A full JRE is ~200 MB; a `jlink`-trimmed runtime with only the modules you use is ~50–80 MB.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM eclipse-temurin:21-jdk AS build
+WORKDIR /src
+COPY . .
+RUN ./mvnw -q package -DskipTests
+RUN jlink --add-modules java.base,java.logging,java.sql,java.naming \
+      --strip-debug --no-man-pages --no-header-files --compress=2 \
+      --output /javaruntime
+
+FROM debian:bookworm-slim
+RUN useradd --uid 10001 app
+COPY --from=build /javaruntime /opt/java
+COPY --from=build --chown=app:app /src/target/app.jar /app/app.jar
+ENV PATH="/opt/java/bin:$PATH"
+USER app
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]
+```
+
+Run `jdeps --print-module-deps target/app.jar` to discover the real module list.
+
+## Static SPA → nginx (non-root)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN --mount=type=cache,target=/root/.npm npm ci
+COPY . .
+RUN npm run build
+
+FROM nginxinc/nginx-unprivileged:1.27-bookworm
+COPY --from=build /app/dist /usr/share/nginx/html
+# nginx-unprivileged already runs as UID 101 and listens on 8080
+EXPOSE 8080
+```
+
+Use `nginxinc/nginx-unprivileged` so you are not running the webserver as root. Caddy
+(`caddy:2-alpine`) is a smaller alternative with automatic compression.
+
+## Multi-arch with buildx
+
+```bash
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -t myimage:1.4.0 --push .
+```
+
+Cross-compile rather than emulate where the toolchain allows it: Go uses `GOOS`/`GOARCH`, Rust uses
+`--target`. Emulated arm64 builds via QEMU are correct but slow; native cross-compile in the build
+stage then `COPY` per-arch is far faster.

package/skills/shared/docker/references/compose-recipes.md

@@ -0,0 +1,109 @@
+# Compose recipes
+
+Fuller `compose.yaml` patterns. Canonical filename is `compose.yaml`; omit `version:`; use the
+`docker compose` v2 subcommand.
+
+## Watch per stack
+
+| Stack | `sync` paths | `rebuild` triggers |
+|---|---|---|
+| Node/Vite/Next | `./src`, `./public` | `package-lock.json` |
+| Python/uv | `./app` | `uv.lock`, `pyproject.toml` |
+| Go (live reload via `air`) | `./` | `go.mod`, `go.sum` |
+
+`sync` copies changed files into the running container (the process must itself hot-reload).
+`rebuild` rebuilds the image when a dependency manifest changes. `sync+restart` syncs then restarts
+PID 1 — use it for config files the process reads only at startup. Use `ignore:` under a watch
+rule to exclude noisy paths (e.g. `node_modules`).
+
+## Healthcheck graph: postgres + redis + app
+
+```yaml
+services:
+  app:
+    build: .
+    depends_on:
+      db:
+        condition: service_healthy
+      cache:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgres://postgres:dev@db:5432/app
+      REDIS_URL: redis://cache:6379
+    develop:
+      watch:
+        - { action: sync, path: ./app, target: /app/app }
+        - { action: rebuild, path: ./uv.lock }
+  db:
+    image: postgres:17-bookworm
+    environment: { POSTGRES_PASSWORD: dev, POSTGRES_DB: app }
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d app"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    volumes: ["pgdata:/var/lib/postgresql/data"]
+  cache:
+    image: redis:7-bookworm
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+`condition: service_healthy` makes `app` wait until both backing services report healthy, instead
+of merely "container started" — which avoids the classic "connection refused on boot" race.
+
+## Profiles
+
+```yaml
+services:
+  app: { build: . }
+  seed:
+    profiles: ["tools"]
+    build: .
+    command: ["python", "-m", "app.seed"]
+  mailpit:
+    profiles: ["tools"]
+    image: axllent/mailpit:latest
+```
+
+Services with a `profiles:` key are inert unless their profile is requested:
+`docker compose --profile tools up`. Use it for seeders, mail catchers, admin UIs.
+
+## env_file vs secrets
+
+- `env_file: [.env]` — convenient for non-sensitive dev config; values become container env.
+- `secrets:` — mounts a file at `/run/secrets/<name>`; the value is not in the process environment
+  and not in `docker inspect`. Prefer it for anything sensitive even in dev.
+
+```yaml
+services:
+  app:
+    build: .
+    secrets: [db_password]
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+```
+
+## Override files
+
+`docker compose` automatically merges `compose.override.yaml` on top of `compose.yaml`. Keep dev-only
+bind mounts and `develop.watch` in the base for local use; create an explicit
+`-f compose.yaml -f compose.prod.yaml` pair if you must describe a prod-ish stack — but that is the
+edge of this skill's scope.
+
+## When to graduate
+
+Compose is a single-host orchestrator. The moment you need rolling deploys, multi-host scheduling,
+autoscaling, or a registry/CI pipeline, stop here:
+
+- registry push, CI build, deploy to a host, rollback → `../deployment/SKILL.md`
+- horizontal autoscaling, k8s, HPA, ingress → `scaling`
+- running Compose on a managed host / self-hosted PaaS → `../coolify/SKILL.md`,
+  `../railway/SKILL.md`, `../fly-io/SKILL.md`

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# verify.sh — read-only static checks for docker artifacts (Dockerfile, compose.yaml, .dockerignore)
+#
+# Usage:
+#   ./verify.sh [DIR] [IMAGE_TAG]
+#     DIR        directory to scan (default: current dir)
+#     IMAGE_TAG  optional built image to scan with trivy/dockle and size-check
+#
+# Behavior:
+#   - Read-only: never builds, never writes, never pulls.
+#   - Degrades gracefully: a missing tool is a SKIP (warning), not a failure — CI-safe.
+#   - Exits 0 on a clean or empty target (no Dockerfile/compose present => nothing to fail).
+#   - Exits 1 only on a real banned pattern or an error-level lint/parse failure.
+
+set -uo pipefail
+
+DIR="${1:-.}"
+IMAGE_TAG="${2:-}"
+SIZE_LIMIT_BYTES="${DOCKER_VERIFY_SIZE_LIMIT:-524288000}" # 500 MB default, override via env
+
+fail=0
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf 'SKIP: %s\n' "$1" >&2; }
+err()  { printf 'FAIL: %s\n' "$1" >&2; fail=1; }
+ok()   { printf 'OK:   %s\n' "$1"; }
+
+# Locate a Dockerfile / Containerfile.
+DOCKERFILE=""
+for cand in "$DIR/Dockerfile" "$DIR/Containerfile"; do
+  [ -f "$cand" ] && DOCKERFILE="$cand" && break
+done
+
+# Locate a compose file.
+COMPOSE=""
+for cand in "$DIR/compose.yaml" "$DIR/compose.yml" "$DIR/docker-compose.yaml" "$DIR/docker-compose.yml"; do
+  [ -f "$cand" ] && COMPOSE="$cand" && break
+done
+
+if [ -z "$DOCKERFILE" ] && [ -z "$COMPOSE" ]; then
+  ok "no Dockerfile or compose file in '$DIR' — nothing to verify"
+  exit 0
+fi
+
+# ---- Dockerfile checks ----
+if [ -n "$DOCKERFILE" ]; then
+  ok "found $DOCKERFILE"
+
+  # Ban: :latest base images.
+  if grep -nEi '^[[:space:]]*FROM[[:space:]]+[^[:space:]]+:latest([[:space:]]|$)' "$DOCKERFILE" >/dev/null \
+     || grep -nEi '^[[:space:]]*FROM[[:space:]]+[^[:space:]@:]+([[:space:]]+AS|[[:space:]]*$)' "$DOCKERFILE" >/dev/null; then
+    err "$DOCKERFILE: FROM uses :latest or an unpinned image (pin a tag or digest)"
+  else
+    ok "all FROM lines are pinned (no :latest)"
+  fi
+
+  # Ban: secrets in ARG/ENV.
+  if grep -nEi '^[[:space:]]*(ARG|ENV)[[:space:]]+.*(TOKEN|SECRET|PASSWORD|PASSWD|API[_-]?KEY|PRIVATE[_-]?KEY|ACCESS[_-]?KEY)' "$DOCKERFILE" >/dev/null; then
+    err "$DOCKERFILE: secret-looking value in ARG/ENV (use RUN --mount=type=secret)"
+  else
+    ok "no secret-looking ARG/ENV"
+  fi
+
+  # Require: a USER instruction (non-root).
+  if grep -nEi '^[[:space:]]*USER[[:space:]]+' "$DOCKERFILE" >/dev/null; then
+    if grep -nEi '^[[:space:]]*USER[[:space:]]+(root|0)[[:space:]]*$' "$DOCKERFILE" >/dev/null; then
+      err "$DOCKERFILE: final USER is root/0 (run as a non-root user)"
+    else
+      ok "non-root USER present"
+    fi
+  else
+    err "$DOCKERFILE: no USER instruction (container will run as root)"
+  fi
+
+  # hadolint (optional).
+  if have hadolint; then
+    if hadolint --no-fail "$DOCKERFILE" | grep -qiE ' error| DL[0-9]+ error'; then
+      err "$DOCKERFILE: hadolint reported error-level findings"
+    else
+      hadolint --failure-threshold error "$DOCKERFILE" && ok "hadolint clean (error level)" || err "$DOCKERFILE: hadolint error-level findings"
+    fi
+  else
+    warn "hadolint not installed — skipping Dockerfile lint"
+  fi
+fi
+
+# ---- compose checks ----
+if [ -n "$COMPOSE" ]; then
+  ok "found $COMPOSE"
+
+  # Ban: obsolete version: key.
+  if grep -nE '^[[:space:]]*version[[:space:]]*:' "$COMPOSE" >/dev/null; then
+    err "$COMPOSE: obsolete top-level 'version:' key (remove it)"
+  else
+    ok "no obsolete version: key"
+  fi
+
+  # Validate with docker compose if available.
+  if have docker && docker compose version >/dev/null 2>&1; then
+    if docker compose -f "$COMPOSE" config -q >/dev/null 2>&1; then
+      ok "docker compose config -q parses"
+    else
+      err "$COMPOSE: docker compose config -q failed to parse/resolve"
+    fi
+  else
+    warn "docker compose v2 not available — skipping compose validation"
+  fi
+fi
+
+# ---- optional image scans (only when a tag is provided) ----
+if [ -n "$IMAGE_TAG" ]; then
+  if have trivy; then
+    trivy image --scanners vuln --severity HIGH,CRITICAL --exit-code 0 "$IMAGE_TAG" \
+      && ok "trivy scanned $IMAGE_TAG (review HIGH/CRITICAL above)" \
+      || warn "trivy could not scan $IMAGE_TAG"
+  else
+    warn "trivy not installed — skipping image CVE scan"
+  fi
+
+  if have dockle; then
+    dockle --exit-code 0 "$IMAGE_TAG" && ok "dockle checked $IMAGE_TAG" || warn "dockle could not check $IMAGE_TAG"
+  else
+    warn "dockle not installed — skipping image hygiene check"
+  fi
+
+  if have docker; then
+    size="$(docker image inspect -f '{{.Size}}' "$IMAGE_TAG" 2>/dev/null || echo '')"
+    if [ -n "$size" ]; then
+      if [ "$size" -gt "$SIZE_LIMIT_BYTES" ]; then
+        err "image $IMAGE_TAG is ${size} bytes (> ${SIZE_LIMIT_BYTES}); consider a smaller base / multi-stage"
+      else
+        ok "image $IMAGE_TAG size ${size} bytes is within limit ${SIZE_LIMIT_BYTES}"
+      fi
+    else
+      warn "could not inspect size of $IMAGE_TAG (not built locally?)"
+    fi
+  fi
+elif have trivy && [ -n "$DOCKERFILE" ]; then
+  # No tag: still do a build-free config scan if trivy is present.
+  trivy config "$DIR" --severity HIGH,CRITICAL --exit-code 0 \
+    && ok "trivy config scanned $DIR (review findings above)" \
+    || warn "trivy config could not scan $DIR"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  printf '\nverify.sh: FAILED\n' >&2
+  exit 1
+fi
+printf '\nverify.sh: PASSED\n'
+exit 0

package/skills/shared/domains-dns/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: domains-dns
+description: "Use when pointing a domain at a host or fixing broken HTTPS — delegating nameservers, writing A/AAAA/CNAME/ALIAS/MX/TXT/CAA rows, apex vs www, standing up auto-renewing TLS, and cutting nameservers over without downtime. NOT inbox placement or warmup (that is `email-deliverability`), NOT what runs behind the name (that is `deployment`)."
+tags: [dns, tls, ssl, domains, https, acme, certbot, dig, caa, nameservers]
+recommends: [email-deliverability, deployment, monitoring, cloudflare, vercel]
+origin: ai-hub
+---
+
+# Domains & DNS
+
+You set up a name end to end: register or delegate it, write the records, and serve valid HTTPS. Almost every "my domain doesn't work" report is one of a handful of recurring mistakes. This skill names them and gives you paste-ready records plus the commands to prove they took.
+
+## Resolution order is debug order
+
+A request resolves in one direction. Diagnose in the same direction, top-down, because the bug is almost always at the layer the user is *not* looking at.
+
+1. **Name** — does the domain exist and is it registered/not expired? (`whois`)
+2. **Delegation** — do the registrar's nameservers point at the DNS provider that actually holds the zone? (`dig NS`)
+3. **Records** — does the authoritative zone return the right A/AAAA/CNAME/ALIAS/MX/TXT/CAA? (`dig @<authoritative-ns>`)
+4. **TLS** — does the served chain validate and is it unexpired? (`openssl s_client`)
+
+Rule: never debug TLS before you've confirmed the record resolves to the box you think it does — a cert error is often a record pointing at the wrong host. Query authoritative nameservers, not your laptop's cache, or you'll chase a stale answer for an hour.
+
+## Where the DNS lives
+
+Pick **one** authoritative provider and keep the whole zone there. Splitting a zone across two providers (some records at the registrar, some at Cloudflare) is the source of "it works for me but not for them" — resolvers see whichever NS set answered.
+
+| Host the zone at | Choose when | Why |
+| --- | --- | --- |
+| Registrar DNS (GoDaddy, Namecheap, Porkbull) | Tiny static site, one or two records | One vendor, fewer logins; weak APIs and slow propagation |
+| Dedicated DNS (Cloudflare, DNSimple) | Most cases; want CNAME flattening + fast edits | Apex flattening, low TTL edits, good API; see ../cloudflare/SKILL.md |
+| Cloud DNS (Route 53, Cloud DNS) | Already all-in on AWS/GCP and want alias-to-LB | Native alias records to cloud load balancers |
+| Host-managed (Vercel, Netlify) | The host *is* the only thing the domain serves | Auto-TLS + apex flattening handled for you; see ../vercel/SKILL.md |
+
+## Apex vs www — the load-bearing trap
+
+You **cannot put a CNAME at the zone apex** (the naked `example.com`). The spec forbids a CNAME coexisting with the SOA and NS records that must live there (RFC 1034 §3.6.2, RFC 2181). Registrars that let you save it produce a silently broken zone.
+
+```text
+# Bad — CNAME at the apex. Breaks SOA/NS; mail and other apex records vanish.
+example.com.        CNAME   cname.vercel-dns.com.
+
+# Good — flatten at the apex (ALIAS/ANAME or provider flattening), CNAME only on the subdomain.
+example.com.        ALIAS   cname.vercel-dns.com.     # Cloudflare/Netlify/Route53/DNSimple equivalent
+www.example.com.    CNAME   cname.vercel-dns.com.
+
+# Good (no flattening available) — hard-code the host's published A/AAAA at the apex.
+example.com.        A       76.76.21.21
+www.example.com.    CNAME   cname.vercel-dns.com.
+```
+
+Then pick **one canonical host** and 301 the other to it (apex→www or www→apex — either, just be consistent). Two live origins split your SEO and your cookies. The redirect lives at the host/edge, not in DNS.
+
+## Record cookbook (summary)
+
+One example row per type. Edge cases — TXT 255-char chunking, MX priority math, the SPF 10-lookup limit, SRV format, NS/SOA, PTR, DNSSEC — live in `references/record-cookbook.md`.
+
+| Type | Use for | Example (name → value) |
+| --- | --- | --- |
+| `A` | name → IPv4 | `app → 76.76.21.21` |
+| `AAAA` | name → IPv6 | `app → 2606:4700::6810` |
+| `CNAME` | subdomain → another name (never apex) | `www → cname.vercel-dns.com.` |
+| `ALIAS`/`ANAME` | apex → another name (flattened to A/AAAA) | `@ → cname.netlify.app.` |
+| `MX` | where mail is delivered (priority, lower = first) | `@ → 10 mail.example.com.` |
+| `TXT` | SPF / DKIM / DMARC / domain-verification | `@ → "v=spf1 include:_spf.google.com ~all"` |
+| `CAA` | which CA may issue certs | `@ → 0 issue "letsencrypt.org"` |
+| `SRV` | service discovery (proto/port) | `_sip._tcp → 10 5 5060 sip.example.com.` |
+
+The SPF/DKIM/DMARC/MX **rows** belong here. *Whether mail lands* — reputation, warmup, inbox placement — is ../email-deliverability/SKILL.md.
+
+## TLS / certificates
+
+**The 2026 reality:** the CA/Browser Forum cut the maximum public-TLS lifetime to **200 days** (from 398) on 2026-03-15, dropping to **100 days on 2027-03-15** and **47 days on 2029-03-15**; domain-validation reuse is capped the same way (200 → 100 → 10 days). Manual annual certs are dead. **Automate renewal or accept guaranteed outages.**
+
+Decision: how does the CA prove you control the domain?
+
+| Challenge | Use when | Cost |
+| --- | --- | --- |
+| **HTTP-01** | Single host, port 80 reachable, no wildcard | Simplest; needs inbound :80 |
+| **DNS-01** | Wildcard cert, or port 80 closed, or cert issued off-box | Needs API access to write a `_acme-challenge` TXT |
+
+Rules, each with the failure it prevents:
+
+- **Add a CAA record that allows your CA *first*.** `0 issue "letsencrypt.org"`. Wildcards need the separate `issuewild` tag. A CAA that omits your CA makes ACME fail with a CAA error before any cert is issued (RFC 8659).
+- **Serve the full chain, not the leaf.** A leaf-only config validates in browsers (they cache intermediates) but fails on `curl` and mobile — the classic "works on my machine" TLS bug. Serve `fullchain.pem`.
+- **Use the ACME staging environment to test.** Let's Encrypt allows **50 certs per registered domain per rolling 7 days**; burning that on retries locks you out for a week. Renewals recognized via ARI (ACME Renewal Info) are exempt from the limit.
+- **Prefer platform-managed certs when the host offers them.** Vercel/Netlify/Cloudflare provision and renew automatically once the record resolves — don't hand-roll certbot on top.
+
+certbot/acme.sh recipes, wildcard via DNS-01, Cloudflare Full vs Full(strict), and the renewal-automation + ARI detail are in `references/tls-and-acme.md`.
+
+## Verify it
+
+Query the authoritative answer and the wire, never your local cache.
+
+```bash
+dig +short app.example.com                      # the resolved record, your resolver's view
+dig +trace example.com                          # full delegation chain from the root — spot stale NS
+dig @ns1.provider.net example.com A             # ask the authoritative NS directly
+dig CAA example.com +short                       # confirm the CA you use is allowed
+openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
+  | openssl x509 -noout -subject -issuer -dates  # served chain subject/issuer + validity window
+curl -vI https://example.com 2>&1 | grep -Ei 'HTTP/|location|SSL certificate'  # status + redirect + cert verdict
+```
+
+Propagation is governed by **TTL, not a fixed 48 hours** (RFC 2181). To make a change land fast, lower the record's TTL (e.g. to 300s) *before* you change it, so resolvers re-query sooner. NS/registrar delegation changes can still lag because of registry/TLD TTLs.
+
+`scripts/verify.sh <domain>` runs the whole done-check read-only: apex-CNAME check, CAA sanity, chain completeness + expiry, HTTPS reachability, www↔apex canonical. The full dig/openssl/curl playbook and an error → cause → fix table are in `references/verify-and-debug.md`.
+
+## Nameserver cutover (no downtime)
+
+Order matters; each step has a reason.
+
+1. **24–48h ahead, lower the TTL** on every record at the current provider (300s). Resolvers will pick up the new zone quickly when you flip.
+2. **Pre-stage every record at the new provider** — copy A/AAAA/CNAME/MX/TXT/CAA exactly. A missed MX row = lost mail the moment NS flips.
+3. **Flip the NS records at the registrar** to the new provider's nameservers. This is the only switch; the zone is already correct on the other side.
+4. **Verify authoritatively** with `dig +trace` and `dig @<new-ns>` until the new NS answer is global. Don't trust your browser.
+5. **Once stable, raise TTLs back up** (3600–86400s) to cut query load.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| CNAME at the apex | Illegal per spec; kills SOA/NS, MX, and other apex records | ALIAS/flattening or hard A/AAAA at apex |
+| "Wait 48 hours" for propagation | Propagation is the TTL; you're just guessing | Lower TTL before change; verify with `dig +trace` |
+| Confirming a change in your browser | Local/OS resolver cache lies for the old TTL | Query authoritative NS or `@1.1.1.1` |
+| Manual yearly cert renewal | Max lifetime is 200d now, 47d by 2029 — it *will* expire | ACME auto-renew or platform-managed TLS |
+| Issuing certs with no CAA / wrong CAA | ACME fails with a CAA error before issuance | `CAA 0 issue "<your-ca>"`; add `issuewild` for wildcards |
+| Serving the leaf cert only | Browsers cache intermediates; curl/mobile break | Serve `fullchain.pem` |
+| Splitting one zone across two providers | Resolvers answer from whichever NS won; records vanish intermittently | One authoritative provider per zone |
+| TTL left at 86400 during migration | Old answer cached for a day after you flip | Drop to 300s a day ahead |
+| Testing certs against ACME production | Burns the 50-cert/7-day limit; week-long lockout | Use the staging endpoint first |

package/skills/shared/domains-dns/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — domains-dns
+
+These cases exercise the skill's routing and coverage. `should_trigger` lists prompts the
+`domains-dns` skill must claim (pointing a domain at a host, TLS chain debugging, CAA gating,
+expired-cert auto-renew, nameserver cutover, the SPF/DKIM/DMARC *rows*), including a non-obvious
+symptom (`dig +trace` shows the old IP), an error-string trigger (`NET::ERR_CERT_AUTHORITY_INVALID`),
+and a Spanish phrasing. `should_not_trigger` lists adjacent prompts that must route elsewhere
+(email-deliverability, cloudflare, deployment, monitoring, vercel) — each names the real sibling it
+belongs to. The `capability` case checks the body actually produces a correct apex+www+TLS+CAA setup
+with the right verification and cutover discipline.
+
+To run: feed `cases.yaml` to the repo's eval harness, which scores the skill description and body
+against each prompt's expected routing and the capability rubric. To check by hand, read `cases.yaml`
+and confirm `SKILL.md` (plus its references) answers each should_trigger prompt, sends each
+should_not_trigger prompt to the named sibling, and covers every `must_include` item in the
+capability scenario.

package/skills/shared/domains-dns/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: domains-dns
+
+should_trigger:
+  - prompt: "Point example.com and www to my Vercel project with valid HTTPS"
+    why: Core task — apex flattening + www CNAME + auto-TLS; the canonical use of this skill.
+  - prompt: "Users get NET::ERR_CERT_AUTHORITY_INVALID on my site but it loads fine for me, fix it"
+    why: Non-obvious symptom of an incomplete (leaf-only) TLS chain; this skill owns chain debugging.
+  - prompt: "I need a CAA record so only Let's Encrypt can issue certificates for my domain"
+    why: CAA issuance gating is a DNS record concern named directly in the cookbook; non-obvious for many.
+  - prompt: "El certificado SSL caducó y no se renueva solo, ¿cómo lo automatizo?"
+    why: Spanish; expired cert + auto-renewal — the 2026 lifetime reality and ACME automation core to this skill.
+  - prompt: "Migrate DNS from GoDaddy to Cloudflare without downtime"
+    why: Nameserver cutover sequence (lower TTL, pre-stage, flip NS, verify) is a dedicated section here.
+  - prompt: "dig +trace still shows the old IP after I changed the A record yesterday"
+    why: Non-obvious propagation/TTL/authoritative-vs-cache diagnosis owned by the verify playbook.
+  - prompt: "Publish the SPF, DKIM and DMARC records for example.com"
+    why: Boundary case that DOES belong here — the DNS rows that back email, not reputation tuning.
+
+should_not_trigger:
+  - prompt: "My emails keep landing in spam, improve inbox placement and warm up the domain"
+    route_to: email-deliverability
+    why: Reputation, placement, and warmup — not the DNS rows; that is deliverability, not record authoring.
+  - prompt: "Set up a Cloudflare Worker with KV and caching rules"
+    route_to: cloudflare
+    why: Platform/edge feature work, not cross-platform DNS+TLS records.
+  - prompt: "Deploy and autoscale my Node app behind a load balancer"
+    route_to: deployment
+    why: What runs and how it's released, not the name that resolves to it.
+  - prompt: "Add uptime monitoring and cert-expiry alerting for production"
+    route_to: monitoring
+    why: Ongoing alerting practice, not one-time correct setup + verification.
+  - prompt: "Configure my Vercel project's build command and output directory"
+    route_to: vercel
+    why: Platform build configuration, not attaching/resolving the domain.
+
+capability:
+  - scenario: >
+      A user owns a naked domain registered at a registrar and wants both the apex and www serving
+      on Netlify with valid auto-renewing HTTPS, locked so only Let's Encrypt may issue certs.
+    must_include:
+      - Diagnoses in resolution order (name → NS delegation → records → TLS), top-down.
+      - Refuses a CNAME at the apex and uses ALIAS/flattening or hard A/AAAA at the apex instead.
+      - Picks one canonical host (apex or www) and 301-redirects the other.
+      - Provides a CAA record `0 issue "letsencrypt.org"` and notes the separate `issuewild` tag for wildcards.
+      - States the 2026 short-lifetime reality (200d now → 47d by 2029) and relies on platform/ACME auto-renew, not manual certs.
+      - Gives verification commands — `dig +short`/`dig +trace`, `openssl s_client -servername`, `curl -vI`.
+      - Lowers TTL before any cutover and verifies authoritatively, not via browser cache.

package/skills/shared/domains-dns/references/record-cookbook.md

@@ -0,0 +1,94 @@
+# Record cookbook
+
+Per-type reference with the edge cases that bite. Names ending in `.` are fully-qualified; `@` is the zone apex.
+
+## A / AAAA — name to IP
+
+```text
+example.com.   300  A     76.76.21.21
+example.com.   300  AAAA  2606:4700:3033::6815:1a2b
+```
+
+- Publish AAAA only if the origin actually serves IPv6, or you'll hand IPv6 clients a dead address.
+- Round-robin (multiple A rows) is crude load distribution, not failover — resolvers pick arbitrarily and don't health-check.
+
+## CNAME — alias one name to another
+
+```text
+www.example.com.   3600  CNAME  cname.vercel-dns.com.
+```
+
+- **Never at the apex** (RFC 1034 §3.6.2). A CNAME cannot coexist with the SOA/NS that must exist there.
+- A CNAME target should resolve to A/AAAA, not chain endlessly. Avoid CNAME-to-CNAME loops.
+
+## ALIAS / ANAME — apex flattening
+
+Vendor names differ (Cloudflare flattening, Netlify ALIAS, Route 53 alias, DNSimple ALIAS). The provider resolves the target to A/AAAA at query time and returns those, so the apex stays spec-legal.
+
+```text
+example.com.   300  ALIAS  apex-loadbalancer.netlify.app.
+```
+
+- The flattened A/AAAA inherit the *provider's* resolution; if the target changes IP, you don't edit anything.
+
+## MX — mail exchange
+
+```text
+example.com.   3600  MX  1   aspmx.l.google.com.
+example.com.   3600  MX  5   alt1.aspmx.l.google.com.
+```
+
+- The number is **priority**; lower is tried first. Equal priorities load-balance.
+- Targets must be hostnames (A/AAAA), **never IPs and never CNAMEs** (RFC 2181).
+- An apex with no MX falls back to the A record for mail — usually not what you want.
+
+## TXT — SPF / DKIM / DMARC / verification
+
+```text
+example.com.        3600  TXT  "v=spf1 include:_spf.google.com ~all"
+default._domainkey  3600  TXT  "v=DKIM1; k=rsa; p=MIGfMA0GCSq...long-key..."
+_dmarc              3600  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"
+```
+
+- A single TXT string maxes at **255 characters**. Longer values (RSA-2048 DKIM keys) must be split into multiple quoted chunks in one record; the resolver concatenates them: `"chunk1" "chunk2"`.
+- **SPF allows at most 10 DNS lookups** when evaluated; each `include`/`a`/`mx`/`redirect` counts. Blow past it and SPF returns `permerror` (treated as fail). Flatten or trim includes.
+- One SPF record per domain only — a second `v=spf1` TXT is a permerror.
+- The *records* are this skill. Tuning policy, alignment, and reputation is ../email-deliverability/SKILL.md.
+
+## CAA — certificate authority authorization
+
+```text
+example.com.   3600  CAA  0 issue     "letsencrypt.org"
+example.com.   3600  CAA  0 issuewild "letsencrypt.org"
+example.com.   3600  CAA  0 iodef     "mailto:security@example.com"
+```
+
+- `issue` gates normal certs; `issuewild` separately gates wildcards; `iodef` is where CAs report violations.
+- No CAA record = any CA may issue. A CAA listing only CA-X makes ACME from CA-Y fail with a CAA error (RFC 8659).
+- CAA is checked at the apex and walked up; a tight apex policy covers subdomains unless overridden.
+
+## SRV — service location
+
+```text
+_sip._tcp.example.com.   3600  SRV  10 5 5060 sip.example.com.
+#                                     |  | |    target
+#                          priority --+  | +-- port
+#                               weight --+
+```
+
+- Format: `priority weight port target`. Lower priority first; weight distributes within equal priority.
+- Name must be `_service._proto`. Target is a hostname, not an IP.
+
+## NS / SOA — delegation and zone metadata
+
+- The apex's `NS` records name the authoritative servers; the registrar's delegation must match them or queries `SERVFAIL`/go stale.
+- `SOA` holds the zone serial and timers. Bump the serial on every edit if you run your own primary, or secondaries won't pull the change.
+
+## PTR / reverse DNS
+
+- PTR lives in the *IP owner's* reverse zone (`x.x.x.x.in-addr.arpa`), set by your hosting provider, not in your forward zone. Mail servers are judged on matching forward/reverse — set it via the host's panel.
+
+## DNSSEC
+
+- DNSSEC signs answers so resolvers can detect tampering. You enable signing at the DNS provider, then publish the resulting **DS record at the registrar** (parent zone) to complete the chain of trust.
+- Common failure: enabling signing but forgetting the DS at the registrar (or a stale DS after a key roll) → `SERVFAIL` for validating resolvers. When migrating providers, turn DNSSEC **off**, cut over, then re-enable — a mismatched DS during cutover breaks the whole zone.