@damiangilgonzalez/harness 1.3.7

package/skills/calendar-scheduling/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: calendar-scheduling
+description: "Use when a product needs a booking surface — a pick-a-slot page, a Cal.com/Calendly embed, or real availability plus the confirmed meeting written to Google/Outlook — or when fixing double-booking, DST drift, or orphaned reschedule events. NOT calendar CRUD with no booking surface (that is `google-workspace`), NOT the payment (that is `stripe`)."
+tags: [scheduling, booking, calendar, calcom, calendly, google-calendar, availability, webhooks]
+recommends: [google-workspace, webhooks, automation-flows, email-connector, stripe, sales-pipeline]
+profiles: []
+origin: risco
+---
+
+# Calendar scheduling — booking surface + calendar sync, shipped together
+
+Scheduling is always two halves bolted together: a **booking surface** (an
+external person reserves a slot — embed, atom, or API call) and **calendar
+sync** (you read free/busy to compute availability and write the confirmed
+event back). Ship one without the other and you get the three bugs the rest of
+this skill exists to prevent: **double-booking**, **timezone drift** after a DST
+change, and **orphaned events** on reschedule.
+
+## Decide the altitude first
+
+Pick the lowest-code option that still owns the data model you actually need.
+
+| You need… | Reach for | What you own | Escape hatch |
+|---|---|---|---|
+| A booking page fast, minimal code | **Embed Cal.com or Calendly** | Nothing — the widget owns slots/sync | Call the API later to read bookings / fire automation |
+| Bookings in *your* UI, *your* branding/data model | **Cal.com Booker atom** or **Scheduling API** (Cal.com / Calendly) | Your UI; provider owns sync | Drop to raw provider API if the data model chafes |
+| Read/write *one* provider's calendar directly | **Google `freebusy.query` + `events.insert`** | OAuth, refresh, slot math, watch/sync | If it's pure CRUD with no booking → `google-workspace` |
+| Many providers (Google + Outlook + Apple), no N integrations | **Unified API** (Cronofy or Nylas v3) | One auth/availability surface | Cronofy if cross-domain scheduling matters; Nylas v3 is domain-scoped |
+
+Why per row: the embed is zero-maintenance but a black box; the atom/API buys
+your own UI without owning sync; raw provider is full control and full
+liability; a unified API trades a vendor for not maintaining three calendar
+integrations. Hosting, auth/scopes, webhook events, cross-domain support and
+when each wins, per provider:
+[`references/provider-matrix.md`](references/provider-matrix.md).
+
+- **Cal.com** is open-source and self-hostable. Self-hosted instances get
+  **unlimited API access** (no cloud rate limit) and full white-label by
+  pointing the embed script at your own domain. REST base is `https://api.cal.com/v2`.
+- **Calendly v1 API and its webhooks were discontinued in May 2025.** Use v2
+  (REST/JSON, OAuth 2.1 or personal access token). Do not write new v1 code.
+
+## OAuth scopes — narrowest that works
+
+The default mistake is requesting the broad scope "to be safe." On Google, both
+`calendar` and `calendar.events` are **restricted scopes** — they force a
+third-party **security assessment** before you can ship to production. Avoid
+them when a granular scope does the job.
+
+```ts
+// Bad — restricted scope, blocks production until a security assessment.
+const SCOPES = ["https://www.googleapis.com/auth/calendar"];
+
+// Good — granular ladder, no restricted tier for the common booking case.
+const SCOPES = [
+  "https://www.googleapis.com/auth/calendar.app.created", // app-owned secondary calendar it creates
+  "https://www.googleapis.com/auth/calendar.freebusy",    // your own availability
+  // add only if you must read the user's existing events to compute slots:
+  "https://www.googleapis.com/auth/calendar.events.owned", // manage only events your app created
+  "https://www.googleapis.com/auth/calendar.events.freebusy", // others' busy blocks
+];
+```
+
+Scope ladder, narrowest first:
+
+- `calendar.app.created` — a dedicated secondary calendar your app creates and
+  owns. Best dodge for the restricted assessment when you only need *your* events.
+- `calendar.freebusy` / `calendar.events.freebusy` — read availability (own /
+  others') without reading event contents.
+- `calendar.readonly` / `calendar.events.readonly` — read paths only.
+- `calendar.events.owned` — write, but only events your app created.
+- `calendar` / `calendar.events` — restricted; request only if you genuinely
+  manage arbitrary events the app didn't create.
+
+## Availability without double-booking — the core flow
+
+Both classic races (computing slots in the browser, and writing the event
+before re-checking) are eliminated by doing this server-side, in order:
+
+1. **`freebusy.query`** across every relevant calendar (the host's, plus any
+   secondary calendars that block time). Never trust a cached availability blob.
+2. **Compute slots server-side** applying buffers (gap before/after),
+   **minimum notice** (no "book in 5 minutes"), working hours, and slot length.
+   The browser may *render* slots; it must never *decide* them.
+3. **Place a short-lived hold/lock** on the chosen slot (a row with a TTL, or a
+   tentative event) so a second request in the same window collides on the lock,
+   not on the calendar.
+4. **Write the event LAST** — only after the lock is held.
+5. **Re-check `freebusy` inside the write transaction.** If the slot went busy
+   between step 1 and now, abort and re-offer. This is the line that actually
+   prevents the double-book.
+
+Decision — do you need a hold step?
+
+| Situation | Hold/lock? |
+|---|---|
+| Low traffic, single host, instant write | No — steps 1→5 with the in-transaction re-check is enough |
+| Multi-step booking form, payment, or high contention | Yes — a TTL lock so the slot survives the form and releases if abandoned |
+
+Google's availability primitive is `freebusy.query` (POST, returns busy blocks
+per calendar); the write is `events.insert`. Both payloads (with
+`conferenceData` for Meet), `watch` channels + sync tokens, recurring-event edge
+cases and refresh-token handling:
+[`references/google-calendar-sync.md`](references/google-calendar-sync.md).
+
+## Timezone correctness
+
+DST is where naive scheduling code dies. Rules:
+
+- **Store the instant in UTC and carry the IANA zone id** (e.g.
+  `Europe/Andorra`) separately. Never store a bare wall-clock string.
+- **Render in the invitee's zone**, derived from the IANA id — not from a
+  browser UTC *offset*. An offset (`+02:00`) is correct only on the day it was
+  captured; it silently breaks across a DST boundary.
+- **Google event payloads MUST set `timeZone`** alongside `dateTime`, or Google
+  interprets the time in the calendar's default zone and the meeting drifts.
+
+```json
+// Bad — floating wall-clock, no zone. Drifts after the clocks change.
+{ "start": { "dateTime": "2026-10-25T10:00:00" } }
+
+// Good — instant + explicit IANA zone on both ends.
+{
+  "start": { "dateTime": "2026-10-25T10:00:00", "timeZone": "Europe/Andorra" },
+  "end":   { "dateTime": "2026-10-25T10:30:00", "timeZone": "Europe/Andorra" }
+}
+```
+
+## Webhooks that survive retries
+
+A booking is not confirmed because the embed said so — it is confirmed when the
+**webhook** says so. Providers retry, deliver duplicates, and arrive out of
+order. Your handler must assume all three.
+
+- **Verify the signature** before trusting the payload (Cal.com and Calendly
+  each sign; reject unsigned).
+- **Dedupe on the provider event id** — an idempotency key persisted before you
+  act, so a retry is a no-op.
+- **Handle the lifecycle:** Calendly fires `invitee.created` /
+  `invitee.canceled` (and routing-form submissions); Cal.com fires
+  `BOOKING_CREATED` / `BOOKING_CANCELLED` / `BOOKING_RESCHEDULED`. Map both to
+  your own created/canceled/rescheduled handlers.
+- Calendly **webhooks require a paid plan** (Standard/Teams/Enterprise) and are
+  scoped `user` or `organization`. Single-use scheduling links **expire after
+  90 days** if unused — don't hand out links you cache forever.
+
+The generic inbound-receiver scaffolding (queue, retry, replay) lives in the
+**webhooks** skill; this skill only owns the booking-specific lifecycle mapping.
+For "on booking, also create a CRM record + Slack + sheet" cross-tool fan-out,
+that orchestration is **automation-flows**, not here.
+
+## Reschedule and cancel without orphans
+
+- **Reschedule = update the same calendar event id.** Look up the event you
+  created, `events.update` (or the provider's PATCH) the times — never
+  `events.insert` a second one. The phantom-event bug is always a missing lookup.
+- **Release the freed slot** — if you held a lock or marked a row busy, free it
+  so the old time is offerable again.
+- **Cancel = delete/cancel the same event** and release the slot; record the
+  cancellation so reminders and downstream automation stop.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Compute available slots in the browser | Stale/raced data → double-book | `freebusy.query` server-side, re-check in the write txn |
+| Request `auth/calendar` for a read-only widget | Restricted scope → blocked by security assessment | Narrowest scope: `calendar.freebusy` / `calendar.app.created` |
+| Store local "wall-clock" times | Drift after DST → wrong-hour meetings | UTC instant + IANA zone; set `timeZone` on Google payloads |
+| Trust the embed for confirmation state | Embed lies on network failures | Confirm only on a signature-verified webhook |
+| Create a new event on reschedule | Orphaned phantom events pile up | `events.update` the same event id; release old slot |
+| No idempotency on the webhook | Retries duplicate the booking | Dedupe on provider event id before acting |
+| Cache a single-use scheduling link forever | Calendly links expire after 90 days | Generate on demand; treat expiry as expected |
+| Poll the calendar for changes | Slow, rate-limited, misses edits | `watch` push channels + incremental sync tokens |
+| Write new code against Calendly v1 | v1 API + webhooks dead since May 2025 | Calendly v2 (OAuth 2.1 / PAT) |
+
+Adjacent skills: raw calendar CRUD / watch channels with no booking →
+[`../google-workspace/SKILL.md`](../google-workspace/SKILL.md); charging for a
+paid appointment → [`../stripe/SKILL.md`](../stripe/SKILL.md); booking funnel as
+sales stages → [`../sales-pipeline/SKILL.md`](../sales-pipeline/SKILL.md);
+sending the confirmation email itself → [`../email-connector/SKILL.md`](../email-connector/SKILL.md).

package/skills/calendar-scheduling/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — calendar-scheduling
+
+`cases.yaml` holds three groups scored by an LLM judge against the rendered
+skill — there are no live calendar/API calls. `should_trigger` and
+`should_not_trigger` check routing: each prompt is classified and we confirm
+this skill owns it, or that it correctly defers to the named sibling (every
+`route_to` id is a real skill). `capability` checks that SKILL.md plus
+`references/` contain enough to satisfy the `must_include` rubric for a
+solo-consultant Google Calendar booking build — freebusy-first slot math, narrow
+scopes, timezone-correct writes, a verified idempotent webhook, and orphan-free
+reschedule. Run them through the repo's eval runner, which discovers
+`evals/cases.yaml` under each skill; there is no standalone harness here. Treat a
+judge miss as a signal to sharpen the description's triggers/boundary or fill a
+gap in the body, not as noise.

package/skills/calendar-scheduling/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: calendar-scheduling
+
+should_trigger:
+  - prompt: "Add a 'book a call' page to our site that shows my real availability and creates the Google Calendar event automatically."
+    why: Core build — booking surface plus calendar sync (freebusy + events.insert), the skill's whole purpose.
+  - prompt: "We keep getting double-booked when two people pick the same slot — fix it."
+    why: Non-obvious symptom phrasing; the availability race (browser-computed slots / write-before-recheck) this skill owns.
+  - prompt: "Embed Cal.com on the landing page and white-label it so there's no Cal.com branding."
+    why: Embed altitude — self-hosted Cal.com embed for full white-label.
+  - prompt: "Añade reservas de citas a la web y evita solapamientos con mi calendario de Outlook."
+    why: Spanish trigger plus multi-provider sync; routes to the unified-API path, still this skill.
+  - prompt: "Build booking inside our own UI with the Cal.com Booker atom and fire a webhook on each booking."
+    why: Booker atom altitude plus booking webhook lifecycle — both core to this skill.
+  - prompt: "Bookings show the wrong time after the clocks changed last weekend."
+    why: Non-obvious DST/timezone-drift symptom; the stored-wall-clock bug this skill prevents.
+  - prompt: "Set up minimum notice and a 15-minute buffer so nobody books me back-to-back or in 5 minutes."
+    why: Availability rules (buffers + min-notice) computed server-side — part of the core slot flow.
+
+should_not_trigger:
+  - prompt: "List and update events on my Google Calendar for an internal dashboard — there's no booking page."
+    route_to: google-workspace
+    why: Raw calendar CRUD with no booking surface; that is the boundary this skill explicitly disclaims.
+  - prompt: "Set up a generic webhook receiver with signature verification and a retry queue for several providers."
+    route_to: webhooks
+    why: Generic inbound-event infrastructure, not the booking-specific lifecycle.
+  - prompt: "When a booking is created, also create a CRM record, post to Slack, and update a Google Sheet."
+    route_to: automation-flows
+    why: Multi-tool orchestration fan-out, not the act of reserving a slot.
+  - prompt: "Charge $50 when someone books a paid appointment."
+    route_to: stripe
+    why: Payment integration, not scheduling.
+  - prompt: "Write and send the booking confirmation email so it doesn't land in spam."
+    route_to: email-connector
+    why: Email sending/deliverability, not the slot/calendar logic.
+
+capability:
+  - scenario: "Design availability + booking for a solo consultant on Google Calendar with a public booking page, preventing double-booking and timezone bugs."
+    must_include:
+      - "freebusy.query run server-side across the relevant calendars before any slot is offered."
+      - "Slots computed server-side applying buffers and minimum notice (not in the browser)."
+      - "A narrow OAuth scope (calendar.freebusy / calendar.events.owned / calendar.app.created), not restricted auth/calendar."
+      - "Event written with an explicit timeZone (IANA) and the instant stored in UTC."
+      - "A booking webhook with signature verification and idempotency on the provider event id."
+      - "Reschedule updates the same stored event id and releases the freed slot (no orphaned second event)."
+      - "Re-check freebusy inside the write transaction to close the race."

package/skills/calendar-scheduling/references/google-calendar-sync.md

@@ -0,0 +1,78 @@
+# Google Calendar sync — payloads and edge cases
+
+Facts dated 2026-06-02. Source: developers.google.com/workspace/calendar/api.
+For non-booking calendar work (internal dashboards, raw event CRUD), use the
+`google-workspace` sibling — this file is the booking-specific subset.
+
+## 1. Availability — `freebusy.query`
+
+POST `https://www.googleapis.com/calendar/v3/freeBusy`. Always query every
+calendar that can block time (primary plus secondary calendars).
+
+```json
+{
+  "timeMin": "2026-06-02T00:00:00Z",
+  "timeMax": "2026-06-09T00:00:00Z",
+  "timeZone": "Europe/Andorra",
+  "items": [{ "id": "primary" }, { "id": "team-room@group.calendar.google.com" }]
+}
+```
+
+Response returns `calendars.<id>.busy` as an array of `{start, end}` blocks.
+Compute open slots = working hours − busy − buffers − minimum-notice window,
+**server-side**. The browser renders the result; it never computes it.
+
+## 2. Write — `events.insert` (with a Meet link)
+
+POST `.../calendars/{calendarId}/events?conferenceDataVersion=1`. Set
+`timeZone` on both `start` and `end`, or the time drifts to the calendar's
+default zone.
+
+```json
+{
+  "summary": "Intro call",
+  "start": { "dateTime": "2026-10-25T10:00:00", "timeZone": "Europe/Andorra" },
+  "end":   { "dateTime": "2026-10-25T10:30:00", "timeZone": "Europe/Andorra" },
+  "attendees": [{ "email": "invitee@example.com" }],
+  "conferenceData": {
+    "createRequest": {
+      "requestId": "uuid-per-booking",
+      "conferenceSolutionKey": { "type": "hangoutsMeet" }
+    }
+  }
+}
+```
+
+Persist the returned event `id` — you need it for reschedule and cancel.
+
+## 3. Reschedule / cancel — no orphans
+
+- Reschedule → `events.update` (or PATCH) the **stored event id** with new
+  times. Never `events.insert` a second event.
+- Cancel → `events.delete` the stored id (or PATCH `status: "cancelled"`), then
+  release any slot lock so the old time is offerable again.
+
+## 4. Stay in sync — `watch` + sync tokens, not polling
+
+- **Push channels:** `events.watch` registers a channel that POSTs to your
+  callback URL on changes. Channels expire — renew before expiry.
+- **Incremental sync:** store the `nextSyncToken` from a list call; pass it as
+  `syncToken` next time to fetch only deltas. A `410 Gone` means the token
+  expired → do a full resync and capture a fresh token.
+- Polling instead is slower, rate-limited, and misses edits between polls.
+
+## 5. Recurring-event edge cases
+
+- A recurring series has one master event; individual occurrences carry a
+  `recurringEventId` pointing back to it.
+- Editing a single occurrence creates an **exception instance** — update that
+  instance's id, not the master, or you mutate the whole series.
+- When reading availability, expand instances (`singleEvents=true`) so each
+  occurrence's busy block is counted, not just the master.
+
+## 6. Refresh tokens
+
+- The refresh token arrives once (first consent with `access_type=offline`).
+  Store it; access tokens are short-lived and you mint new ones from it.
+- A `401` on an API call means refresh the access token and retry; a hard
+  refresh failure means re-consent (token revoked or scope changed).

package/skills/calendar-scheduling/references/provider-matrix.md

@@ -0,0 +1,71 @@
+# Provider matrix — which scheduling stack wins when
+
+Facts dated 2026-06-02. Pick by what you must *own*, not by brand familiarity.
+
+## Cal.com
+
+- **Hosting:** open-source, cloud or **self-hostable**. Self-host = full
+  white-label (point the embed script at your own domain, zero Cal.com brand)
+  and **unlimited API access** — no cloud rate limit to design around.
+- **REST API:** base `https://api.cal.com/v2`. `POST /v2/bookings` creates
+  regular, recurring, and instant bookings with attendee info, metadata, and
+  booking-field responses.
+- **Booking surfaces:** (a) **embed** — inline / button / modal triggers,
+  identical on cloud and self-hosted; (b) **Booker atom** — an open-source
+  modular component for a fully custom booking UI inside your app; (c) the v2
+  API for headless booking.
+- **Webhooks:** `BOOKING_CREATED` / `BOOKING_CANCELLED` / `BOOKING_RESCHEDULED`
+  (plus more). Verify the signature; dedupe on the booking id.
+- **Wins when:** you want OSS / self-host / white-label, or you need a custom UI
+  (atom) without owning calendar sync, or you want no rate-limit anxiety.
+
+## Calendly
+
+- **Auth:** OAuth 2.1 or personal access token. **v1 API and v1 webhooks were
+  discontinued in May 2025** — v2 only for new work (REST, JSON).
+- **Scheduling API:** the Create Event Invitee endpoint books meetings via API
+  with **no redirect / iframe / hosted UI** — headless booking.
+- **Single-use scheduling links expire after 90 days** if unused.
+- **Webhooks:** `invitee.created`, `invitee.canceled`, and routing-form
+  submissions. Scoped `user` or `organization`. **Require a paid plan**
+  (Standard / Teams / Enterprise).
+- **Wins when:** the org already runs Calendly and you want API booking + events
+  without standing up your own scheduler.
+
+## Google Calendar (direct, single provider)
+
+- **Availability:** `freebusy.query` (POST) returns busy blocks per calendar.
+- **Write:** `events.insert` (add `conferenceData` to attach a Meet link).
+- **Scopes:** `calendar` / `calendar.events` are **restricted** (require a
+  third-party security assessment for production). Prefer granular:
+  `calendar.app.created`, `calendar.freebusy`, `calendar.events.freebusy`,
+  `calendar.events.owned`, `calendar.readonly`.
+- **What you own:** OAuth, token refresh, `watch` push channels, incremental
+  sync via sync tokens, recurring-event edge cases.
+- **Wins when:** one provider, you need direct read/write, and you accept owning
+  the integration. Pure CRUD with no booking surface → use `google-workspace`.
+
+## Nylas v3 (unified)
+
+- **Coverage:** Google + Outlook/Exchange + Apple/iCloud behind one API, with
+  availability and free/busy endpoints.
+- **Caveat:** **domain-scoped** — availability queries are restricted within an
+  organization, so **cross-company scheduling needs multiple external calls**.
+- **Wins when:** multi-provider but single-org scheduling is fine and you don't
+  want to maintain three integrations.
+
+## Cronofy (unified)
+
+- **Coverage:** Google + Outlook/Exchange + Apple/iCloud behind one API.
+- **No domain restriction:** a single call can span domains; caches free/busy in
+  a Sync Engine.
+- **Wins when:** multi-provider AND **cross-domain** scheduling matters (booking
+  across companies in one availability call).
+
+## Quick chooser
+
+- Fastest page, no UI work → Cal.com / Calendly **embed**.
+- Own UI + own data model → Cal.com **Booker atom** or **Scheduling API**.
+- One provider, direct control → **Google direct** (`freebusy.query` + `events.insert`).
+- Many providers, single org → **Nylas v3**.
+- Many providers, cross-domain → **Cronofy**.

package/skills/calendar-scheduling/scripts/verify.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# verify.sh — calendar-scheduling lint. Run inside YOUR project against the
+# generated scheduling integration. Read-only: it greps, it never edits.
+#
+# Usage:
+#   bash scripts/verify.sh [path]      # default path: .
+#
+# Lints three definite booking hazards (a lint, not a build):
+#   1. Over-broad Google scope — restricted auth/calendar or auth/calendar.events
+#      requested where a narrower scope (calendar.freebusy, calendar.app.created,
+#      calendar.events.owned) would do.
+#   2. Timezone hazard — a Google event payload with a dateTime but no timeZone.
+#   3. Webhook unsafety — a booking webhook handler with neither a signature
+#      verification nor an idempotency key.
+#
+# Exit non-zero ONLY on a definite hazard. Empty/clean target -> exit 0.
+# Prose-only configs (docs, READMEs) pass the scope/timezone checks.
+#
+# Env: NO_COLOR=1 disables color.
+# Portability: stock macOS bash 3.2 and CI bash 5. No mapfile, no bash-4 features.
+set -euo pipefail
+
+ROOT="${1:-.}"
+
+if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
+else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
+warn() { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GRN" "$RST" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RST" "$*"; }
+
+if [[ ! -e "$ROOT" ]]; then warn "path not found: $ROOT (nothing to lint)"; exit 0; fi
+
+# Collect candidate source files (NUL-delimited; bash-3.2-safe, no mapfile).
+FILES=()
+while IFS= read -r -d '' f; do
+  FILES+=("$f")
+done < <(find "$ROOT" \
+  \( -path '*/node_modules/*' -o -path '*/vendor/*' -o -path '*/.git/*' \
+     -o -path '*/dist/*' -o -path '*/build/*' \) -prune \
+  -o -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \
+     -o -name '*.py' -o -name '*.go' -o -name '*.rb' -o -name '*.json' \
+     -o -name '*.yaml' -o -name '*.yml' -o -name '*.env*' \) -print0 2>/dev/null)
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  ok "no scheduling source files under $ROOT — nothing to lint"
+  exit 0
+fi
+
+FAILED=0
+
+# 1. Over-broad Google scope. The restricted scopes are the full-string forms;
+#    do not flag the granular .freebusy/.app.created/.events.owned/.readonly ones.
+SCOPE_HITS=""
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  if grep -Eq 'auth/calendar(\.events)?["'\'' ,)]' "$f" 2>/dev/null \
+     || grep -Eq 'auth/calendar(\.events)?$' "$f" 2>/dev/null; then
+    # exclude lines that are actually a narrower scope
+    if grep -E 'auth/calendar(\.events)?["'\'' ,)$]' "$f" 2>/dev/null \
+        | grep -Ev 'freebusy|app\.created|events\.owned|readonly|events\.freebusy' >/dev/null 2>&1; then
+      SCOPE_HITS="$SCOPE_HITS $f"
+    fi
+  fi
+done
+if [[ -n "$SCOPE_HITS" ]]; then
+  fail "restricted Google scope (auth/calendar or auth/calendar.events) found in:$SCOPE_HITS"
+  fail "  -> use calendar.freebusy / calendar.app.created / calendar.events.owned to avoid the security assessment"
+  FAILED=1
+else
+  ok "no over-broad Google calendar scopes"
+fi
+
+# 2. Timezone hazard — a Google event payload with dateTime but no timeZone in
+#    the same file. Heuristic: files mentioning dateTime must also mention timeZone.
+TZ_HITS=""
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  if grep -q 'dateTime' "$f" 2>/dev/null; then
+    if ! grep -q 'timeZone' "$f" 2>/dev/null; then
+      TZ_HITS="$TZ_HITS $f"
+    fi
+  fi
+done
+if [[ -n "$TZ_HITS" ]]; then
+  fail "event payload uses dateTime without timeZone (drifts after DST) in:$TZ_HITS"
+  fail "  -> set timeZone (IANA id) on start/end; store the instant in UTC"
+  FAILED=1
+else
+  ok "no naive datetime payloads (timeZone present where dateTime is)"
+fi
+
+# 3. Webhook unsafety — a booking webhook handler with neither signature
+#    verification nor an idempotency key.
+WH_HITS=""
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  if grep -Eiq 'invitee\.(created|canceled)|BOOKING_(CREATED|CANCELLED|RESCHEDULED)|webhook' "$f" 2>/dev/null; then
+    has_sig=0; has_idem=0
+    grep -Eiq 'signature|verifySignature|constructEvent|x-cal-signature|x-hook-signature|hmac' "$f" 2>/dev/null && has_sig=1
+    grep -Eiq 'idempoten|dedupe|event[_.]?id|already[_ ]?processed' "$f" 2>/dev/null && has_idem=1
+    if [[ $has_sig -eq 0 && $has_idem -eq 0 ]]; then
+      WH_HITS="$WH_HITS $f"
+    fi
+  fi
+done
+if [[ -n "$WH_HITS" ]]; then
+  fail "booking webhook handler with no signature verification AND no idempotency key in:$WH_HITS"
+  fail "  -> verify the provider signature and dedupe on the provider event id"
+  FAILED=1
+else
+  ok "booking webhook handlers verify a signature or dedupe (or none present)"
+fi
+
+echo
+if [[ $FAILED -ne 0 ]]; then
+  fail "calendar-scheduling lint found definite hazards above"
+  exit 1
+fi
+ok "calendar-scheduling lint clean"
+exit 0

package/skills/case-studies/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: case-studies
+description: "Use when turning one named customer's measured win into a case study, or the attributed testimonial quote that travels with it — consent-cleared, metrics-anchored proof for the next skeptical buyer. NOT the deck that sells the vision to a room (that is `pitch-deck`), NOT thought-leadership with no single named customer (that is `article-writing`)."
+tags: [case-study, testimonial, social-proof, customer-story, conversion]
+recommends: [pitch-deck, article-writing, retention, review-management, brand-voice, landing-copy]
+origin: risco
+---
+
+# case-studies
+
+You write the consent-cleared, metrics-anchored story of a customer who already won — and the short attributed quote that travels with it. Your reader is the *next* skeptical buyer, not your own marketing team. Every line either advances that buyer's decision or it is cut.
+
+A case study is a proof artifact, not a brochure. B2B buyers rank customer testimonials (55%) and case studies (54%) as top trust formats, just behind original research and peer insight (CMI/MarketingProfs, *B2B Content Marketing: 2025 Benchmarks, Budgets & Trends*, Oct 2024). They are reading to de-risk a purchase. A page that praises the vendor and hides the numbers fails that job no matter how polished the prose.
+
+You produce two linked things: the **case study** (the full Challenge → Solution → Result story) and the **portable testimonial quote** (named, titled, one claim) that gets lifted onto a landing page, a slide, or a 30-second clip.
+
+## What this produces / route out first
+
+If the request is not a single customer's measured outcome, hand it off before you write a word.
+
+| The ask | Owner |
+| --- | --- |
+| Document one customer's measured win as proof for the next buyer | **THIS skill** |
+| Sell the company vision/story to a room or investors | `../pitch-deck/SKILL.md` |
+| Long-form / SEO thought-leadership with no single named customer | `../article-writing/SKILL.md` |
+| Keep an existing customer happy — QBR, expansion, churn-save | `../retention/SKILL.md` |
+| Solicit or reply to public reviews / ratings | `../review-management/SKILL.md` |
+| The reusable cross-channel tone-of-voice rules | `../brand-voice/SKILL.md` |
+| Drop the proven quote into a converting page | `../landing-copy/SKILL.md` |
+| Price the offer this win justifies | `pricing` |
+
+The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted.
+
+## The intake gate — STOP if any of these is missing
+
+Do not start prose until you have all three. A missing piece is a gathering task or an anonymization decision, never an invention.
+
+- **The metric set** — baseline, result, timeframe, and a money figure if the customer permits it. Why: a number with no baseline or timeframe is a claim, not a result. "Increased revenue" is unfalsifiable; "€420k → €1.6M in 11 months" is proof.
+- **The named source** — a real person with title and company for the quote. Why: an anonymous "— a happy client" reads as fabricated and a same-industry, named quote lifts lead quality far more than a generic one.
+- **The consent status** — written sign-off to publish the name, quote, logo, and numbers. Why: publishing an un-consented named customer is the legal failure mode, not a style miss (see below).
+
+If you lack a metric → ask for it or do not claim it. If you lack consent → anonymize honestly ("a 200-seat logistics SaaS") or do not ship. Never round a vague number up to look better.
+
+## The legal + consent floor
+
+This is the hard floor, not a nicety. The FTC Consumer Reviews and Testimonials Rule has been in force since 21 October 2024, with penalties up to ~$53,088 per violation (the FTC's max is inflation-adjusted annually — this is the figure effective 17 Jan 2025; re-check FTC.gov before quoting it as current).
+
+- **Real customer, honest statement.** No fabricated, scripted, or insider testimonial presented as an ordinary customer. If the speaker is an employee, investor, or affiliate, you must add a clear-and-conspicuous material-connection disclosure or drop the quote.
+- **Substantiation.** You may not publish a metric you cannot back with a source. If you cannot point to the data, the number does not go in.
+- **Written consent, kept.** Get sign-off before publishing the name, exact quote, logo, image, and figures. An email confirmation suffices, but it must be retained.
+- **Edit the quote only with approval.** You may tighten a quote for clarity, but the customer must approve the edited wording — you cannot change what they meant.
+
+Carry the consent state in the artifact's front-matter so it is impossible to ship a story whose status is unknown:
+
+```yaml
+---
+customer: "Acme Logistics"
+consent: signed          # signed | pending | anonymized
+approved: 2026-05-28     # date the customer signed off on the exact quote
+quote_source: "interview-2026-05-20.txt"
+---
+```
+
+`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, consent/release checklist, approval-email wording, substantiation and insider-disclosure notes, and the anonymization fallback rules live in `references/consent-and-substantiation.md`.
+
+## Case-study anatomy
+
+Write the sections in this order. Each earns its place; cut anything that does not advance the buyer's decision. Target **600–1,200 words** — long enough to prove the result, short enough that a busy buyer finishes it.
+
+1. **Results headline** — one KPI, the single most important number. Why: it is the only line many readers see. "Fraud cut to 0.10% in 8 weeks," not the customer's company name.
+2. **Snapshot box** — above the fold: industry, region, products used, and the headline KPIs. Why: a skeptical buyer self-qualifies in seconds ("same industry as us? same size?").
+3. **Challenge** — the measurable pain before, in the customer's words. Why: the buyer must see their own problem to care about the fix.
+4. **Solution** — what was implemented and how, concrete and specific. Why: vague "we partnered closely" proves nothing; "migrated 1,200 SKUs to the new pricing engine in two sprints" proves capability.
+5. **Result** — the before/after numbers with timeframe, as Context-Achievement-Relevance lines (below). Why: this is the proof the whole piece exists to deliver.
+6. **Attributed quote** — named + title + company, one specific claim. Why: the human voice is the conversion lever, and the quote is what travels onto other surfaces.
+7. **Decision-stage CTA** — one next step matched to where the reader now is ("See pricing," "Book a 20-min fit call"). Why: proof with no next step wastes the intent it just built.
+
+The ordered skeleton and a filled mini-example with real-shaped numbers are in `references/case-study-skeleton.md`.
+
+## Metrics-first
+
+Collect the numbers before you write any prose. The story is built around the data, not decorated with it.
+
+Write each result as a **Context → Achievement → Relevance** line: what changed, the measured lift, and what it was worth.
+
+```text
+Bad:  "The new workflow improved efficiency significantly and the team is much happier."
+Good: "Restructuring lead nurturing (context) drove a 43% conversion lift (achievement),
+       generating €1.2M in additional annual revenue (relevance)."
+
+Bad:  "We helped them process invoices faster."
+Good: "Cut invoice-processing time from 6 days to 4 hours (−97%) within the first quarter."
+```
+
+A result that lacks a baseline or a timeframe is not a result — it is an unfalsifiable claim. Always pair before with after, and always state the window.
+
+## Testimonial / quote craft
+
+The quote is the conversion lever, so make it carry weight. Specific beats glowing. One claim per quote — a quote that says three things says nothing.
+
+```text
+Bad:  "Great product, the team is amazing, highly recommend! — a happy customer"
+Good: "We cut new-hire onboarding from 3 weeks to 2 days — my team stopped dreading
+       every new starter. — Ana Pérez, COO, Acme Logistics"
+```
+
+Rules:
+
+- **Named + title + company.** Attribution is what makes it believable. Anonymous quotes read as invented.
+- **Same industry wins.** A quote from the prospect's own sector lifts lead quality; match where you can.
+- **One concrete claim.** Tie the quote to a number or a felt change, not to adjectives.
+- **The customer's voice, not yours.** If it sounds like your marketing, the buyer discounts it. Approve any edit with the customer.
+
+## Format leverage — write once, cut many
+
+Default to a repurposable structure, because video is now the top-rated B2B content format (58% rate it most effective, with case studies/customer stories close behind at 53% — CMI/MarketingProfs *2025 Benchmarks*, Oct 2024) and testimonials are a measured conversion lever, not decoration: a three-line testimonial block lifted landing-page conversion 34% in VWO's WikiJob A/B test, and Unbounce reported swapping static reviews for video testimonials lifted conversion up to 80%. From one signed-off case study you should be able to cut, with no new approval needed:
+
+- a **pull-stat card** (the headline KPI on its own),
+- a **quote card** (the attributed testimonial),
+- a **30–60s video script** (challenge in one line, result in one line, the quote read aloud).
+
+Write the prose so these fall out cleanly; do not produce a separate brochure for each. (This is the cut, not a full video-production guide — that craft lives elsewhere.)
+
+## Anti-patterns
+
+| Bad | Good |
+| --- | --- |
+| Hero headline is the customer's company name | Hero is the result + a number ("Churn cut 40% in one quarter") |
+| "Increased revenue" with no baseline or window | baseline → result → timeframe, every time |
+| Publish the quote before the customer signs off | Exact-quote written approval first, retained |
+| Anonymous "— a satisfied client" | Named + title + company, or anonymize the whole story honestly |
+| Superlatives: "revolutionary", "seamless", "best-in-class" | Verifiable specifics with units |
+| Insider/employee quote presented as a customer | Clear material-connection disclosure, or drop it |
+| Vendor-praise narrative ("we are proud to...") | Buyer-serving proof ("here is what changed for them") |
+| One 2,500-word wall of prose | 600–1,200 words, snapshot box up top, scannable |
+| A metric you cannot source | Only published numbers you can substantiate on demand |
+
+## Verify + handoffs
+
+`scripts/verify.sh <case-study.md>` is a read-only structural and legal lint. It checks for a quantified hero metric, the required Challenge/Solution/Result sections and snapshot box, an attributed quote, a before→after signal, a CTA, and the `consent:` / `approved:` marker — and it warns on the superlative banlist. It **fails hard** when the hero has no metric, a core section is missing, or consent is unmarked, because shipping an un-consented named quote is the legal risk. It is structural lint only; persuasion quality is the capability eval's job and yours.
+
+Hand off when the piece is done: the proven quote → `../landing-copy/SKILL.md`, the broader narrative → `../article-writing/SKILL.md`, the slide version → `../pitch-deck/SKILL.md`, the public-review angle → `../review-management/SKILL.md`.