@damiangilgonzalez/harness 1.3.7

package/skills/sqlite-turso/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: sqlite-turso
+
+should_trigger:
+  - prompt: "My app is read-heavy and single-tenant. Is SQLite actually enough or do I need a real database like Postgres?"
+    why: "The core decision this skill leads with — workload fit and the route-out to postgresdb when writers multiply."
+  - prompt: "Under load I keep getting 'database is locked' and occasional SQLITE_BUSY errors. How do I fix it?"
+    why: "Non-obvious: the user names a symptom, not the engine. Owned by the WAL + busy_timeout + single-writer guidance."
+  - prompt: "I want a local SQLite file that automatically syncs to a Turso database in the cloud so reads stay fast but data is durable."
+    why: "This is the embedded-replica flagship — file: url + syncUrl + token + sync()."
+  - prompt: "How do I wire createClient from @libsql/client to my Turso edge database with an auth token?"
+    why: "Direct connection scope: the current client, env-var token convention, URL-scheme transport selection."
+  - prompt: "I'm building a SaaS and want a separate database per customer on the edge. Is that practical?"
+    why: "Non-obvious mapping: database-per-user/per-tenant economics are a Turso strength (unlimited DBs), covered in the body and reference."
+  - prompt: "Munta una base de dades local-first amb rèplica incrustada que sincronitzi amb el núvol."
+    why: "Catalan trigger for the embedded-replica / local-first flagship — language coverage plus core feature."
+  - prompt: "Should I turn on WAL mode for my SQLite file, and what other pragmas should I always set?"
+    why: "Engine-truth scope: journal_mode=WAL, busy_timeout, foreign_keys per-connection, synchronous=NORMAL."
+
+should_not_trigger:
+  - prompt: "Define my libSQL schema with tables and relations and write type-safe queries with Drizzle."
+    route_to: drizzle-orm
+    why: "Schema modeling and the type-safe query builder layer ON TOP of the client — drizzle's job, not this engine/connection skill."
+  - prompt: "Create ordered up/down migration files for my SQLite schema and a runner to apply them."
+    route_to: db-migrations
+    why: "Versioned migration discipline is engine-agnostic and explicitly out of scope; this skill only does ad-hoc DDL."
+  - prompt: "We need thousands of users writing concurrently with complex transactions and roles."
+    route_to: postgresdb
+    why: "Many concurrent writers is exactly where SQLite's single-writer model breaks — route to a client-server RDBMS."
+  - prompt: "Give me serverless Postgres with database branching for preview environments."
+    route_to: neon
+    why: "Postgres-compatible serverless with branching is neon; Turso is serverless SQLite, a different engine."
+  - prompt: "Build a vector similarity search store for my RAG pipeline with reranking."
+    route_to: vector-db
+    why: "Even though Turso has native vector search, a dedicated vector store as the goal routes to the vector specialist."
+
+capability:
+  - scenario: "User asks to add Turso to a Next.js app so local reads are sub-millisecond but data is durably stored in the cloud, and wants the connection set up correctly."
+    must_include:
+      - "Uses an embedded replica: createClient with a local `file:` url AND a `syncUrl` to the remote primary (not a bare remote client for the local-read requirement)"
+      - "Reads the auth token from the environment (process.env.TURSO_AUTH_TOKEN), never a hardcoded literal"
+      - "Provides freshness via syncInterval and/or a manual await db.sync() call, mentioning sync() returns {frame_no, frames_synced}"
+      - "Recommends PRAGMA journal_mode=WAL plus busy_timeout and foreign_keys=ON on the file-backed connection"
+      - "States that production today uses libSQL (@libsql/client v0.17.x); Turso Database (Rust) is the future direction, not the default target"
+      - "Routes type-safe schema/queries to drizzle-orm and versioned migrations to db-migrations rather than doing them here"
+      - "Warns that db.sync() on a remote-only/HTTP client throws SYNC_NOT_SUPPORTED, and that a syncUrl requires a local file: url"

package/skills/sqlite-turso/references/embedded-replicas.md

@@ -0,0 +1,96 @@
+# Embedded replicas — deep reference
+
+Offloaded from SKILL.md because it is branch-specific and longer than the body should carry. Read
+this when you are actually building or operating an embedded-replica deployment.
+
+## What a replica actually is
+
+An embedded replica is a real local SQLite file (`url: "file:local.db"`) plus a `syncUrl` pointing at
+a remote primary. The client maintains the local copy and pulls a stream of **frames** (the unit of
+replication — roughly a batch of committed changes) from the primary. Reads execute against the local
+file with in-process latency. Writes are forwarded to the primary; they do not mutate the local file
+directly, they come back via the next sync.
+
+This is why the local file is mandatory: there is no replica without somewhere local to materialize
+the data. A `syncUrl` next to a `libsql://` url is a contradiction — there is no local store to sync
+into, so the client behaves as a plain remote client and never replicates.
+
+## Sync mechanics and frame numbers
+
+`await client.sync()` returns `{ frame_no, frames_synced }`:
+
+- `frame_no` — the replication frame the local replica is now at (a monotonically advancing
+  position in the primary's change log). Useful for logging/observability and reasoning about how far
+  behind a replica was.
+- `frames_synced` — how many frames this particular `sync()` call pulled. `0` means the replica was
+  already current.
+
+Two ways to drive sync:
+
+- **`syncInterval` (seconds)** in `createClient` — background periodic pull. Good for read-mostly
+  apps that tolerate eventual consistency up to one interval. Pick the interval from how stale a read
+  may be, not from a default.
+- **Manual `client.sync()`** — pull on demand: at request start, after a known remote write, on app
+  resume from background. Combine both: a slow `syncInterval` safety net plus targeted manual syncs
+  where freshness matters.
+
+Calling `sync()` on a client without a `syncUrl` + local `file:` (a remote-only or pure HTTP/WS
+client) throws `LibsqlError` with code `SYNC_NOT_SUPPORTED`. Guard the call by construction — only
+sync clients you built as replicas.
+
+## `readYourWrites` semantics
+
+Default is `true`. With it on, a write you issue through the client is immediately visible to your
+own subsequent reads on that client, even before the next background sync — the client tracks your
+write position and waits for the local replica to catch up to it on read. This is what most apps
+want: you click "save", you re-read, you see your change.
+
+Set `readYourWrites: false` only when you deliberately want a sync's effect to be observable on its
+own timeline — e.g. tests that assert "this row is not visible until I explicitly `sync()`", or
+benchmarks measuring pure replica staleness. If you turn it off in a normal app you will get
+confusing "I just wrote that, why is it gone?" reports.
+
+## Offline and bidirectional writes
+
+Classic libSQL embedded replicas are read-local / write-through-primary: you need connectivity to
+the primary to commit a write. True **offline writes** with bidirectional sync (write locally while
+disconnected, reconcile later) is a capability of **Turso Database (the Rust rewrite)**, not the
+production libSQL path. If a requirement says "must accept writes fully offline and merge later",
+that is the Rust engine's roadmap territory — flag it as not-yet-default-production rather than
+promising it on libSQL today.
+
+## Database-per-user / per-tenant patterns
+
+Turso's unlimited-databases free tier makes a separate database per tenant economical, which gives
+hard data isolation without row-level-security gymnastics.
+
+- **One primary per tenant**, each with its own `libsql://` URL and token. Mint tokens per database
+  with the `turso` CLI.
+- **Connection management**: do not create one `createClient` per request — cache clients keyed by
+  tenant id (a `Map<tenantId, Client>`), and reuse. Each embedded replica holds an open local file;
+  thousands of unmanaged replicas will exhaust file handles and disk.
+- **Replica per tenant** only where the access pattern is local-heavy for that tenant (e.g. a desktop
+  or edge node dedicated to one tenant). For a multi-tenant server hitting many tenants, prefer
+  remote clients (shape #2) and let the edge do the work, or you will be syncing a fleet of files.
+- **Provisioning**: tenant signup creates a database (`turso db create`) and a scoped token; store
+  the URL/token in your secrets store keyed by tenant, never in source.
+
+## Staleness, failure, and consistency
+
+- A replica serves the **last successfully synced state**. If sync fails (network, auth), reads keep
+  working against the stale local copy — this is a feature for availability, a trap for correctness.
+  Surface sync errors; do not swallow them.
+- `frames_synced: 0` over many calls when you expect changes means the primary genuinely has nothing
+  new, or your client is pointed at the wrong primary — check `syncUrl` and token scope.
+- Writes are linearized at the primary, so cross-tenant/global invariants belong at the primary, not
+  asserted against a possibly-stale replica.
+- For "must always read the absolute latest", call `sync()` immediately before the read, or use a
+  remote-only client (shape #2) for that path and accept the round-trip.
+
+## Where this hands off
+
+- Type-safe schema and queries on top of any of these clients → `drizzle-orm`.
+- Versioned, ordered, reversible schema changes (up/down files, a runner) → `db-migrations`. This
+  reference only covers ad-hoc DDL through `execute`/`batch`.
+- Backup/restore and point-in-time strategy as the goal → `backups`.
+- Generic SQL authoring independent of engine (window functions, query tuning) → `sql`.

package/skills/sqlite-turso/scripts/verify.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — sqlite-turso skill gate. Read-only, no network, deterministic.
+#
+# Statically checks @libsql/client integration file(s) for the foot-guns this skill exists to
+# prevent. Pass a file or a directory; with no arg it scans the current directory.
+#
+#   bash verify.sh                 # scan ./ for *.ts / *.js / *.mjs / *.mts
+#   bash verify.sh src/db.ts       # check one file
+#   bash verify.sh src/            # scan a directory
+#
+# What it checks PER FILE that imports @libsql/client:
+#   1. uses createClient (else: not really wiring the client) ......... FAIL
+#   2. if `syncUrl` appears, a local `file:` url must also appear ...... FAIL
+#      (an embedded replica must be backed by a local file)
+#   3. no hardcoded auth token literal (require process.env/Deno.env) .. FAIL
+#   4. file-backed client (`file:`) should set PRAGMA ... WAL .......... advisory [warn]
+#
+# Exit code: non-zero ONLY when a FAIL is recorded. Files with no @libsql/client import are
+# skipped. An empty/clean target prints nothing actionable and exits 0 (no false failure).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+TARGET="${1:-.}"
+
+# Collect candidate files (bash 3.2: no mapfile; NUL-delimited into an initialised array).
+FILES=()
+if [ -f "$TARGET" ]; then
+  FILES+=("$TARGET")
+elif [ -d "$TARGET" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$TARGET" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
+      -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' -o -name '*.mts' \) -print0 2>/dev/null
+  )
+else
+  warn "target not found: $TARGET (nothing to check)"
+  exit 0
+fi
+
+CHECKED=0
+for f in "${FILES[@]+"${FILES[@]}"}"; do
+  # Only inspect files that actually pull in the libSQL client.
+  grep -Eq "@libsql/client" "$f" 2>/dev/null || continue
+  CHECKED=$((CHECKED + 1))
+
+  # 1. must call createClient
+  if grep -Eq "createClient[[:space:]]*\(" "$f"; then
+    ok "$f: imports @libsql/client and calls createClient"
+  else
+    err "$f: imports @libsql/client but never calls createClient"
+  fi
+
+  # 2. embedded replica must be file-backed
+  if grep -Eq "syncUrl" "$f"; then
+    if grep -Eq "[\"'\`]file:" "$f"; then
+      ok "$f: syncUrl is backed by a local file: url (embedded replica)"
+    else
+      err "$f: syncUrl present but no local 'file:' url — that is a confused remote client, not a replica"
+    fi
+  fi
+
+  # 3. no hardcoded auth token literal. authToken must come from an env source.
+  if grep -Eq "authToken" "$f"; then
+    if grep -Eq "authToken[[:space:]]*:[[:space:]]*[\"'\`]" "$f"; then
+      err "$f: authToken assigned a string literal — read it from process.env / Deno.env instead"
+    elif grep -Eq "authToken[[:space:]]*:[[:space:]]*(process\.env|Deno\.env|import\.meta\.env|Bun\.env)" "$f"; then
+      ok "$f: authToken read from an environment source"
+    else
+      warn "$f: authToken present — confirm it comes from the environment, not a literal"
+    fi
+  fi
+
+  # 4. advisory: a file-backed client should set WAL
+  if grep -Eq "[\"'\`]file:" "$f"; then
+    if grep -Eiq "journal_mode[[:space:]]*=[[:space:]]*WAL" "$f"; then
+      ok "$f: file-backed client sets journal_mode=WAL"
+    else
+      warn "$f: file-backed client — consider PRAGMA journal_mode=WAL (advisory)"
+    fi
+  fi
+done
+
+if [ "$CHECKED" -eq 0 ]; then
+  ok "no @libsql/client integration files found — nothing to verify"
+fi
+
+exit "$EXIT"

package/skills/stripe/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: stripe
+description: "Use when wiring an app to Stripe for payments, subscriptions, Checkout, webhooks or the billing portal — adding a paywall or paid plan, charging recurring fees, and debugging why a completion event never fires, why signature verification fails, or why a webhook fires twice and duplicates the order. NOT a generic non-Stripe inbound event receiver (that is `webhooks`), NOT the invoice document's legal form (that is `invoicing`), NOT deciding what to charge (that is `pricing`)."
+tags: [stripe, payments, subscriptions, checkout, webhooks, billing, saas]
+recommends: [webhooks, invoicing, pricing, secure-coding, nodejs]
+profiles: []
+origin: risco
+---
+
+# Stripe — Checkout, subscriptions, and webhooks that survive production
+
+Wire an app to Stripe for one-time payments and subscriptions: a Checkout
+Session to take money, a signature-verified webhook to learn the outcome, and
+the billing portal so customers manage themselves. Targets stripe-node v22.x
+(API version `2026-05-27.dahlia`).
+
+The one rule everything else hangs off:
+
+- **Stripe is the source of truth; your DB is a cache kept current by verified
+  webhooks.** A subscription's real state lives in Stripe. You mirror it locally
+  only so you can render a paywall without a round-trip. The webhook is what
+  keeps the mirror honest — never the client redirect, never polling.
+
+## When to use / When NOT to use
+
+**Use when:** adding Checkout or a paywall; taking a one-time or recurring
+charge; receiving Stripe webhooks; letting users cancel/upgrade via the portal;
+debugging `No signatures found matching`, double-fired events, or a
+`checkout.session.completed` that never arrives.
+
+**Do NOT use for:**
+
+- A **generic, non-Stripe inbound webhook receiver** (arbitrary HMAC, a
+  retry/queue consumer for any provider) → `webhooks`. This skill only covers
+  Stripe's `Stripe-Signature` scheme and event model.
+- The **invoice document's legal form** — what must appear on it, dunning copy,
+  payment-status as a business process → [invoicing](../invoicing/SKILL.md).
+- **Cash-flow forecasting, bank reconciliation, month-close** →
+  [finance-ops](../finance-ops/SKILL.md).
+- **What to charge / plan tiers / packaging** → [pricing](../pricing/SKILL.md).
+  This skill implements a price; it does not decide it.
+- A **typed client for some other REST API** → `api-connector-builder`.
+
+## Pick the surface
+
+| You need | Use | Why |
+|---|---|---|
+| A link to sell one product, zero code | Payment Link | No backend; Stripe hosts everything. Outgrow it fast. |
+| Hosted checkout, full control of session | **Checkout Session** | The default. Stripe hosts the page, handles SCA/3DS, PCI scope is minimal. |
+| Your own embedded payment form | Payment Element + Checkout Session | Custom UI, but you render the form. Use the Element *with* a Checkout Session, not raw PaymentIntents, unless you have a reason. |
+
+Default to **Checkout Session** unless a requirement forces otherwise.
+
+## Mental model
+
+```text
+Customer ──> Price (you defined it in Stripe) ──> Checkout Session
+   │                                                    │
+   │                                          customer pays (hosted)
+   ▼                                                    ▼
+your DB  <── webhook (verified) ── Event <── Subscription / Invoice
+(a cache)                                    (the real state, in Stripe)
+```
+
+Env vars used throughout — read from the environment, never hard-code:
+
+- `STRIPE_SECRET_KEY` — `sk_test_…` in dev, `sk_live_…` in prod.
+- `STRIPE_WEBHOOK_SECRET` — `whsec_…`, one per endpoint; differs in test vs live.
+
+## Construct the client (pin the API version)
+
+```ts
+import Stripe from "stripe";
+
+// Pin apiVersion explicitly so a dashboard-level version bump can never change
+// your API behavior under you. Match the version your SDK release ships with.
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: "2026-05-27.dahlia",
+});
+```
+
+## Create a Checkout Session
+
+```ts
+// Subscription mode — recurring price.
+const session = await stripe.checkout.sessions.create({
+  mode: "subscription",
+  line_items: [{ price: "price_123", quantity: 1 }], // a recurring Price ID
+  success_url: `${BASE}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${BASE}/pricing`,
+  // Tie the session to YOUR user so the webhook can find the right row.
+  client_reference_id: userId,
+  // 14-day trial; omit for immediate billing.
+  subscription_data: { trial_period_days: 14 },
+});
+// Redirect the browser to session.url.
+```
+
+```ts
+// Payment mode — one-time charge (e.g. a digital download).
+const session = await stripe.checkout.sessions.create({
+  mode: "payment",
+  line_items: [{ price: "price_onetime", quantity: 1 }],
+  success_url: `${BASE}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${BASE}/`,
+  client_reference_id: userId,
+});
+```
+
+`success_url` is a UX redirect, not proof of payment. The customer can close the
+tab before it loads, or hit the URL directly. **Grant access from the webhook,
+not the redirect.**
+
+## The webhook handler (load-bearing)
+
+This is where integrations break. Three non-negotiables:
+
+1. **Verify against the RAW body.** `constructEvent` recomputes the signature
+   over the exact bytes Stripe sent. Any middleware that parses/re-serializes
+   the body (e.g. `express.json()` on this route) changes those bytes and you
+   get `No signatures found matching the expected signature`.
+2. **Return 2xx before slow work.** Verify, record the event, return 200
+   immediately. Stripe treats a timeout as failure and retries — for up to 3
+   days in live mode — so slow handlers cause duplicate delivery.
+3. **Be idempotent.** Events are unordered and may arrive more than once.
+   Dedupe on `event.id`, persisting the idempotency record in the *same
+   transaction* as the business write. Default replay tolerance is 5 minutes.
+
+```ts
+// Express. The route gets the RAW body; do NOT mount express.json() here.
+app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      req.body,                          // raw Buffer, untouched
+      req.headers["stripe-signature"]!,  // header name is lowercase
+      process.env.STRIPE_WEBHOOK_SECRET!,
+    );
+  } catch (err) {
+    return res.status(400).send(`Webhook Error: ${(err as Error).message}`);
+  }
+
+  // Dedupe + record in one transaction; skip if we have seen this event.id.
+  const fresh = await recordEventOnce(event.id, event.type);
+  if (!fresh) return res.status(200).send(); // already processed; ack and stop
+
+  // Return 2xx FAST. Hand heavy work to a queue/background job if it is slow.
+  switch (event.type) {
+    case "checkout.session.completed": {
+      const s = event.data.object as Stripe.Checkout.Session;
+      await grantAccess(s.client_reference_id!, s.customer as string);
+      break;
+    }
+    case "customer.subscription.updated":
+    case "customer.subscription.deleted": {
+      const sub = event.data.object as Stripe.Subscription;
+      await syncSubscription(sub.customer as string, sub.status); // mirror state
+      break;
+    }
+    case "invoice.payment_failed":
+      // dunning lives here; see references/webhook-events.md
+      break;
+  }
+  res.status(200).send();
+});
+```
+
+See [`references/webhook-events.md`](references/webhook-events.md) for the full
+event catalog per flow (subscription lifecycle, one-time payment, dunning) and
+what each event should do to your DB.
+
+### Framework gotchas (raw body)
+
+```ts
+// Next.js App Router — read the raw text yourself; do not use req.json().
+// app/api/webhook/route.ts
+export async function POST(req: Request) {
+  const body = await req.text();                       // raw string
+  const sig = req.headers.get("stripe-signature")!;
+  const event = stripe.webhooks.constructEvent(body, sig, secret);
+  // ...handle, then:
+  return new Response(null, { status: 200 });
+}
+```
+
+```ts
+// Edge / Cloudflare Workers — synchronous crypto is unavailable. Use the async
+// API with the Web Crypto provider.
+const event = await stripe.webhooks.constructEventAsync(
+  body, sig, secret, undefined, Stripe.createSubtleCryptoProvider(),
+);
+```
+
+## Subscribe to only the events you need
+
+For a subscription paywall, listen to exactly these — listening to "all events"
+is discouraged and buries you in noise:
+
+`checkout.session.completed`, `customer.subscription.created`,
+`customer.subscription.updated`, `customer.subscription.deleted`,
+`invoice.paid`, `invoice.payment_failed`.
+
+## Billing portal (self-service)
+
+Do not build cancel/upgrade/update-card UI. Stripe hosts it.
+
+```ts
+const portal = await stripe.billingPortal.sessions.create({
+  customer: stripeCustomerId,             // the Customer you stored
+  return_url: `${BASE}/account`,
+});
+// Redirect to portal.url — it is short-lived; mint it on demand, never cache it.
+```
+
+## Idempotency on create calls
+
+A retried POST (network blip, double-click) can create two subscriptions.
+Pass an idempotency key derived from the operation, not a random one:
+
+```ts
+await stripe.checkout.sessions.create(params, {
+  idempotencyKey: `checkout:${userId}:${planId}`,
+});
+```
+
+## Local testing — Stripe CLI, never hand-crafted JSON
+
+```bash
+stripe login
+stripe listen --forward-to localhost:3000/api/webhook   # prints a whsec_… secret
+stripe trigger checkout.session.completed                # fire a real test event
+```
+
+Put the printed `whsec_…` in `STRIPE_WEBHOOK_SECRET` for local runs. Hand-built
+JSON will never pass signature verification — that is the point.
+
+## Going live
+
+Compact checklist; depth in [`references/going-live.md`](references/going-live.md):
+
+- [ ] `apiVersion` pinned explicitly in the client.
+- [ ] Swap `sk_test_`/`whsec_` (test) for live values via env, not code.
+- [ ] Create the live webhook endpoint; copy its **own** signing secret.
+- [ ] Restrict the event subscription to the allowlist above.
+- [ ] Use **restricted API keys** for the server, not the unrestricted secret.
+- [ ] Idempotency keys on all create calls.
+- [ ] Confirm SCA/3DS is handled (Checkout does this for you).
+
+## Anti-patterns
+
+| Bad | Good | Why |
+|---|---|---|
+| `express.json()` on the webhook route | `express.raw()` / `req.text()` | Re-serialized body breaks the signature → `No signatures found matching`. |
+| No `constructEvent` — trust the payload | Always verify the signature | Anyone can POST fake events to an unverified endpoint. |
+| Grant access on the `success_url` redirect | Grant on `checkout.session.completed` | The redirect is UX, not proof; it can be skipped or forged. |
+| DB writes, then return 200 | Return 200 fast, queue slow work | Timeouts make Stripe retry → duplicate delivery. |
+| Process every delivery | Dedupe on `event.id` in the write txn | Events are unordered and at-least-once. |
+| Hard-coded `sk_live_…` in source | `process.env.STRIPE_SECRET_KEY` | Leaked keys = drained account; never commit them. |
+| No `apiVersion` | Pin it explicitly | A dashboard version bump silently changes your API behavior. |
+| Poll the API for subscription state | React to webhooks | Polling is slow, rate-limited, and races real events. |
+| Listen to all event types | Subscribe to the allowlist | Noise, wasted handling, accidental side effects. |
+| Cache the portal/session URL | Mint per request | These URLs are short-lived and single-use. |
+
+## See also
+
+- `webhooks` — generic, non-Stripe inbound event receivers.
+- [invoicing](../invoicing/SKILL.md) — the invoice document and its legal form.
+- [pricing](../pricing/SKILL.md) — deciding tiers and amounts before you wire them.
+- [secure-coding](../secure-coding/SKILL.md) — secret handling, key restriction.

package/skills/stripe/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — stripe
+
+`cases.yaml` holds three groups scored by an LLM judge against the rendered
+skill. `should_trigger` and `should_not_trigger` check routing: each prompt is
+classified and we confirm Stripe owns it (or that it correctly defers to the
+named sibling — `route_to` ids are real skills). `capability` checks that the
+SKILL.md plus `references/` actually contain enough to satisfy the `must_include`
+rubric for a subscription-paywall build. Run these through the repo's eval runner
+(it discovers `evals/cases.yaml` under each skill); there is no standalone
+harness here. Treat a judge miss as a prompt to sharpen the description's
+triggers/boundary or to fill a gap in the body, not as noise.

package/skills/stripe/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: stripe
+
+should_trigger:
+  - prompt: "Add a Pro subscription tier with Stripe Checkout to my SaaS."
+    why: Core build — subscription-mode Checkout Session plus webhook to grant access.
+  - prompt: "My Stripe webhook returns 400 with 'No signatures found matching the expected signature'."
+    why: Non-obvious symptom of the raw-body/signature-verification bug this skill owns.
+  - prompt: "The Stripe webhook fires twice and creates the order twice."
+    why: Idempotency / dedupe on event.id — a core handler concern, not obvious from the word 'twice'.
+  - prompt: "Let customers cancel and upgrade their plan themselves without me building UI."
+    why: Customer billing portal session.
+  - prompt: "El webhook de Stripe se ejecuta dos veces y duplica el pedido."
+    why: Spanish phrasing of the idempotency problem; same skill.
+  - prompt: "Set up recurring billing with a 14-day free trial in Stripe."
+    why: Subscription mode with trial_period_days.
+  - prompt: "Charge a one-time payment for a digital download via Stripe."
+    why: payment-mode Checkout Session and fulfillment on checkout.session.completed.
+
+should_not_trigger:
+  - prompt: "Verify the HMAC on an incoming GitHub webhook and put it on a retry queue."
+    route_to: webhooks
+    why: Generic non-Stripe inbound receiver; not Stripe's Stripe-Signature scheme.
+  - prompt: "What must legally appear on the invoice I email the client, and what's the dunning copy?"
+    route_to: invoicing
+    why: The invoice document and its legal form, not Stripe API wiring.
+  - prompt: "Should our Pro plan be $29 or $49, and how many tiers should we offer?"
+    route_to: pricing
+    why: Packaging/amount decision, not implementation.
+  - prompt: "Build a 13-week cash-flow forecast and reconcile the bank statement."
+    route_to: finance-ops
+    why: Forecasting and reconciliation, not payment integration.
+  - prompt: "Build a typed client for the Acme REST API with retries and backoff."
+    route_to: api-connector-builder
+    why: Generic third-party API client, unrelated to Stripe.
+
+capability:
+  - scenario: "Add a subscription paywall to a Next.js app: a Checkout Session, a webhook handler, and a self-service billing portal."
+    must_include:
+      - "Checkout Session created with mode: 'subscription' and both success_url and cancel_url."
+      - "Webhook verifies the RAW body with stripe.webhooks.constructEvent using STRIPE_WEBHOOK_SECRET."
+      - "Returns a 2xx before slow work and dedupes on event.id."
+      - "Handles checkout.session.completed plus customer.subscription.updated/deleted."
+      - "Billing portal via stripe.billingPortal.sessions.create({ customer, return_url })."
+      - "Keys read from process.env, explicit apiVersion pin, no hard-coded sk_ literal."
+      - "Access granted from the webhook, not from the success_url redirect."

package/skills/stripe/references/going-live.md

@@ -0,0 +1,64 @@
+# Going live — production hardening
+
+The Checkout/webhook code is the easy part. These are the things that bite in
+production.
+
+## Test → live cutover
+
+- Test and live mode have **separate keys, separate webhook endpoints, separate
+  signing secrets, and separate data**. Nothing crosses over.
+- Create the live webhook endpoint in the dashboard; copy its **own**
+  `whsec_…`. The CLI secret from `stripe listen` is for local only.
+- Swap keys via environment/secret manager, never by editing code. A `sk_live_`
+  literal in source is a drainable credential.
+
+## Restricted API keys
+
+Do not run the server with the account's unrestricted secret key. Create a
+**restricted key** granting only the resources you touch (e.g. write on
+Checkout Sessions, Customers, Subscriptions; read on Prices). If it leaks, blast
+radius is bounded. Rotate it on suspicion of exposure.
+
+## Webhook secret rotation
+
+When rotating a webhook signing secret, Stripe lets you keep the old secret
+valid during a roll window. Verify against both during the overlap, then drop
+the old one. Never log the secret or the raw signature header.
+
+## Idempotency keys
+
+Every create call that a retry could duplicate (`checkout.sessions.create`,
+`subscriptions.create`, `customers.create`) takes an `idempotencyKey`. Derive it
+from the operation (`checkout:${userId}:${planId}`), not `Math.random()`, so a
+genuine retry collides and Stripe returns the original result instead of making
+a second object.
+
+## SCA / 3DS
+
+Strong Customer Authentication and 3D Secure are handled for you by Checkout and
+the Payment Element — that is a core reason to prefer them over hand-rolled
+PaymentIntents + cards. Don't reimplement the authentication dance.
+
+## Test clocks
+
+To exercise renewals, trials ending, and dunning without waiting real days,
+attach a Customer to a **test clock** and advance time. This is the only sane
+way to test the multi-day subscription lifecycle.
+
+## PCI scope
+
+With Checkout (Stripe-hosted) or the Payment Element, card data never touches
+your server, keeping you in the lightest PCI tier (SAQ A-class). Raw card
+numbers hitting your backend escalate scope dramatically — don't.
+
+## Pre-launch checklist
+
+- [ ] `apiVersion` pinned in the client.
+- [ ] Live keys/secret in env, not code; test literals gone.
+- [ ] Live webhook endpoint created; its own signing secret wired.
+- [ ] Event subscription restricted to the allowlist you actually handle.
+- [ ] Restricted API key in use on the server.
+- [ ] Idempotency keys on all create calls.
+- [ ] Webhook handler verifies signature, returns 2xx fast, dedupes on `event.id`.
+- [ ] Access gated on `subscription.status`, refreshed by webhooks.
+- [ ] Tested the renewal/dunning path against a test clock.