rsc-universal 0.1.1

package/skills/vector-db/scripts/verify.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — vector-db skill gate. A HEURISTIC config linter, not a live DB check.
+#
+# Usage:  scripts/verify.sh [FILE ...]
+#   FILE = a produced artifact (index DDL, collection schema, query). With no args it scans
+#   the current directory for *.sql / *.py / *.json / *.md artifacts that mention a vector
+#   store. Read-only; never connects to anything; never writes.
+#
+# Exit code: non-zero ONLY on a hard violation (metric mismatch, selective filter with no
+# index/iterative-scan, ef_construction < 2*m). Missing recall mention is advisory. An empty or
+# clean target exits 0 — no false failure.
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays, arrays pre-initialised.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# ---- collect target files -------------------------------------------------
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for f in "$@"; do
+    [ -f "$f" ] && FILES+=("$f") || note "not a file, skipping: $f"
+  done
+else
+  ROOT="$(pwd)"
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+      -type f \( -name '*.sql' -o -name '*.py' -o -name '*.json' -o -name '*.md' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  ok "no artifacts to check — clean"
+  exit 0
+fi
+
+# Keep only files that actually look like a vector-store artifact, so a generic repo scan does
+# not produce noise. A clean (non-matching) set still exits 0.
+TARGETS=()
+for f in "${FILES[@]}"; do
+  if grep -Eiq 'vector\(|halfvec|hnsw|ivfflat|<=>|<->|<#>|create_collection|VectorParams|create_index\(|ServerlessSpec|pinecone|qdrant|weaviate|vector_cosine_ops|vector_l2_ops|vector_ip_ops' "$f" 2>/dev/null; then
+    TARGETS+=("$f")
+  fi
+done
+
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  ok "no vector-store artifacts detected — nothing to lint"
+  exit 0
+fi
+
+# ---- per-file heuristics --------------------------------------------------
+for f in "${TARGETS[@]}"; do
+  printf -- '--- %s\n' "$f"
+
+  has_cosine_ops=$(grep -Eic 'vector_cosine_ops|halfvec_cosine_ops|<=>|metric *= *.?cosine|Distance\.COSINE' "$f" 2>/dev/null || true)
+  has_l2_ops=$(grep -Eic 'vector_l2_ops|halfvec_l2_ops|<->|metric *= *.?(l2|euclidean)|Distance\.EUCLID' "$f" 2>/dev/null || true)
+  mentions_cosine_model=$(grep -Eic 'text-embedding-3|cohere|sentence-transformers|all-MiniLM|bge-|e5-|gte-|normaliz' "$f" 2>/dev/null || true)
+
+  # 1) Metric mismatch: a cosine-implying model but only L2 ops, no cosine ops anywhere.
+  if [ "$mentions_cosine_model" -gt 0 ] && [ "$has_l2_ops" -gt 0 ] && [ "$has_cosine_ops" -eq 0 ]; then
+    err "metric mismatch: artifact names a cosine-style model but indexes/queries with L2 (<->). Use cosine (<=> / vector_cosine_ops)."
+  fi
+
+  # 2) Selective filter with no index on the field and no iterative scan.
+  has_filter=$(grep -Eic 'WHERE |filter=|Filter\(|filters=|MatchValue|"\$eq"' "$f" 2>/dev/null || true)
+  has_field_index=$(grep -Eic 'create_payload_index|CREATE INDEX|payload_index|btree|gin' "$f" 2>/dev/null || true)
+  has_iter_scan=$(grep -Eic 'iterative_scan|relaxed_order|strict_order' "$f" 2>/dev/null || true)
+  is_pgvector=$(grep -Eic 'vector\(|halfvec|hnsw|ivfflat|<=>|<->|<#>' "$f" 2>/dev/null || true)
+  if [ "$has_filter" -gt 0 ] && [ "$has_field_index" -eq 0 ]; then
+    if [ "$is_pgvector" -gt 0 ] && [ "$has_iter_scan" -eq 0 ]; then
+      err "selective filter present but no index on the filter field AND no iterative_scan — pgvector will drop rows / scan."
+    else
+      note "filter present but no obvious index on the filter field — confirm the field is indexed."
+    fi
+  fi
+
+  # 3) IVFFlat + selective filter without iterative scan = deprecated foot-gun.
+  has_ivfflat=$(grep -Eic 'ivfflat' "$f" 2>/dev/null || true)
+  if [ "$has_ivfflat" -gt 0 ] && [ "$has_filter" -gt 0 ] && [ "$has_iter_scan" -eq 0 ]; then
+    err "IVFFlat used with a selective filter and no iterative_scan — drops rows; prefer HNSW + hnsw.iterative_scan='relaxed_order'."
+  fi
+
+  # 4) HNSW ef_construction >= 2*m invariant (only when both are literally present).
+  m_val=$(grep -Eio 'm *= *[0-9]+' "$f" 2>/dev/null | grep -Eo '[0-9]+' | head -1 || true)
+  efc_val=$(grep -Eio 'ef_construction *= *[0-9]+' "$f" 2>/dev/null | grep -Eo '[0-9]+' | head -1 || true)
+  if [ -n "$m_val" ] && [ -n "$efc_val" ]; then
+    if [ "$efc_val" -lt $(( 2 * m_val )) ]; then
+      err "ef_construction ($efc_val) < 2*m ($((2*m_val))) — weak HNSW graph; recall needs a full rebuild to fix."
+    fi
+  fi
+
+  # 5) Recall / search-time knob mentioned somewhere (advisory).
+  has_recall=$(grep -Eic 'ef_search|hnsw_ef|recall|brute.?force|baseline|probes|[^a-z]ef *=' "$f" 2>/dev/null || true)
+  if [ "$has_recall" -eq 0 ]; then
+    note "no recall / ef_search (or engine equivalent) mention — confirm recall was measured before shipping."
+  fi
+done
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "no hard violations"
+fi
+exit "$EXIT"

package/skills/vercel/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: vercel
+description: "Use when operating an already-chosen Vercel project from the CLI or vercel.json/vercel.ts — deploying preview vs production, debugging builds, pushing/pulling env vars across production/preview/development, attaching custom domains, configuring functions (runtime, maxDuration, regions), crons, rewrites/redirects/headers, and deployment protection. Triggers: 'deploy to Vercel', 'vercel --prod', 'my function timed out at 10s', 'vercel env pull doesn't update .env.local', 'should I still use Edge Functions', 'set maxDuration', 'add a cron on Vercel', 'desplega a Vercel', 'configura les variables d'entorn a Vercel', 'configurar un cron en Vercel'. NOT host choice / Docker / CI (that is deployment), NOT Next.js app code or next.config.js (that is nextjs), NOT DNS records / registrar transfers (that is domains-dns)."
+tags: [vercel, deploy, serverless, edge, env-vars]
+recommends: [deployment, nextjs, domains-dns]
+origin: risco
+---
+
+# Vercel, operated
+
+The operator's manual for a project that already lives on Vercel: the commands you run and the
+config keys you set, with the 2025-2026 platform baked in — **Fluid compute on by default**, and
+**Edge Functions deprecated** (folded into Vercel Functions). Every claim here maps to a CLI command
+or a `vercel.json` key, not vibes.
+
+This skill assumes the host decision is settled. If you are still asking *where* to run, or you need
+a Dockerfile / CI pipeline, that is `../deployment/SKILL.md`. If you are writing the app's route
+handlers or `next.config.js`, that is `../nextjs/SKILL.md`.
+
+```text
+git push branch ──────────────▶ preview deployment (unique URL, protected on Hobby)
+vercel              ───────────▶ preview deployment from your machine
+vercel --prod       ───────────▶ production domain
+vercel dev          ───────────▶ local emulation of functions + routing
+                    config:  vercel.json (static)  |  vercel.ts (generated at build time)
+                    env:     scoped per environment  →  production / preview / development
+```
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Linking a repo (`vercel link`), deploying (`vercel`, `vercel --prod`), or debugging a build.
+- Authoring or fixing `vercel.json` / `vercel.ts`: `functions`, `crons`, `rewrites`, `redirects`,
+  `headers`, `regions`, `cleanUrls`, `trailingSlash`, `framework`, `buildCommand`.
+- Managing env vars across the three environments: `vercel env add|pull|ls`, `.env.local`, sensitive
+  vars, `vercel env pull` round-trips that "don't update".
+- Attaching a custom domain (`vercel domains add`), aliasing, deployment protection scopes.
+- Setting function `maxDuration` / `regions`, choosing edge vs Node runtime, configuring crons.
+- Reading `VERCEL_ENV`, `VERCEL_URL`, `VERCEL_GIT_*` inside the running app.
+
+**When NOT to use:**
+
+- "Vercel vs Hetzner vs Coolify, Dockerfile, GitHub Actions CI" → `../deployment/SKILL.md`. That skill
+  owns the host *choice* and containers; this one operates the chosen Vercel project.
+- Next.js application code, App Router, RSC, `next.config.js`, ISR logic → `../nextjs/SKILL.md`.
+  This skill only touches the Vercel-side knobs (function config, env, ISR-as-a-function).
+- Raw DNS records, registrar transfers, nameserver theory → `../domains-dns/SKILL.md`. Here we cover
+  only the `vercel domains` / `vercel dns` CLI surface for attaching a domain to a project.
+- A different platform (Netlify, Railway, Render, Fly, Cloudflare) → its own sibling. For Cloudflare
+  Pages/Workers, see `../cloudflare/SKILL.md`.
+
+## Mental model
+
+Three facts make Vercel predictable:
+
+1. **A deployment is immutable and tied to one environment.** `git push` to a branch → a preview;
+   `vercel --prod` (or a push to the production branch) → production. You never "edit" a deployment;
+   you ship a new one and the domain points at it.
+2. **Env vars are scoped, not global.** A var exists in some subset of `{production, preview,
+   development}`. Pulling for the wrong environment is the #1 "my var is missing locally" cause.
+3. **Config has two front doors with identical keys.** `vercel.json` is static; `vercel.ts` runs at
+   build time and can compute the same properties from env vars or an API call. Pick `vercel.json`
+   unless you genuinely need to generate config.
+
+## First contact — which path
+
+| Situation | Do this |
+| --- | --- |
+| New project, never linked | `vercel link` (or first `vercel` run prompts to set it up), then `vercel` for a preview |
+| Existing repo, just deploying | `vercel` for a preview URL, `vercel --prod` when ready |
+| Only need the prod env vars locally | `vercel env pull .env.local` (see env section — pick the env) |
+| Only attaching a domain | jump to Domains: `vercel domains add example.com` |
+| Build failing | `vercel --prod --debug`, then read the build log; check `buildCommand`/`installCommand`/`framework` in `vercel.json` |
+| Function times out | not a deploy bug — set `maxDuration` (and confirm your plan's ceiling) in `functions` |
+
+## Deploy & build
+
+```bash
+vercel                 # deploy a PREVIEW from the current dir, prints a unique URL
+vercel --prod          # deploy to the PRODUCTION domain
+vercel dev             # run functions + routing locally (emulates the platform)
+vercel link            # associate this dir with a Vercel project (.vercel/ created)
+vercel pull            # fetch project settings + env into .vercel/.env.* for local builds
+vercel --prod --debug  # same prod deploy with verbose build output for debugging
+```
+
+Skip redundant builds with `ignoreCommand` — Vercel runs it and **cancels the build when it exits
+`0`** (yes, zero means skip). Useful in a monorepo where most pushes don't touch this project:
+
+```json
+{ "ignoreCommand": "git diff --quiet HEAD^ HEAD -- ." }
+```
+
+Bad → Good, the one that bites everyone:
+
+```bash
+# Bad: secrets committed so the build can read them
+echo "STRIPE_SECRET=sk_live_..." >> .env && git add .env && git commit
+
+# Good: secret lives in Vercel, never in git; pulled only for local dev
+vercel env add STRIPE_SECRET production
+vercel env pull .env.local        # .env.local is gitignored by Next/Vite defaults
+```
+
+## Environments & env vars
+
+Why scoping matters: the same key holds different values in `production`, `preview`, and
+`development`, and the CLI treats `development` specially.
+
+```bash
+vercel env ls                          # list which vars exist in which environments
+vercel env add API_URL production      # add to production (prompts for the value)
+vercel env add API_URL preview         # separate command for preview
+vercel env pull .env.local             # writes vars for the local-linked env into .env.local
+vercel env pull .env.local --environment=preview   # pull a SPECIFIC environment
+vercel env run -- npm run seed         # run a command with the project's vars injected
+```
+
+Gotchas, each with the reason:
+
+- **You cannot add `development` in the same command as `production`/`preview`.** The API rejects
+  mixing the dev environment with the others — run a second `vercel env add … development`. (Run
+  `vercel env add` with no args for the interactive picker.)
+- **`vercel env add` for production/preview/custom defaults the var to *sensitive*** (write-only;
+  you can't read it back, only overwrite). Fine for secrets, surprising for plain config.
+- **"`vercel env pull` doesn't update my `.env.local`"** is almost always the *environment*: pull
+  defaults to the linked environment (usually development). Pass `--environment=preview` (or
+  `production`) to get the values you actually mean. It overwrites the target file, so re-pull after
+  you change a var in the dashboard.
+- **Browser-exposed vars need the framework prefix.** Anything reachable in client code must be
+  prefixed (`NEXT_PUBLIC_` for Next.js, `VITE_` for Vite). No prefix → server-only. Never prefix a
+  secret.
+
+System vars are read-only and prefixed `VERCEL_` — read them in the app, never set them:
+
+```ts
+const env = process.env.VERCEL_ENV        // 'production' | 'preview' | 'development'
+const url = process.env.VERCEL_URL        // deployment host, no protocol
+const branch = process.env.VERCEL_GIT_COMMIT_REF  // git branch that triggered the deploy
+```
+
+Checklist — "my var isn't showing up locally":
+
+1. `vercel env ls` — does the var exist in the environment you expect?
+2. Re-run `vercel env pull .env.local --environment=<env>` (it overwrites, doesn't merge).
+3. Browser code? Confirm the framework prefix (`NEXT_PUBLIC_`/`VITE_`).
+4. Dev server reads `.env.local` at boot — restart it.
+
+## vercel.json essentials
+
+Add the `$schema` line first — you get editor autocomplete and validation for free.
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "functions": {
+    "api/**/*.ts": {
+      "maxDuration": 30,
+      "regions": ["fra1"]
+    }
+  },
+  "crons": [{ "path": "/api/digest", "schedule": "0 * * * *" }],
+  "redirects": [{ "source": "/old", "destination": "/new", "permanent": true }],
+  "rewrites": [{ "source": "/proxy/:path*", "destination": "https://api.example.com/:path*" }],
+  "headers": [
+    { "source": "/(.*)", "headers": [{ "key": "X-Frame-Options", "value": "DENY" }] }
+  ],
+  "cleanUrls": true
+}
+```
+
+Whys:
+
+- **`maxDuration`** caps wall-clock per invocation. Defaults/ceilings are plan-bound (Hobby 60s, Pro
+  300s, Enterprise 900s). Setting `30` on Hobby is fine; setting `300` on Hobby silently can't apply.
+- **No `memory` key here when Fluid is on** (default for new projects since 2025-04-23). Under Fluid,
+  default function memory/CPU is a *dashboard* setting, not a `vercel.json` key — putting `memory`
+  in-file is ignored or rejected. See `references/vercel-json.md`.
+- **`crons` fire only on the production deployment.** Each entry needs a `path` starting with `/` and
+  a `schedule` cron expression. They never run against preview. Don't expect a preview to tick.
+- **`redirects` change the URL the browser sees** (`permanent: true` → 308, cacheable); **`rewrites`
+  keep the URL and serve other content** (proxying, framework routing); **`headers` add response
+  headers** by path. Reaching for the wrong one of these three is the classic mistake.
+- **`functions` cannot be combined with the legacy `builds` key** — pick one; `functions` is current.
+
+`vercel.ts` exports the same shape but is code that runs at build time — use it only to *generate*
+config (e.g. regions from an env var). Full top-level key catalog (21 keys), object shapes, and the
+per-plan limit table live in `references/vercel-json.md`.
+
+## Runtimes in 2025-2026
+
+Edge Functions and Edge Middleware were **deprecated and unified into Vercel Functions** — the edge
+runtime now runs *on* Vercel Functions (changelog "Edge Middleware and Edge Functions are now powered
+by Vercel Functions", 2025-06). What this means for you:
+
+- **New standalone functions: don't set `runtime: 'edge'`.** Use the default Node runtime (Vercel
+  Functions). Reaching for the edge runtime for a fresh API route is the deprecated path.
+- **Routing Middleware still defaults to the edge runtime** — the deprecation does *not* apply to it.
+  Leave middleware as-is.
+- **Pick Node** when you need full Node APIs, longer duration, larger payloads, or a database driver
+  that isn't edge-compatible. The Fluid-compute default already gives you fast cold starts and
+  concurrency, so the old "use edge for speed" reflex is mostly obsolete.
+
+## Domains & deployment protection
+
+```bash
+vercel domains add example.com         # attach a domain to the current project
+vercel domains ls                      # list domains
+vercel domains inspect example.com     # show config + nameserver/record status
+vercel domains add example.com --force # move it off whatever project currently holds it
+vercel alias set <deployment-url> staging.example.com   # point an alias at a deployment
+```
+
+For DNS records themselves (`vercel dns add`) beyond attachment, and for registrar/nameserver theory,
+see `../domains-dns/SKILL.md`.
+
+**Deployment Protection** is per-project: a *method* (Vercel Authentication or Password) plus a
+*scope*. On **Hobby, Standard Protection covers preview deployments and the generated deployment
+URLs; the production custom domain stays public.** For CI that must hit a protected preview, use a
+protection-bypass token rather than disabling protection — recipe in `references/cli-cookbook.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+| --- | --- | --- |
+| `memory` set inside `functions` on a Fluid project | Ignored/rejected — Fluid sets memory/CPU in the dashboard, not the file | Remove `memory`; set the default in project settings |
+| `builds` + `functions` together | Legacy `builds` is mutually exclusive with `functions` | Delete `builds`; express everything via `functions` |
+| Committing `.env` so the build can read secrets | Secret leaks into git history; rotates badly | `vercel env add`; `vercel env pull` for local only |
+| Expecting `crons` to run on a preview | Crons execute only on the production deployment | Test the handler with `vercel dev`; rely on prod for the schedule |
+| Cranking `maxDuration` to the plan ceiling to mask a slow query | Hides the real bug; burns compute; still hits the hard cap | Fix the query/timeout; set `maxDuration` to a sane headroom value |
+| `runtime: 'edge'` on a new standalone function | Edge Functions are deprecated → Vercel Functions | Use the default Node runtime; keep edge only for middleware |
+| Using `redirect` when you meant `rewrite` (or vice-versa) | Redirect changes the visible URL; rewrite keeps it | Redirect for moved URLs (308), rewrite for proxy/internal routing |
+| `vercel env pull` then surprised the value is stale | Pull overwrites for one environment at the moment you run it | Re-pull with `--environment=<env>` after any dashboard change |
+
+## References
+
+- `references/vercel-json.md` — every top-level key, the `functions`/`crons`/`rewrites`/`redirects`/
+  `headers` object shapes, the per-plan `maxDuration`/`memory` limit table, and a `vercel.ts` example.
+- `references/cli-cookbook.md` — copy-paste CLI recipes (link, deploy, env round-trip, domains +
+  alias, promote a preview to production, protection-bypass for CI) and the full `VERCEL_*` system
+  env var table.

package/skills/vercel/evals/README.md

@@ -0,0 +1,23 @@
+# Eval harness — `vercel`
+
+These cases are graded by an agent/human judge, not a shell script. No live Vercel account, login,
+or network is needed: triggering checks routing, and the capability check grades a generated
+`vercel.json` against a `must_include` rubric (you can additionally pipe that file through
+`scripts/verify.sh` for a mechanical sanity pass).
+
+## How to run
+
+- **Triggering.** Load the full skill catalog so routing is realistic (vercel alongside deployment,
+  nextjs, domains-dns, cloudflare, …). For each `should_trigger` prompt, run 3-5 fresh sessions and
+  confirm the `vercel` skill fires. For each `should_not_trigger`, confirm `vercel` stays silent and
+  the agent routes toward the named `route_to` sibling. A near-miss leaking into `vercel` is a worse
+  failure than a missed trigger — investigate any leak. Pass bar: ~90% trigger accuracy.
+- **Capability.** Run the scenario twice — once with `skills/vercel/SKILL.md` (and its `references/`)
+  loaded, once without — and score each output against the `must_include` list (one point per item).
+  Pass when the with-skill run covers >=80% AND clearly beats the without-skill run; if both score
+  the same, the skill is adding no value on that scenario. Optionally run the produced `vercel.json`
+  through `bash scripts/verify.sh <file>` to confirm it mechanically passes (no `builds`+`functions`,
+  no in-file `memory`, well-formed crons).
+
+Record per-prompt fire rates, routing targets on near-misses, and with/without capability scores.
+Note borderline cases honestly rather than rounding up to a green check.

package/skills/vercel/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: vercel
+
+should_trigger:
+  - prompt: "Deploy this project to Vercel production from the CLI."
+    why: "Core scope — the `vercel --prod` deploy path against an already-linked Vercel project."
+  - prompt: "My Vercel function keeps timing out at 10 seconds. How do I let it run longer?"
+    why: "Non-obvious: the symptom is a timeout, not 'config', but the fix is `maxDuration` plus the plan ceiling (Hobby 60s / Pro 300s) — a signature vercel.json knob."
+  - prompt: "vercel env pull isn't updating my .env.local for the preview environment."
+    why: "Non-obvious env round-trip gotcha — pull defaults to the linked env and overwrites; the fix is `--environment=preview`. Names the CLI but the failure mode is the teaching point."
+  - prompt: "Configura un cron job a Vercel que s'executi cada hora."
+    why: "Catalan phrasing for crons; tests the production-only crons rule and the path/schedule shape."
+  - prompt: "Set up a custom domain on my Vercel project and protect the preview deployments."
+    why: "Combines `vercel domains add` with deployment-protection scopes (Hobby: preview protected, prod public) — both squarely platform-ops."
+  - prompt: "Should I still be using Edge Functions on Vercel or is there a new way?"
+    why: "Runtime-deprecation fact: Edge Functions folded into Vercel Functions; don't set runtime:'edge' on new standalone functions, keep edge only for middleware."
+  - prompt: "Write me a vercel.json with an hourly cron, a 30s function timeout in fra1, and clean URLs."
+    why: "Direct vercel.json authoring across functions/crons/cleanUrls — the config front door this skill owns."
+
+should_not_trigger:
+  - prompt: "Should I host on Vercel or a Hetzner VPS? I'll need a Dockerfile and CI too."
+    route_to: "deployment"
+    why: "Host-choice plus containers and CI is the deployment skill; this skill assumes the Vercel choice is already made."
+  - prompt: "My Next.js App Router route handler returns a 500 — fix the data fetching."
+    route_to: "nextjs"
+    why: "Application runtime code (App Router, route handler logic) belongs to nextjs; vercel only touches platform knobs around it."
+  - prompt: "Add an MX record and verify SPF/DKIM for my domain."
+    route_to: "domains-dns"
+    why: "Raw DNS records and email auth are domains-dns; vercel only covers attaching a domain to a project via the CLI."
+  - prompt: "Set up GitHub Actions to run my test suite on every push."
+    route_to: "deployment"
+    why: "CI-pipeline authoring lives in the deployment skill (which owns GitHub Actions); it's not Vercel platform operation."
+  - prompt: "Deploy this to Cloudflare Pages instead of Vercel."
+    route_to: "cloudflare"
+    why: "Different platform — Cloudflare Pages/Workers is its own sibling; vercel is Vercel-specific."
+
+capability:
+  - scenario: "Author a vercel.json for a Pro project: API functions under api/ with a 30s timeout running in fra1, an hourly cron hitting /api/digest, a redirect from /old to /new, and clean URLs."
+    must_include:
+      - "`$schema` set to https://openapi.vercel.sh/vercel.json"
+      - "`functions` glob (e.g. `api/**/*.ts`) with `maxDuration: 30` and `regions: [\"fra1\"]`"
+      - "does NOT set `memory` inside `functions` (Fluid: memory is a dashboard setting)"
+      - "`crons` entry with `path` starting with `/` (`/api/digest`) and a valid `schedule` cron expression (`0 * * * *`)"
+      - "notes that crons run only on the production deployment, not on previews"
+      - "`redirects` entry from /old to /new, with `permanent` flagged (308 vs 307 noted)"
+      - "`cleanUrls: true`"

package/skills/vercel/references/cli-cookbook.md

@@ -0,0 +1,98 @@
+# Vercel CLI cookbook
+
+Copy-paste recipes. All read-only unless noted. Assumes `npm i -g vercel` (or `npx vercel`).
+
+## Link & first deploy
+
+```bash
+vercel link                  # associate the current dir with a project (writes .vercel/)
+vercel                       # preview deploy, prints a unique URL
+vercel --prod                # production deploy
+vercel dev                   # local emulation of functions + routing
+vercel pull                  # fetch project settings + env into .vercel/.env.* for local builds
+vercel inspect <url>         # details for a specific deployment
+vercel logs <url>            # runtime logs for a deployment
+```
+
+## Env var round-trip
+
+```bash
+vercel env ls                                   # which vars exist in which environments
+vercel env add API_URL production               # add to production (prompts for value)
+vercel env add API_URL preview                  # separate command — preview
+vercel env add LOCAL_ONLY development            # development MUST be its own command
+vercel env pull .env.local                      # pull the linked env into .env.local (overwrites)
+vercel env pull .env.local --environment=preview # pull a SPECIFIC environment
+vercel env rm API_URL preview                   # remove a var from one environment
+vercel env run -- npm run seed                  # run a command with project vars injected
+```
+
+Reminders:
+
+- You cannot mix `development` with `production`/`preview` in one `vercel env add`.
+- Vars added to production/preview/custom default to **sensitive** (write-only).
+- `vercel env pull` **overwrites** the target file for one environment — re-pull after changes.
+
+## Domains & aliases
+
+```bash
+vercel domains add example.com           # attach a domain to the current project
+vercel domains ls                        # list domains
+vercel domains inspect example.com       # config + record/nameserver status
+vercel domains add example.com --force   # move the domain off whatever project holds it
+vercel domains rm example.com            # detach (mutating)
+vercel alias set <deployment-url> staging.example.com  # point an alias at a deployment
+vercel dns ls example.com                # list DNS records (managed-domain case)
+```
+
+For DNS-record theory and registrar transfers, defer to the `domains-dns` skill.
+
+## Promote a preview to production
+
+A preview deployment is already built; promote it instead of rebuilding.
+
+```bash
+vercel ls                                # find the preview deployment URL
+vercel promote <deployment-url>          # promote that exact build to production
+vercel rollback <deployment-url>         # roll the production domain back to a prior deploy
+```
+
+## Skip redundant builds (monorepo)
+
+```json
+{ "ignoreCommand": "git diff --quiet HEAD^ HEAD -- ." }
+```
+
+Vercel cancels the build when `ignoreCommand` exits `0` (zero = skip).
+
+## Deployment-protection bypass for CI
+
+When CI must reach a protected preview, don't disable protection — send the bypass header.
+Configure "Protection Bypass for Automation" in project settings to get the secret, then:
+
+```bash
+curl -H "x-vercel-protection-bypass: $VERCEL_AUTOMATION_BYPASS_SECRET" \
+     "https://my-preview-xyz.vercel.app/api/health"
+```
+
+On Hobby, Standard Protection covers preview deployments and the generated deployment URLs; the
+production custom domain stays public.
+
+## System env vars (`VERCEL_*`, read-only)
+
+| Var | Value |
+| --- | --- |
+| `VERCEL` | `1` when running on Vercel |
+| `VERCEL_ENV` | `production` \| `preview` \| `development` |
+| `VERCEL_URL` | Deployment host (no protocol) |
+| `VERCEL_BRANCH_URL` | Git-branch deployment URL |
+| `VERCEL_PROJECT_PRODUCTION_URL` | Production domain |
+| `VERCEL_REGION` | Region the function is executing in |
+| `VERCEL_GIT_PROVIDER` | e.g. `github` |
+| `VERCEL_GIT_REPO_SLUG` | Repository slug |
+| `VERCEL_GIT_COMMIT_REF` | Branch/ref that triggered the deploy |
+| `VERCEL_GIT_COMMIT_SHA` | Commit SHA |
+| `VERCEL_GIT_COMMIT_MESSAGE` | Commit message |
+| `VERCEL_GIT_COMMIT_AUTHOR_LOGIN` | Author login |
+
+Read them in the app (`process.env.VERCEL_ENV`); never try to set them.

package/skills/vercel/references/vercel-json.md

@@ -0,0 +1,120 @@
+# `vercel.json` — full key catalog
+
+Static config for a Vercel project. Add `"$schema": "https://openapi.vercel.sh/vercel.json"` for
+editor autocomplete and validation. `vercel.ts` supports the **same** properties but runs at build
+time, so it can compute config from env vars or API calls.
+
+## Top-level keys (current)
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `$schema` | string | Set to `https://openapi.vercel.sh/vercel.json` for validation |
+| `buildCommand` | string | Overrides the framework build command |
+| `bunVersion` | string | Pin the Bun version used for builds |
+| `cleanUrls` | boolean | Drop `.html`/`.htm` extensions from paths |
+| `crons` | array | Scheduled invocations — **production only** (see below) |
+| `devCommand` | string | Command for `vercel dev` |
+| `fluid` | boolean | Fluid compute toggle (on by default for new projects since 2025-04-23) |
+| `framework` | string | Framework preset (e.g. `nextjs`); `null` for no preset |
+| `functions` | object | Per-path function config (see below) — cannot combine with legacy `builds` |
+| `headers` | array | Response headers by path |
+| `ignoreCommand` | string | Run before build; **exit 0 = skip/cancel the build** |
+| `images` | object | Image Optimization config |
+| `installCommand` | string | Overrides dependency install |
+| `outputDirectory` | string | Build output dir |
+| `public` | boolean | Expose source/logs publicly |
+| `redirects` | array | URL redirects (status changes the visible URL) |
+| `bulkRedirectsPath` | string | Path to a large redirects file |
+| `regions` | array | Default deployment regions |
+| `functionFailoverRegions` | array | Failover regions (Enterprise) |
+| `rewrites` | array | URL rewrites (URL stays, content swaps) |
+| `routes` | array | Low-level routing (prefer rewrites/redirects/headers) |
+| `trailingSlash` | boolean | Force/forbid a trailing slash |
+
+`functions` and the legacy `builds` are mutually exclusive — use `functions`.
+
+## `functions` object
+
+```json
+{
+  "functions": {
+    "api/**/*.ts": {
+      "runtime": "nodejs22.x",
+      "maxDuration": 60,
+      "regions": ["fra1", "iad1"],
+      "includeFiles": "data/**",
+      "excludeFiles": "tests/**",
+      "supportsCancellation": true
+    }
+  }
+}
+```
+
+| Key | Notes |
+| --- | --- |
+| `runtime` | Runtime identifier; default Node (Vercel Functions). Edge Functions are deprecated |
+| `memory` | **Not under Fluid** — set default memory/CPU in the dashboard instead |
+| `maxDuration` | Max wall-clock seconds per invocation; plan-bound (table below) |
+| `supportsCancellation` | Node only |
+| `includeFiles` / `excludeFiles` | Glob extra/omitted files in the function bundle |
+| `regions` | Where the function runs |
+| `functionFailoverRegions` | Enterprise failover |
+
+### Per-plan duration & memory
+
+| Plan | `maxDuration` default → ceiling | Default memory |
+| --- | --- | --- |
+| Hobby | 10s → 60s | 1024 MB |
+| Pro | 15s → 300s | 1024 MB |
+| Enterprise | 15s → 900s | 1024 MB |
+
+Memory defaults to 1024 MB; under Fluid the default is a dashboard setting, not a `vercel.json` key.
+
+## `crons`
+
+```json
+{ "crons": [{ "path": "/api/digest", "schedule": "0 * * * *" }] }
+```
+
+- Each entry needs a `path` (must start with `/`) and a `schedule` (cron expression).
+- Crons run **only on the production deployment** — never on preview.
+
+## `rewrites` / `redirects` / `headers`
+
+```json
+{
+  "redirects": [{ "source": "/old", "destination": "/new", "permanent": true }],
+  "rewrites": [{ "source": "/proxy/:path*", "destination": "https://api.example.com/:path*" }],
+  "headers": [
+    { "source": "/(.*)", "headers": [{ "key": "X-Frame-Options", "value": "DENY" }] }
+  ]
+}
+```
+
+- `redirects`: `permanent: true` → 308 (cacheable), `false` → 307. Changes the visible URL.
+- `rewrites`: URL stays in the address bar; different content/origin is served. Use for proxying.
+- `headers`: attach response headers per path.
+
+## `vercel.ts` example
+
+```ts
+import type { VercelConfig } from "@vercel/config";
+
+const config: VercelConfig = {
+  functions: {
+    "api/**/*.ts": {
+      maxDuration: process.env.SLOW_API === "1" ? 60 : 15,
+      regions: [process.env.PRIMARY_REGION ?? "fra1"],
+    },
+  },
+  crons: [{ path: "/api/digest", schedule: "0 * * * *" }],
+  cleanUrls: true,
+};
+
+export default config;
+```
+
+Use `vercel.ts` only when config must be *generated*; otherwise prefer the static `vercel.json`.
+
+For the full region identifier list (`fra1`, `iad1`, `sfo1`, …) consult the Vercel regions doc — they
+change over time and are not worth hard-coding here.