@damiangilgonzalez/harness 1.3.7

package/skills/pitch-deck/references/numbers-that-matter.md

@@ -0,0 +1,78 @@
+# The numbers that matter on the deck
+
+This file is about **which numbers belong ON the deck and what "good" looks like** — not how to compute them
+at scale. Build the projection/cohort/burn model in `financial-model`; run the standalone CAC/LTV/payback
+health check in `unit-economics`. Here you pick the decision-grade few and put them where they persuade.
+
+At seed, the decision rides on a small set. Do **not** dump the P&L on a slide — choose the metrics that tell
+*your* story (traction, business model, the ask) and show each with a unit and a trend.
+
+## The metric glossary (formula + current band)
+
+| Metric | Formula | Healthy band (2025/26) | Where on the deck |
+| --- | --- | --- | --- |
+| MRR | sum of monthly recurring revenue | — | Traction |
+| ARR | MRR × 12 | — | Traction |
+| MoM growth | (this month − last month) / last month | ~15–20% (<$1M ARR); ~8–15% ($1M–$10M ARR) | Traction (the curve) |
+| CAC | sales+marketing spend / new customers acquired | varies; judged via LTV:CAC + payback | Business model |
+| LTV | (ARPA × gross margin) / churn rate | — | Business model |
+| LTV : CAC | LTV / CAC | **≥ 3:1** | Business model / Traction |
+| CAC payback | CAC / (ARPA × gross margin), in months | **< ~18 months** (2024 median; lower = above avg) | Business model |
+| Gross margin | (revenue − COGS) / revenue | software typically **70%+** | Business model |
+| Net revenue retention | (start + expansion − churn − contraction) / start | **> 110%** | Traction |
+| Burn rate | net cash out per month | context for runway | Ask (use-of-funds) |
+| Runway | cash on hand / monthly burn | names the ask milestone | Ask |
+
+A quick read of the bands: **LTV:CAC ≥ 3:1, NRR > 110%, CAC payback under ~18 months** is the "above-average
+efficiency" signal. You do not need all of them — pick the ones that are strong and honest for your stage.
+
+## Growth shape beats absolute size
+
+This is the load-bearing idea of the traction slide. **A consistent curve outperforms a bigger flat number.**
+
+```text
+Company A:  $50K MRR, +25% MoM, 6 months straight   ->  reads STRONGER
+Company B:  $200K MRR, flat or erratic              ->  reads weaker
+```
+
+Why: investors back the *derivative*, not the level. $50K growing 25% MoM compounds past $200K fast and proves
+the acquisition engine works; $200K flat proves it stalled. Show the curve, label the trend, and let the slope
+do the persuading. Early-stage targets: ~15–20% MoM under $1M ARR, ~8–15% MoM from $1M–$10M ARR.
+
+## Bad → Good traction slides
+
+```text
+Bad   "10,000 users. Huge interest. Going viral."
+       (no unit, no trend, no money — a vanity wall)
+
+Good   "$50K MRR, +22% MoM for 5 straight months (curve shown).
+        NRR 118%. 40 paying logos incl. [Customer A, Customer B].
+        LTV:CAC 4:1, CAC payback 11 months."
+       (each number has a UNIT and a TREND; the SHAPE is visible; money is real)
+```
+
+```text
+Bad   "We grew 300% last year!"
+       (300% from what to what? one big % hides a tiny base or a one-off spike)
+
+Good   "$8K -> $50K MRR over 6 months, +22% MoM average (no single month below +15%)."
+       (the base, the path, the consistency — the claim is falsifiable and the trend is the point)
+```
+
+The vanity tell: **a count with no rate behind it.** Registered users without an activation or paying rate, app
+installs without retention, "interest" without revenue. A sharp investor reads the missing rate as the number
+you are hiding — so show it, even when it is small but honest.
+
+## What NOT to put on the deck
+
+- The full P&L or a 5-year monthly model — that is a data-room artifact; the deck shows the shape, the room
+  holds the detail. Build it in `financial-model`.
+- A CAC/LTV teardown by channel and cohort — that is the `unit-economics` health check; the deck shows the
+  headline band (LTV:CAC 4:1), the analysis lives elsewhere.
+- Every metric you track. Three strong, honest numbers beat twelve mediocre ones. Curate.
+
+## Sourcing rule
+
+Every number on a slide traces to a source: the model, your analytics, or a citation. Mark any gap
+`[[NEEDS PROOF]]` rather than inventing a figure to fill a chart — a single fabricated number, once caught,
+poisons the whole deck. A hockey-stick projection must name its driver; a curve with no mechanism is fiction.

package/skills/pitch-deck/references/slide-spine.md

@@ -0,0 +1,149 @@
+# The slide spine — full template
+
+The canonical investor-deck spine is **10 core slides + the ask**, read in risk-evaluation order. Keep the
+whole deck under ~15 (DocSend: 11–20 raises better; past that it hurts). For each slide below: its one job, the
+investor question it answers, what content goes on it, an example line, and the trap.
+
+Read this top-to-bottom: the deck is built in this order because that is the order an investor evaluates risk.
+
+---
+
+## 1 — Title / purpose
+
+- **Job:** say what you do in one declarative line.
+- **Investor question:** "What is this, in a sentence?"
+- **On it:** company name, a one-line "we do X for Y" positioning, stage/round (optional), one clean visual.
+- **Example:** *"Acme — the books-close autopilot for Series-A finance teams."*
+- **Trap:** a vague tagline ("reimagining work") that could describe a hundred companies. Be concrete.
+
+## 2 — Problem
+
+- **Job:** make a real pain ache, for a specific who.
+- **Investor question:** "Is this a real, urgent problem — and for whom?"
+- **On it:** who has the pain, what it costs them today, why current workarounds fail. One number that sizes
+  the pain.
+- **Example:** *"A 200-person SaaS company spends ~12 finance-days a month closing the books in spreadsheets."*
+- **Trap:** a problem no one pays to solve, or a problem stated so broadly it has no owner.
+
+## 3 — Solution
+
+- **Job:** show the insight that solves the problem.
+- **Investor question:** "Does their thing actually solve it — and why is it the right shape?"
+- **On it:** your approach in one sentence, the non-obvious insight behind it, the before→after for the user.
+- **Example:** *"We ingest the ledger and auto-reconcile — close drops from 12 days to 2."*
+- **Trap:** a feature list. Lead with the insight; features are slide 6.
+
+## 4 — Why now
+
+- **Job:** name the shift that makes this the moment.
+- **Investor question:** "Why hasn't this been done — and why is now the time?"
+- **On it:** the recent change (tech, regulation, behavior, cost curve) that just made this viable or urgent.
+- **Example:** *"Ledger APIs went universal in 2024; what needed a 6-month integration is now a 1-day connect."*
+- **Trap:** no answer, or a hand-wave ("AI is hot"). If there is no real shift, the timing thesis is weak.
+
+## 5 — Market
+
+- **Job:** show the prize is big and reachable.
+- **Investor question:** "Is the outcome big enough to return the fund?"
+- **On it:** TAM / SAM / SOM, **bottom-up first**, every number sourced. (Full method below.)
+- **Example:** *"120K target SMBs × $4.8K ACV = $576M SAM (source: [registry]); 3-yr SOM 3,000 = $14.4M ARR."*
+- **Trap:** "$X trillion, we just need 1%." Top-down hand-wave; a credibility tell.
+
+## 6 — Product
+
+- **Job:** one concrete proof the thing is real.
+- **Investor question:** "Is this a working product or a slide?"
+- **On it:** one screenshot / flow / demo frame that shows the core loop. Not 17 features — the one that matters.
+- **Example:** *"[screenshot of the auto-reconcile run completing in 90 seconds]."*
+- **Trap:** a feature carousel. One visual that proves the core insight from slide 3 actually ships.
+
+## 7 — Business model
+
+- **Job:** show how a dollar in becomes more dollars out.
+- **Investor question:** "How does this make money, and is the unit profitable?"
+- **On it:** pricing, who pays, ACV, and the unit economics signal (gross margin, LTV:CAC if you have it).
+- **Example:** *"$400/mo per finance seat; ACV $4.8K; 82% gross margin; LTV:CAC 4:1."*
+- **Trap:** "we'll figure out monetization later" at seed, or a model with no margin logic.
+
+## 8 — Traction (the center of gravity)
+
+- **Job:** show it is working AND accelerating — the SHAPE, not just a point.
+- **Investor question:** "Is it working, and is it speeding up?"
+- **On it:** MRR/ARR + MoM trend (the curve), retention/NRR, key logos, the LTV:CAC band. Few numbers, each
+  with a unit and a trend.
+- **Example:** *"$50K MRR, +22% MoM for 5 months (curve); NRR 118%; 40 paying logos; LTV:CAC 4:1."*
+- **Trap:** vanity metrics (registered users with no activation), a single flat number, or no unit/trend.
+- **Why it's the highest-stakes slide:** investors spend ~3× longer here, and 76% of "no" decisions cite weak
+  traction. This is where the deck is won or lost.
+
+## 9 — Competition
+
+- **Job:** an honest landscape + your specific wedge.
+- **Investor question:** "Why won't incumbents just crush them?"
+- **On it:** the real alternatives (incl. "status quo / spreadsheets"), and the one axis where you win.
+- **Example:** *"Incumbents bolt reconciliation onto an ERP; we are the close-native layer — 10× faster setup."*
+- **Trap:** "we have no competition." Reads as naive or as "no market." Status quo is always a competitor.
+
+## 10 — Team
+
+- **Job:** why *this* team wins *this*.
+- **Investor question:** "Can these specific people pull it off?"
+- **On it:** founders, the earned insight / unfair advantage, relevant prior wins. Key hires/advisors if they
+  de-risk.
+- **Example:** *"Ex-Stripe finance-infra lead + ex-Big4 controller — we lived this close for 6 years."*
+- **Trap:** a logo wall of past employers with no link to *why it makes you win this problem*.
+
+## 11 — The ask
+
+- **Job:** amount → use-of-funds → the milestone it buys.
+- **Investor question:** "What do you need, and what does my money de-risk?"
+- **On it:** raise amount + instrument, the use-of-funds split, and the specific milestone the runway reaches.
+- **Example:**
+
+  ```text
+  Raising $1.5M (SAFE).
+  Use of funds:  60% engineering · 25% go-to-market · 15% ops
+  Buys:          18 months runway to $100K MRR — Series-A ready.
+  ```
+
+- **Trap:** an ask with no number, or a burn statement with no milestone ("$1.5M for 18 months"). The
+  milestone turns a burn rate into an investment thesis.
+
+---
+
+## The market-sizing method (bottom-up, sourced)
+
+Investors scrutinize the market slide and the ask hardest for realism. Build the number, do not assert it.
+
+1. **SOM (bottom-up, the honest one):** reachable accounts in 3 years × your price. Start here.
+2. **SAM:** total accounts you could serve × price — the segment you actually address.
+3. **TAM:** the whole category, top-down — used only as a sanity ceiling.
+4. **Source every figure** (registry, analyst report, census). The big number should be the *result* of the
+   unit math, never the premise.
+
+```text
+SOM (3-yr reachable):  3,000 accounts  × $4.8K ACV = $14.4M ARR
+SAM (addressable):     120,000 accounts × $4.8K   = $576M
+TAM (category ceiling): $X.XB  (top-down sanity check, sourced)
+```
+
+## Stage deltas — what each slide may claim
+
+| Slide | Pre-seed (sells team + insight) | Seed (sells early traction shape) | Series A (sells repeatable engine) |
+| --- | --- | --- | --- |
+| Problem | Sharp, lived, specific | Same, now validated by users | Same, with paying-customer proof |
+| Solution | The insight + a prototype | A shipped product | A product with depth/moat |
+| Why now | The timing thesis | Same, with early signal | Same, proven by adoption |
+| Market | Bottom-up estimate | Bottom-up, refined by real ACV | Real ACV + expansion math |
+| Traction | Waitlist / LOIs / design partners | MRR + MoM trend + early retention | Predictable growth + NRR + payback |
+| Business model | Hypothesis, with margin logic | Early pricing validated | Proven unit economics (LTV:CAC, payback) |
+| Team | The whole bet | Team + early execution proof | Team scaled, key hires in place |
+| Ask | Small (to reach traction) | Medium (to reach the engine) | Larger (to pour fuel on a proven engine) |
+
+Claiming above your stage (Series-A "engine" language on a pre-seed deck with no data) reads as naive.
+Claiming below it (a seed deck hiding real traction behind a vision) wastes your strongest card.
+
+---
+
+Hand off: once this spine is locked, `presentations` renders + themes + exports it; `financial-model` produces
+the numbers behind slides 5/7/8/11; `investor-materials` builds the one-pager, memo, and data room around it.

package/skills/pitch-deck/scripts/verify.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural/numeric lint for an investor pitch-deck OUTLINE.
+#
+# WHAT IT DOES (read-only; no edits, no network)
+#   Parses a deck outline (markdown — one slide per heading line, e.g. `## Problem`
+#   or `## Slide 8: Traction`) and checks the CONTENT CONTRACT, not prose taste:
+#     1. Required core slides present: problem, solution, why-now, market, product,
+#        business-model, traction, team, ask (case-insensitive heading match).
+#     2. Slide count: warn if > 15 (the deck-discipline limit).
+#     3. Ask block: must name a currency amount (or "raising ...") AND a
+#        use-of-funds / runway / milestone token. A numberless ask FAILS.
+#     4. Traction block: must carry >=1 metric with a unit (%, MRR, ARR, x, $).
+#        Numberless traction WARNS.
+#     5. Buzzword banlist WARNING (revolutionary, disruptive, world-class,
+#        no competition, best-in-class, hockey stick, conservative estimate).
+#
+#   Narrative quality is NOT judged here — that is the capability eval's job.
+#   This is grep-level structure only.
+#
+# HOW TO RUN (against your own deck outline, not the skills repo)
+#   ./verify.sh path/to/deck.md
+#   ./verify.sh --strict path/to/deck.md      # warnings become failures (CI gate)
+#   ./verify.sh                               # no path -> nothing to lint, exits 0
+#
+# EXIT CODES
+#   0  clean, or warn-only (and not --strict), or no target given / empty target
+#   1  a real failure: a missing CORE slide, or an ask with no number
+#      (also: any warning when --strict)
+#   2  bad usage (path given but not a readable file)
+
+set -euo pipefail
+
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (>= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color (suppressed when not a TTY) -------------------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+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)); }
+
+usage() { sed -n '3,35p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse -------------------------------------------------------------
+STRICT=0
+DECK=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    -*)        printf '%sUnknown flag: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *)         DECK="$1"; shift ;;
+  esac
+done
+
+# No target -> nothing to check. Clean exit (no false failure on empty input).
+if [ -z "$DECK" ]; then
+  printf 'No deck outline given. Pass a markdown path, e.g.: %s deck.md\n' "$0"
+  printf '(nothing to lint — exiting clean)\n'
+  exit 0
+fi
+
+if [ ! -f "$DECK" ]; then
+  printf '%sNot a readable file: %s%s\n' "$RED" "$DECK" "$NC"
+  exit 2
+fi
+
+# Empty file -> clean exit, no false failure.
+if [ ! -s "$DECK" ]; then
+  warn "deck outline is empty: $DECK (nothing to lint)"
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Linting deck outline: %s\n\n' "$DECK"
+
+# Headings only (lines starting with one or more '#').
+HEADINGS="$(grep -E '^#{1,6}[[:space:]]' "$DECK" 2>/dev/null || true)"
+
+# --- 1. required core slides ----------------------------------------------
+# Each entry: "Label|regex matched against heading text (case-insensitive)".
+check_slide() {
+  label="$1"; pat="$2"
+  if printf '%s\n' "$HEADINGS" | grep -iqE "$pat"; then
+    ok "core slide present: $label"
+  else
+    fail "missing core slide: $label (heading matching /$pat/)"
+  fi
+}
+
+check_slide "Problem"        'problem|pain'
+check_slide "Solution"       'solution|how it works|approach'
+check_slide "Why now"        'why[ -]?now|timing'
+check_slide "Market"         'market|tam|sam|som|market size'
+check_slide "Product"        'product|demo|how it works'
+check_slide "Business model" 'business model|model|pricing|revenue model|how we (make|earn)'
+check_slide "Traction"       'traction|growth|metrics|momentum'
+check_slide "Team"           'team|founders|who we are'
+check_slide "Ask"            'ask|raise|raising|fundrais|the ask|use of funds'
+
+# --- 2. slide count --------------------------------------------------------
+SLIDE_COUNT="$(printf '%s\n' "$HEADINGS" | grep -cE '^#{1,6}[[:space:]]' || true)"
+SLIDE_COUNT="${SLIDE_COUNT:-0}"
+if [ "$SLIDE_COUNT" -gt 15 ]; then
+  warn "deck has $SLIDE_COUNT headings — over the ~15-slide discipline; move detail to the conversation/data room"
+elif [ "$SLIDE_COUNT" -eq 0 ]; then
+  warn "no '#' headings found — is this a slide-per-heading outline?"
+else
+  ok "slide count $SLIDE_COUNT (<= 15 discipline limit)"
+fi
+
+# --- block extraction ------------------------------------------------------
+# Print the lines from the heading matching $1 up to (not incl.) the next heading.
+block_for() {
+  # Lowercase the heading for matching so it works on BSD awk (no IGNORECASE).
+  awk -v pat="$1" '
+    BEGIN { inblk = 0 }
+    /^#{1,6}[[:space:]]/ {
+      if (inblk) { exit }
+      if (tolower($0) ~ pat) { inblk = 1; print; next }
+    }
+    { if (inblk) print }
+  ' "$DECK"
+}
+
+# --- 3. ask block: amount AND a use-of-funds/runway/milestone token --------
+ASK_BLOCK="$(block_for 'ask|raise|raising|fundrais|use of funds')"
+if [ -z "$ASK_BLOCK" ]; then
+  warn "could not isolate an ask block to inspect (heading not found earlier?)"
+else
+  has_amount=0; has_use=0
+  # currency amount: $/€/£ + number, or a number + k/m/mm, or the word raising/raise
+  # An actual figure: currency+digit, a number with a k/m unit, or "raising <number>".
+  # Bare "raise/raising" with no number does NOT count as an amount.
+  if printf '%s\n' "$ASK_BLOCK" | grep -iqE '[$€£][0-9]|[0-9]+(\.[0-9]+)?[[:space:]]*(k|m|mm|million|thousand)|rais(e|ing)[[:space:]]+[$€£]?[0-9]'; then
+    has_amount=1
+  fi
+  if printf '%s\n' "$ASK_BLOCK" | grep -iqE 'use of funds|runway|milestone|months?|to[[:space:]]+[$€£]?[0-9]|series[ -]?[ab]|allocat|breakdown'; then
+    has_use=1
+  fi
+  if [ "$has_amount" -eq 1 ] && [ "$has_use" -eq 1 ]; then
+    ok "ask names an amount AND a use-of-funds/runway/milestone"
+  elif [ "$has_amount" -eq 0 ]; then
+    fail "ask slide names no raise amount (need e.g. '\$1.5M' or 'raising ...')"
+  else
+    warn "ask names an amount but no use-of-funds/runway/milestone — add 'what it buys'"
+  fi
+fi
+
+# --- 4. traction block: at least one metric with a unit --------------------
+TRACTION_BLOCK="$(block_for 'traction|growth|metrics|momentum')"
+if [ -z "$TRACTION_BLOCK" ]; then
+  warn "could not isolate a traction block to inspect"
+else
+  if printf '%s\n' "$TRACTION_BLOCK" | grep -iqE '[0-9]+([.,][0-9]+)?[[:space:]]*(%|x|mrr|arr|nrr)|[$€£][0-9]|[0-9]+[[:space:]]*(mom|mo|month)'; then
+    ok "traction carries >=1 metric with a unit (%, x, MRR/ARR, \$, MoM)"
+  else
+    warn "traction slide has no number+unit — show the growth SHAPE (e.g. '\$50K MRR, +22% MoM')"
+  fi
+fi
+
+# --- 5. buzzword banlist (warn-only) ---------------------------------------
+BUZZ='revolutionary|disruptive|world-?class|no competition|best-?in-?class|hockey ?stick|conservative estimate|game-?changer'
+hits="$(grep -inE "$BUZZ" "$DECK" 2>/dev/null || true)"
+if [ -n "$hits" ]; then
+  warn "buzzwords found (replace with a number / mechanism / receipt):"
+  printf '%s\n' "$hits" | head -n 6
+else
+  ok "no banlist buzzwords"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/planetscale/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: planetscale
+description: "Use when operating PlanetScale (Vitess serverless MySQL) — branches and the `pscale` CLI, schema changes through deploy requests (Online DDL cutover, ~30-min revert window), tables without foreign keys, or the edge HTTP driver. NOT MySQL engine work like EXPLAIN or index choice (that is `mysql`), NOT generic migration theory (that is `db-migrations`)."
+tags: [planetscale, vitess, mysql, deploy-requests, serverless-db]
+recommends: [mysql, db-migrations, prisma-orm, drizzle-orm, github-actions, postgresdb]
+origin: risco
+---
+
+# PlanetScale — Vitess serverless MySQL: branches, deploy requests, no FKs
+
+PlanetScale is serverless, MySQL-compatible database-as-a-service built on **Vitess** — the same
+horizontal-scaling layer that runs YouTube. You do not `ALTER TABLE` against production. Schema
+changes live on an isolated **branch** (a full copy of the schema), reach production through a
+**deploy request** (a pull request for your schema), and apply via **Online DDL**: Vitess builds a
+shadow table holding the new schema, replicates rows and in-flight writes old→new with VReplication,
+then **cuts over** with no table lock. Because Online DDL and sharding are the platform's center of
+gravity, you **design without foreign keys** (FKs are now an opt-in but unsharded-only feature). This
+skill owns that workflow — not MySQL the engine.
+
+Heuristic for the boundary: **would this answer be identical on RDS MySQL? Then it is not this skill.**
+
+| When the question is really about | Route to |
+| --- | --- |
+| A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking | `../mysql/SKILL.md` for MySQL-engine work; `../postgresdb/SKILL.md` when you want the transferable engine reasoning |
+| PostgreSQL engine/design — even PlanetScale's own managed Postgres SQL semantics | `../postgresdb/SKILL.md`. PlanetScale sells Postgres too; this skill is strictly the **Vitess/MySQL branch+deploy-request** flow |
+| Engine-agnostic migration *theory* (expand-contract, backfill ordering) | `../db-migrations/SKILL.md`. Here you get the concrete PlanetScale realization, not the theory |
+| Postgres copy-on-write branches | `../neon/SKILL.md`. Postgres BaaS → `../supabase/SKILL.md` |
+| ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) | `../prisma-orm/SKILL.md` / `../drizzle-orm/SKILL.md`. This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter) |
+
+## Mental model
+
+| PlanetScale concept | Git analogue | What it actually is |
+| --- | --- | --- |
+| Branch | branch | A full, isolated copy of the schema. `main` is your production branch. |
+| Deploy request | pull request | The gate that carries schema from a dev branch to production. |
+| Schema diff | the PR diff | The exact DDL the deploy will run, computed by PlanetScale. |
+| Online DDL | (no git analogue) | Shadow table + VReplication + non-blocking cutover. No `ALTER` lock. |
+| Schema revert | revert commit | A **~30-minute** window after deploy to undo while preserving post-deploy writes. |
+
+The revert window is the one thing people get wrong: it is **not** forever, and it has carve-outs
+(dropped tables/columns and FK-constraint changes are not cleanly revertible). After ~30 minutes the
+deploy is permanent. Plan rollbacks as new forward deploys, not as "I'll just revert later."
+
+## The deploy-request workflow
+
+Production branches should have **safe migrations** enabled — that is what forces every schema change
+through a deploy request instead of letting a raw `ALTER` hit `main`. Production branches are protected
+by default. The full lifecycle (numbered steps, real `pscale` commands):
+
+```bash
+# 0. Install + authenticate (once)
+brew install planetscale/tap/pscale   # or scoop / apt — see pscale docs
+pscale auth login
+
+# 1. Create the database (region close to your app)
+pscale database create my_app --region us-east
+
+# 2. Create a dev branch off production to hold the change
+pscale branch create my_app add-orders-table
+
+# 3. Apply your DDL on the BRANCH, never on main.
+#    Open a MySQL shell scoped to the branch and run your CREATE/ALTER:
+pscale shell my_app add-orders-table
+#    mysql> CREATE TABLE orders (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
+#    mysql> ALTER TABLE users ADD COLUMN last_seen_at TIMESTAMP NULL;
+
+# 4. Open a deploy request from the branch back to production.
+#    --disable-auto-apply gates the cutover behind a manual apply (recommended for risky drops).
+pscale deploy-request create my_app add-orders-table --disable-auto-apply
+
+# 5. Inspect the exact schema diff the deploy will run. ALWAYS read this.
+pscale deploy-request diff my_app 42
+
+# 6. Review / approve (the schema-PR review step)
+pscale deploy-request review my_app 42 --approve
+
+# 7. Deploy. PlanetScale runs Online DDL: shadow table -> VReplication -> cutover.
+pscale deploy-request deploy my_app 42
+
+# 8. If you disabled auto-apply, the change waits gated until you apply the cutover:
+pscale deploy-request apply my_app 42
+
+# 9. Verify on production. If wrong, REVERT within the ~30-minute window:
+pscale deploy-request revert my_app 42
+```
+
+**Auto-apply is ON by default.** With it on, step 7 deploys *and* cuts over in one motion. For
+anything destructive — dropping a column/table, narrowing a type — pass `--disable-auto-apply` at
+step 4 so the cutover sits gated (step 8) until a human applies it. That gap is your last cheap exit
+before the revert window starts ticking.
+
+For queued/gated deploys that won't move, lint errors that block a deploy, declarative vs imperative
+schema, and the exact revert carve-outs, see [deploy-requests](references/deploy-requests.md).
+
+## Design without foreign keys
+
+Vitess's first-class features are Online DDL and horizontal sharding. Native foreign keys fight both:
+a cross-shard FK is meaningless once a table is sharded, and FK constraint checks degrade
+high-concurrency writes. PlanetScale **historically disallowed FKs entirely**; they are now an opt-in
+but **unsharded-only** feature. The scale-safe default is **app-level referential integrity** with
+emulated relations, not database-enforced FKs.
+
+```sql
+-- Bad on PlanetScale at scale: a DB-enforced FK with ON DELETE CASCADE.
+-- Blocks sharding, conflicts with Online DDL, and the cascade is a hidden write amplifier.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- Good: no DB FK. Index the relation column, enforce integrity in the app/ORM,
+-- and do cascades explicitly in a transaction or background job.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  KEY idx_orders_user_id (user_id)   -- the relation still needs its index
+);
+```
+
+With Prisma, declare `relationMode = "prisma"` so the client emulates relations and adds the implicit
+indexes instead of emitting DB-level FKs:
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+```
+
+With Drizzle, model the relation in app code (`relations()`), index the join column, and skip the
+`references()`-backed FK constraint at the DB layer.
+
+| Will this table shard? | FK strategy | Notes |
+| --- | --- | --- |
+| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
+| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |
+
+See [no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.
+
+## Connecting
+
+Two connection paths. Pick by **runtime**, not by preference.
+
+```ts
+// Direct MySQL string — for Node/long-lived servers that can open a TCP socket.
+// DATABASE_URL=mysql://user:pass@host/db?ssl-mode=require   (TLS required)
+
+// Serverless HTTP driver — for edge/serverless where raw TCP MySQL is blocked.
+import { connect } from "@planetscale/database";
+
+const conn = connect({ url: process.env.DATABASE_URL });
+const result = await conn.execute("SELECT id FROM users WHERE email = ?", [email]);
+```
+
+`@planetscale/database` is Fetch-API compatible: it speaks HTTP, so it works where you cannot open a
+MySQL socket — Cloudflare Workers, Vercel Edge, Lambda. The spelling is exactly `@planetscale/database`;
+there is no other official package name. Drizzle ships a matching adapter,
+`drizzle-orm/planetscale-serverless`, that wraps this driver — see `../drizzle-orm/SKILL.md` for the
+query-builder side.
+
+| Runtime | Connection path | Why |
+| --- | --- | --- |
+| Node server, long-lived process | Direct `mysql://…?ssl-mode=require` | TCP socket available; pool it. |
+| Vercel Edge / Cloudflare Workers | `@planetscale/database` (HTTP) | No raw TCP; the Fetch-based driver works. |
+| AWS Lambda / short-lived serverless | `@planetscale/database` (HTTP) | Avoids per-invocation connection churn. |
+| Drizzle on edge | `drizzle-orm/planetscale-serverless` | Wraps the HTTP driver; same constraints. |
+
+## CI/CD
+
+Wire the deploy-request flow into CI so schema changes are reviewed like code. A GitHub Actions job
+installs `pscale`, authenticates with a service token (`PLANETSCALE_SERVICE_TOKEN` /
+`PLANETSCALE_SERVICE_TOKEN_ID` as secrets), then drives the same verbs you run locally:
+
+```yaml
+# .github/workflows/schema.yml — open + diff a deploy request on PR
+- run: |
+    pscale deploy-request create "$DB" "${{ github.head_ref }}" --disable-auto-apply
+    pscale deploy-request diff   "$DB" "$DR_NUMBER"   # surface the schema diff in the PR
+```
+
+For a **branch-per-PR preview database**, create a PlanetScale branch named after the PR head, run the
+app's migrations against it, and tear the branch down when the PR closes. The orchestration (matrix,
+secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to `../github-actions/SKILL.md`
+and keep the PlanetScale verbs here.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `ALTER TABLE` on the `main` production branch | Skips the gate; no diff, no review, no revert window | Branch → DDL → deploy request → diff → deploy |
+| Relying on DB-enforced foreign keys at scale | Blocks sharding, fights Online DDL, degrades high-concurrency writes | App/ORM-level integrity; `relationMode="prisma"`; index the relation column |
+| Leaving auto-apply ON for a destructive change | Deploy + cutover happen in one motion; no gated last-look before the drop | `--disable-auto-apply`, inspect, then `deploy-request apply` |
+| Opening a direct `mysql://` connection from Vercel Edge / Workers | Raw TCP MySQL is blocked on edge runtimes → connection timeouts | Use `@planetscale/database` HTTP driver |
+| Treating revert as available forever | The window is **~30 min** and excludes dropped tables/cols and FK changes | Plan rollbacks as new forward deploys |
+| Deploying without reading `deploy-request diff` | You ship DDL you never saw; surprise table rewrites | Always run the diff before `deploy` |
+| Inventing a driver name (`@planetscale/serverless`, `planetscale-js`) | There is no such package; install fails | The package is exactly `@planetscale/database` |

package/skills/planetscale/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — planetscale
+
+`cases.yaml` holds prompt-routing checks and capability rubrics for the repo's eval harness. The
+`should_trigger` / `should_not_trigger` entries assert routing: an LLM grader decides whether each
+prompt would invoke the planetscale skill, and the `should_not_trigger` cases name the real sibling it
+should go to instead (mysql, postgresdb, neon, db-migrations, prisma-orm). The `capability` entry is a
+scenario graded against its `must_include` rubric — the model's answer must hit each bullet (dev
+branch, branch-scoped DDL, `pscale deploy-request create`/`diff`, Online DDL shadow-copy/cutover,
+auto-apply vs manual apply, the ~30-minute revert window and its carve-outs, and a no-FK table design).
+No live PlanetScale account, `pscale` CLI, or database is needed — everything is graded from the model's
+text. Run it through the repo's standard eval runner against this directory.