rsc-universal 0.1.1

package/skills/document-processing/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static guardrail for document-processing skill content.
+#
+# WHAT IT DOES (read-only; never edits, moves, runs, or installs anything)
+#   Network-free, dependency-free static checks over a target file or
+#   directory of skill content (defaults to the SKILL.md next to this script).
+#   It does NOT execute any PDF/OCR library — it only greps the text:
+#     1. No dead `import PyPDF2` / `from PyPDF2` — must use the maintained
+#        `pypdf` import.                                            (FAIL)
+#     2. Every form-fill call (`update_page_form_field_values`) sits in a
+#        file that also sets `auto_regenerate=False`.               (FAIL)
+#     3. The OCR guidance names BOTH a local engine (docling/marker/
+#        tesseract) AND the hosted option (mistral).                (FAIL)
+#     4. Code fences are language-tagged (no bare ``` opening a block). (WARN)
+#     5. references/engines.md exists alongside the skill.          (WARN)
+#
+#   Checks 1-3 are hard failures. 4-5 are warnings (don't fail) unless
+#   --strict. An empty / content-free / non-skill target exits 0 — never a
+#   false failure on nothing.
+#
+# HOW TO RUN
+#   bash scripts/verify.sh                 # checks ../SKILL.md by default
+#   bash scripts/verify.sh path/to/SKILL.md
+#   bash scripts/verify.sh path/to/dir/    # checks every *.md under dir
+#   bash scripts/verify.sh --strict ...    # treat warnings as failures
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/non-skill target
+#   1  a hard failure — or any warning under --strict
+#   2  bad usage (target does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -u
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+fail_count=0; warn_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+STRICT=0
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) sed -n '2,46p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --strict)  STRICT=1; shift ;;
+    -*) printf 'unknown option: %s\n' "$1" >&2; exit 2 ;;
+    *)  if [ -z "$TARGET" ]; then TARGET="$1"; fi; shift ;;
+  esac
+done
+
+# Default target: the SKILL.md beside this script's directory.
+if [ -z "$TARGET" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  TARGET="$SCRIPT_DIR/../SKILL.md"
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf 'no such target: %s\n' "$TARGET" >&2
+  exit 2
+fi
+
+# Build the list of files to inspect.
+FILES=""
+if [ -d "$TARGET" ]; then
+  FILES="$(find "$TARGET" -name '*.md' -type f 2>/dev/null)"
+  DIR_ROOT="$TARGET"
+else
+  FILES="$TARGET"
+  DIR_ROOT="$(cd "$(dirname "$TARGET")" && pwd)"
+fi
+
+# Nothing with content -> exit 0, no false failure.
+HAS_CONTENT=0
+for f in $FILES; do
+  if [ -s "$f" ] && grep -q '[^[:space:]]' "$f"; then HAS_CONTENT=1; fi
+done
+if [ "$HAS_CONTENT" -eq 0 ]; then
+  ok "empty or content-free target: nothing to verify"
+  exit 0
+fi
+
+# --- 1. No dead PyPDF2 import ----------------------------------------------
+# Only flag a real import line in CODE: skip Markdown table rows (lines
+# starting with '|', where it may be cited as the bad example to AVOID) and
+# inline-code mentions wrapped in backticks within prose.
+PYPDF2_HITS="$(grep -REn 'import[[:space:]]+PyPDF2|from[[:space:]]+PyPDF2' $FILES 2>/dev/null \
+  | grep -vE ':[[:space:]]*\|' \
+  | grep -vE '`[^`]*PyPDF2' || true)"
+if [ -n "$PYPDF2_HITS" ]; then
+  fail "found a PyPDF2 import in code — use the maintained 'pypdf' instead"
+  printf '%s\n' "$PYPDF2_HITS" | sed 's/^/        /'
+else
+  ok "no dead PyPDF2 import in code"
+fi
+
+# --- 2. Form fills set auto_regenerate=False -------------------------------
+for f in $FILES; do
+  if grep -q 'update_page_form_field_values' "$f"; then
+    if grep -q 'auto_regenerate[[:space:]]*=[[:space:]]*False' "$f"; then
+      ok "form-fill in $(basename "$f") sets auto_regenerate=False"
+    else
+      fail "$(basename "$f") fills a form but never sets auto_regenerate=False (spurious 'save changes' prompt)"
+    fi
+  fi
+done
+
+# --- 3. OCR names a local AND a hosted engine ------------------------------
+ALLTEXT="$(cat $FILES 2>/dev/null)"
+if printf '%s' "$ALLTEXT" | grep -qiE 'ocr'; then
+  has_local=0; has_hosted=0
+  printf '%s' "$ALLTEXT" | grep -qiE 'docling|marker|tesseract' && has_local=1
+  printf '%s' "$ALLTEXT" | grep -qiE 'mistral' && has_hosted=1
+  if [ "$has_local" -eq 1 ] && [ "$has_hosted" -eq 1 ]; then
+    ok "OCR guidance names a local engine and the hosted Mistral option"
+  else
+    [ "$has_local" -eq 0 ] && fail "OCR section names no local engine (docling/marker/tesseract)"
+    [ "$has_hosted" -eq 0 ] && fail "OCR section names no hosted option (mistral)"
+  fi
+fi
+
+# --- 4. Code fences are language-tagged (warn) -----------------------------
+for f in $FILES; do
+  # Count fence lines; a bare ``` that OPENS a block (odd-indexed) is untagged.
+  # We approximate: any line that is exactly ``` may be a close OR a bad open.
+  # Flag files where a ``` opener has no language by tracking parity.
+  awk '
+    /^```/ {
+      if (inblock == 0) {
+        # opening fence: must have a language after the backticks
+        if ($0 ~ /^```[[:space:]]*$/) { bad++ }
+        inblock = 1
+      } else {
+        inblock = 0
+      }
+    }
+    END { exit (bad > 0 ? 1 : 0) }
+  ' "$f" || warn "$(basename "$f") has an untagged code fence (bare \`\`\`) — tag the language"
+done
+[ "$warn_count" -eq 0 ] && ok "code fences appear language-tagged"
+
+# --- 5. references/engines.md exists (warn) --------------------------------
+if [ -d "$TARGET" ]; then
+  REF_DIR="$TARGET/references"
+else
+  REF_DIR="$DIR_ROOT/references"
+fi
+if [ -f "$REF_DIR/engines.md" ]; then
+  ok "references/engines.md present"
+else
+  warn "references/engines.md not found at $REF_DIR — install/licensing depth is expected there"
+fi
+
+# --- Summary ---------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then
+  printf '%s0 failures but %d warning(s) under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 1
+fi
+printf '%spassed: 0 failures, %d warning(s)%s\n' "$GREEN" "$warn_count" "$NC"
+exit 0

package/skills/domains-dns/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: domains-dns
+description: "Use when pointing a custom domain at a host, fixing broken HTTPS, choosing apex vs www, or publishing DNS rows — registering/delegating a name, writing A/AAAA/CNAME/ALIAS/MX/TXT/CAA/SRV records, standing up auto-renewing TLS, or cutting nameservers over without downtime. Triggers: 'point example.com at Vercel', 'set up DNS for the domain', 'NET::ERR_CERT_AUTHORITY_INVALID', 'CNAME flattening / ALIAS at the apex', 'dig +trace still shows the old IP', 'need a CAA record for Let's Encrypt', 'publish the SPF/DKIM/DMARC/MX rows', 'apuntar el dominio', 'el certificado caducó y no renueva', 'configurar els registres DNS'. NOT inbox placement / warmup / spam-rate tuning (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: risco
+---
+
+# 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.
+
+Verification checklist before you call it done:
+
+- [ ] `dig +short` returns the intended IP/host from a public resolver (`@1.1.1.1`).
+- [ ] Apex resolves via A/AAAA or ALIAS, **never** a CNAME.
+- [ ] `dig CAA` lists the CA that issued (or is empty — open policy).
+- [ ] `openssl s_client` shows the right subject, a complete chain, and `notAfter` comfortably ahead.
+- [ ] `curl -vI` returns 2xx/3xx with no cert warning; www and apex land on the one canonical host.
+
+## 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 |
+
+## References & siblings
+
+- `references/record-cookbook.md` — every record type with edge cases (TXT chunking, MX priority, SPF lookup limit, SRV, DNSSEC).
+- `references/tls-and-acme.md` — certbot/acme.sh, HTTP-01 vs DNS-01, wildcards, platform cert quirks, 2026 lifetimes + ARI.
+- `references/verify-and-debug.md` — full dig/openssl/curl playbook and error → cause → fix.
+- `scripts/verify.sh <domain>` — read-only audit: apex-CNAME check, CAA sanity, chain completeness + expiry, HTTPS reachability, www↔apex canonical.
+
+Route out when the ask isn't the records: inbox placement → ../email-deliverability/SKILL.md; what runs behind the name and how it's released → ../deployment/SKILL.md; platform-specific edge/build config → ../cloudflare/SKILL.md or ../vercel/SKILL.md.

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

package/skills/domains-dns/references/tls-and-acme.md

@@ -0,0 +1,90 @@
+# TLS & ACME
+
+## The 2026 lifetime schedule
+
+The CA/Browser Forum (ballot SC-081v3, voting closed 2025-04-11) ratcheted the **maximum public-TLS certificate lifetime** down on a fixed timeline. Domain-validation (DCV) reuse shrinks in lockstep.
+
+| Effective | Max cert lifetime | Max DCV reuse |
+| --- | --- | --- |
+| 2026-03-15 | 200 days | 200 days |
+| 2027-03-15 | 100 days | 100 days |
+| 2029-03-15 | 47 days | 10 days |
+
+Consequence: a human renewing once a year cannot keep up. Every cert path must auto-renew. Let's Encrypt's own default lifetime is moving 90 → 64 → 45 days across 2025–2026, ahead of the CA/B floor.
+
+## HTTP-01 vs DNS-01
+
+| | HTTP-01 | DNS-01 |
+| --- | --- | --- |
+| Proof | Serve a token at `http://host/.well-known/acme-challenge/...` | Publish a `_acme-challenge` TXT |
+| Needs | Inbound port 80 on the host | API access to the DNS zone |
+| Wildcards | No | **Yes — wildcards require DNS-01** |
+| Off-box issuance | No (must answer on the host) | Yes (issue anywhere) |
+
+Pick DNS-01 when you need `*.example.com`, when port 80 is closed, or when the cert is issued somewhere other than the serving host.
+
+## certbot (HTTP-01, single host)
+
+```bash
+# Test against STAGING first so retries don't burn the production rate limit.
+certbot certonly --standalone \
+  --staging \
+  -d example.com -d www.example.com \
+  --agree-tos -m admin@example.com --non-interactive
+
+# Then production once the dry run is clean:
+certbot certonly --standalone \
+  -d example.com -d www.example.com \
+  --agree-tos -m admin@example.com --non-interactive
+```
+
+certbot installs a systemd timer (`certbot.timer`) or cron entry that renews automatically. Verify it:
+
+```bash
+systemctl list-timers | grep certbot
+certbot renew --dry-run        # exercises the full renewal path without issuing
+```
+
+## acme.sh (DNS-01, wildcard)
+
+```bash
+# DNS-01 via the provider's API (Cloudflare token in env) for a wildcard.
+export CF_Token="..."; export CF_Account_ID="..."
+acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --staging
+acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'   # production
+```
+
+acme.sh registers its own cron renewal on install. Always serve the **fullchain**, not the leaf.
+
+## Serve the full chain
+
+```nginx
+ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;  # leaf + intermediates
+ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+```
+
+A leaf-only config validates in browsers (they cache intermediates from prior sites) and fails on `curl`, mobile, and fresh clients. Always point at `fullchain.pem`.
+
+## Rate limits & ARI
+
+- Let's Encrypt: **50 certificates per registered domain per rolling 7 days**, counted globally across all your ACME accounts.
+- **Renewals recognized via ARI (ACME Renewal Info) are exempt** from the limit, so well-behaved auto-renewal never trips it.
+- Testing/CI loops must hit the **staging** endpoint, or one bad loop locks you out for a week.
+
+## Platform-managed certs
+
+Let the host do it when it can — Vercel, Netlify, and Cloudflare provision and renew automatically once the DNS record resolves to them. Do not stack certbot on top.
+
+- **Cloudflare SSL mode** matters: *Flexible* terminates TLS at the edge and talks plaintext to your origin (insecure, can loop-redirect). *Full* encrypts edge↔origin but doesn't validate the origin cert. *Full (strict)* validates it — use Full (strict) in production with a real or Cloudflare Origin cert.
+- The apex must flatten (see record-cookbook.md) before any of these can validate.
+
+## Cert error → cause → fix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ERR_CERT_AUTHORITY_INVALID` on curl/mobile but OK in browser | Leaf-only chain, missing intermediate | Serve `fullchain.pem` |
+| `ERR_CERT_COMMON_NAME_INVALID` / name mismatch | Cert doesn't cover the hostname (e.g. apex cert, www request) | Add the SAN; reissue covering both names |
+| ACME fails with a CAA error | CAA omits your CA, or wildcard lacks `issuewild` | Add `CAA 0 issue "<ca>"` (+ `issuewild` for `*`) |
+| Cert valid but site still warns | Mixed content (HTTP assets on an HTTPS page) | Serve all assets over HTTPS |
+| Expired cert in prod | No working auto-renew | Fix the timer/cron; `certbot renew --dry-run` |
+| Rate-limit / "too many certificates" | Tested against production repeatedly | Use staging; rely on ARI-aware renewal |

package/skills/domains-dns/references/verify-and-debug.md

@@ -0,0 +1,64 @@
+# Verify & debug playbook
+
+Always query the authoritative answer and the wire. Your laptop's resolver caches the old answer for the record's full TTL and will lie to you.
+
+## dig — resolution
+
+```bash
+dig +short app.example.com                 # what your resolver returns right now
+dig +short app.example.com @1.1.1.1         # what a public resolver returns (bypasses local cache)
+dig +trace example.com                      # walk root → TLD → authoritative; reveals stale/wrong NS
+dig NS example.com +short                   # the delegated nameservers
+dig @ns1.provider.net example.com A +short  # ask the authoritative NS directly — the source of truth
+dig CAA example.com +short                  # CA authorization at the apex
+dig TXT _dmarc.example.com +short           # confirm a TXT row took
+```
+
+- `dig +short` shows the resolved value; drop `+short` to see the TTL counting down (low number = recently changed or short TTL).
+- If `dig @<authoritative>` is correct but `dig +short` is wrong, it's **caching** — wait out the TTL or query a fresh resolver. Don't re-edit the record.
+
+## openssl — the served chain
+
+```bash
+openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
+  | openssl x509 -noout -subject -issuer -dates
+```
+
+- `-servername` sends SNI; without it a multi-tenant host serves the wrong/default cert and you misdiagnose.
+- Check `notAfter` is comfortably ahead. Check `issuer` matches your CAA.
+- To see whether the **chain is complete**, look at the full handshake output for the intermediate; an incomplete chain is the curl/mobile-only failure.
+
+## curl — the HTTP verdict
+
+```bash
+curl -vI https://example.com 2>&1 | grep -Ei 'HTTP/|location|SSL certificate'
+curl -sI https://www.example.com -o /dev/null -w '%{http_code} %{redirect_url}\n'
+```
+
+- `SSL certificate verify ok` = chain validates from curl's bundle (catches missing intermediates browsers hide).
+- Confirm www and apex resolve to the same canonical host and one 301s to the other.
+
+## Propagation, the right way
+
+Propagation is the **TTL**, not a fixed window (RFC 2181). To make a change land fast:
+
+1. Lower the record's TTL to 300s **before** you change the value.
+2. Wait for the old TTL to elapse so resolvers re-query at the new rate.
+3. Change the value; new value is picked up within ~5 min.
+4. Raise the TTL back afterward.
+
+NS/registrar delegation changes can lag longer because of registry/TLD TTLs — that's the parent zone, outside your control.
+
+## Error → cause → fix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `NXDOMAIN` | Name doesn't exist in the zone, or wrong zone is authoritative | Confirm record exists; `dig NS` that delegation points at the right provider |
+| `SERVFAIL` | Broken delegation, or DNSSEC DS mismatch | Match registrar NS to provider; fix/remove stale DS |
+| `dig +short` right but browser wrong | Local/OS/browser cache | Flush OS cache or query `@1.1.1.1`; wait the TTL |
+| `dig +trace` shows old IP | Authoritative zone not updated, or queried a stale secondary | Edit at the authoritative provider; bump SOA serial |
+| `ERR_CERT_AUTHORITY_INVALID` (curl/mobile) | Incomplete chain | Serve `fullchain.pem` |
+| `ERR_CERT_COMMON_NAME_INVALID` | Cert SAN doesn't cover the hostname | Reissue covering apex + www |
+| ACME CAA error | CAA forbids your CA | Add `CAA 0 issue "<ca>"` |
+| HTTPS warns despite valid cert | Mixed content | Serve all subresources over HTTPS |
+| Redirect loop on HTTPS | Cloudflare SSL set to Flexible against an HTTPS origin | Set Full (strict) |