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

package/skills/shared/vector-db/references/engines.md

@@ -0,0 +1,175 @@
+# engines.md — per-engine recipes (current APIs)
+
+Concrete create-collection / create-index + a filtered hybrid query for each of the four engines.
+Adjust dims and metric to your model; cosine shown throughout (the common case).
+
+## pgvector (Postgres extension, 0.8.x)
+
+HNSW since 0.5.0; iterative scan, `halfvec`, and `binary_quantize` since 0.8.0.
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE docs (
+  id        bigserial PRIMARY KEY,
+  tenant_id text NOT NULL,
+  body      text,
+  embedding vector(1536)          -- text-embedding-3-small; use halfvec(3072) for -3-large
+);
+
+-- Filter field gets its own index so the planner can use it.
+CREATE INDEX docs_tenant_idx ON docs (tenant_id);
+
+-- HNSW, cosine ops to match the model. ef_construction >= 2*m.
+CREATE INDEX docs_embedding_idx
+  ON docs USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+```
+
+`halfvec` to halve storage at near-identical recall (and the only path above 2000 dims):
+
+```sql
+ALTER TABLE docs ADD COLUMN embedding_h halfvec(1536);
+CREATE INDEX ON docs USING hnsw (embedding_h halfvec_cosine_ops);
+```
+
+Filtered query with iterative scan so a selective `WHERE` does not return fewer than `LIMIT` rows:
+
+```sql
+SET hnsw.iterative_scan = 'relaxed_order';   -- 'strict_order' if exact ordering required
+SET hnsw.ef_search = 100;                     -- raise until recall@k hits target
+SELECT id, body
+  FROM docs
+ WHERE tenant_id = 'acme'
+ ORDER BY embedding <=> $1
+ LIMIT 10;
+```
+
+Hybrid is DIY: keep a `tsvector` column, score with `ts_rank`, run both, fuse ranks yourself.
+
+```sql
+ALTER TABLE docs ADD COLUMN tsv tsvector
+  GENERATED ALWAYS AS (to_tsvector('english', coalesce(body,''))) STORED;
+CREATE INDEX docs_tsv_idx ON docs USING gin (tsv);
+-- Then run a vector ORDER BY and a ts_rank query, and combine by reciprocal rank in SQL/app.
+```
+
+## Qdrant (named vectors + hybrid via query API)
+
+In-graph payload filtering, named dense+sparse vectors, server-side IDF (v1.15+), RRF/DBSF fusion.
+
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(url="http://localhost:6333")
+
+client.create_collection(
+    collection_name="docs",
+    vectors_config={"dense": models.VectorParams(size=1536, distance=models.Distance.COSINE)},
+    sparse_vectors_config={"bm25": models.SparseVectorParams()},
+)
+
+# Index the field you filter on (in-graph filtering needs it).
+client.create_payload_index(
+    collection_name="docs",
+    field_name="tenant_id",
+    field_schema=models.PayloadSchemaType.KEYWORD,
+)
+```
+
+Hybrid query: prefetch dense + sparse, fuse with RRF, filter inside the search.
+
+```python
+flt = models.Filter(must=[models.FieldCondition(
+    key="tenant_id", match=models.MatchValue(value="acme"))])
+
+res = client.query_points(
+    collection_name="docs",
+    prefetch=[
+        models.Prefetch(query=dense_vec, using="dense", filter=flt, limit=50),
+        models.Prefetch(query=models.SparseVector(indices=idx, values=val),
+                        using="bm25", filter=flt, limit=50),
+    ],
+    query=models.FusionQuery(fusion=models.Fusion.RRF),   # or models.Fusion.DBSF
+    limit=10,
+)
+```
+
+Search-time recall knob: pass `search_params=models.SearchParams(hnsw_ef=128)`.
+
+## Weaviate (alpha + fusionType, BlockMax WAND BM25)
+
+`alpha` slides keyword↔vector; BlockMax WAND BM25 is the default from v1.30 (~10x faster).
+
+```python
+import weaviate
+import weaviate.classes.config as wc
+
+client = weaviate.connect_to_local()
+client.collections.create(
+    name="Docs",
+    vector_config=wc.Configure.Vectors.self_provided(),   # bring your own vectors
+    properties=[
+        wc.Property(name="body", data_type=wc.DataType.TEXT),
+        wc.Property(name="tenant_id", data_type=wc.DataType.TEXT),
+    ],
+)
+```
+
+Hybrid query with fusion and a filter:
+
+```python
+from weaviate.classes.query import Filter, HybridFusion
+
+docs = client.collections.get("Docs")
+res = docs.query.hybrid(
+    query="how to reset a token",
+    vector=dense_vec,
+    alpha=0.5,                                   # 0.0 keyword .. 1.0 vector
+    fusion_type=HybridFusion.RELATIVE_SCORE,     # or RANKED
+    filters=Filter.by_property("tenant_id").equal("acme"),
+    limit=10,
+)
+```
+
+## Pinecone (serverless, API 2025-01)
+
+Serverless is the default; namespaces partition tenants inside one index. Python SDK v6.x.
+
+```python
+from pinecone import Pinecone, ServerlessSpec
+
+pc = Pinecone(api_key="...")
+pc.create_index(
+    name="docs",
+    dimension=1536,
+    metric="cosine",                             # match the model
+    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+)
+index = pc.Index("docs")
+```
+
+Batched upsert into a namespace (never one-by-one):
+
+```python
+index.upsert(
+    vectors=[{"id": d["id"], "values": d["vec"], "metadata": {"source": d["src"]}}
+             for d in batch],          # send hundreds per call
+    namespace="acme",
+)
+```
+
+Query with metadata filter in the retrieval path (not post-filter):
+
+```python
+res = index.query(
+    vector=dense_vec,
+    top_k=10,
+    namespace="acme",
+    filter={"source": {"$eq": "handbook"}},
+    include_metadata=True,
+)
+```
+
+Sparse-dense hybrid uses `sparse_values` on upsert and query, or integrated inference to embed +
+rerank server-side.

package/skills/shared/vector-db/references/tuning.md

@@ -0,0 +1,62 @@
+# tuning.md — recall, parameters, quantization, filter pitfalls
+
+## HNSW vs IVFFlat
+
+| | HNSW | IVFFlat |
+|---|---|---|
+| Recall | High, smooth with `ef_search` | Lower; depends on `lists`/`probes` |
+| Build cost | Higher (graph) | Lower / faster |
+| Memory | Higher | Lower |
+| Build params | `m` (default 16), `ef_construction` (default 64) | `lists` (≈ rows/1000, capped) |
+| Query param | `ef_search` (default 40) | `probes` (more = better recall, slower) |
+| Selective filter | Use with iterative scan (pgvector 0.8) | Drops rows on selective filters — avoid |
+| Default choice | **Yes** | Only when build speed > recall |
+
+Invariant: keep `ef_construction >= 2*m`. A too-low `ef_construction` permanently degrades the
+graph; you cannot tune it back at query time — only a rebuild fixes it.
+
+## Recall-measurement recipe
+
+Do this on a sample before shipping. "Search is bad" is unactionable without a recall number.
+
+1. Pick ~200–500 representative query vectors.
+2. **Exact baseline**: compute true top-k by brute force (full scan / no index). In pgvector,
+   query with the index disabled to get ground truth.
+3. **Index result**: same queries through the ANN index.
+4. `recall@k = mean(|index_topk ∩ exact_topk| / k)`.
+5. Raise the search knob (below) until recall hits target (often ≥0.95), then stop — extra `ef`
+   buys latency, not quality.
+
+| Engine | Search-time recall knob | Default |
+|---|---|---|
+| pgvector | `hnsw.ef_search` | 40 |
+| Qdrant | `hnsw_ef` (`SearchParams`) | per-collection |
+| Weaviate | `ef` (vectorIndexConfig; `-1` = dynamic) | dynamic |
+| Pinecone | managed (no manual knob) | — |
+
+## Quantization tradeoffs
+
+| Method | Compression | Recall risk | Notes |
+|---|---|---|---|
+| Scalar (int8) | ~4x | Low | Safe default RAM cut |
+| Product (PQ) | 8–64x | Medium–high | Needs tuning; recall-test mandatory |
+| Binary | ~32x, ~40x faster (SIMD popcount) | High on low dims | Only ≥1024 dims; rescore with full precision |
+| pgvector `halfvec` | ~2x | Negligible | 16-bit float; required for >2000 dims |
+
+Order of reach: `halfvec`/scalar first (near-free) → product for huge corpora → binary only on
+high-dim vectors after a measured recall test, with optional full-precision rescoring.
+
+## Per-engine filtered-search pitfalls
+
+- **pgvector**: a selective `WHERE` on a pre-0.8 setup (or without `hnsw.iterative_scan`) returns
+  fewer than `LIMIT` rows because the index returns `ef_search` candidates and then the filter
+  removes most. Set `hnsw.iterative_scan='relaxed_order'` and index the filter column.
+- **Qdrant**: filtering only works well when the payload field has a payload index; otherwise it
+  degrades to a scan. Filtering happens in-graph during traversal — keep the index.
+- **Weaviate**: combine `filters=` with `hybrid(...)`; an unfiltered prefetch followed by an
+  app-side filter is the post-filter trap.
+- **Pinecone**: metadata filtering is in the retrieval path, but very high-cardinality metadata
+  still costs; keep filterable fields lean and use namespaces for tenant isolation.
+
+Cross-cutting rule: **filter inside the search, index the filter field, and verify you still get
+`k` rows on your most selective real filter.**

package/skills/shared/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/shared/vercel/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: vercel
+description: "Use when operating an already-chosen Vercel project from the CLI or its config file — preview versus production deploys, debugging builds, pushing and pulling env vars across environments, custom domains, function runtime, duration and regions, crons, rewrites and headers, and deployment protection. NOT host choice, Docker or CI (that is `deployment`), NOT Next.js app code or next.config (that is `nextjs`), NOT DNS records or registrar transfers (that is `domains-dns`)."
+tags: [vercel, deploy, serverless, edge, env-vars]
+recommends: [deployment, nextjs, domains-dns]
+origin: ai-hub
+---
+
+# 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, React Server Components, `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/shared/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/shared/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`"