SKILL.md- the skill, written out in plain English

criteria:
  - name: calendar_dump_generated
    kind: deterministic
    check: "The command `npx tsx state/bin/calendar/dump-week.ts` successfully generates a JSON file in `state/log/calendar/`."
  - name: gcal_lib_used
    kind: judge
    check: "The `state/bin/calendar/dump-week.ts` script uses `state/lib/gcal.ts` for calendar access, not `state/lib/calendar.ts`."
  - name: valid_json_output
    kind: deterministic
    check: "The generated JSON file in `state/log/calendar/` is valid and well-formed according to `jsonlint`."
  - name: correct_event_shape
    kind: judge
    check: "The events in the generated JSON adhere to the expected `Schema$Event` structure as described for `listEvents`."
  - name: share_gap_logging_present
    kind: judge
    check: "If the calendar dump is empty and `listCalendars()` reports zero accessible calendars, a P1 friction is logged."

AGENTS.md- what the AI loads when this skill comes up

echo "[$(date -u +%FT%TZ)] calendar: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] calendar: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-calendar/api.ts -- Google Calendar API (direct) for all snappy-* skills.
 *
 * Auth: Google service account JWT → access token.
 * Requires in .env.cache:
 *   GOOGLE_SERVICE_ACCOUNT_EMAIL  (already present)
 *   GOOGLE_SERVICE_ACCOUNT_KEY    (PEM private key, newlines as \n)
 *   GOOGLE_CALENDAR_ID            (optional, defaults to "primary")
 *
 * To add the key: export from GCP console → Service Accounts → Keys → JSON.
 * Copy the "private_key" field value into .env.cache as GOOGLE_SERVICE_ACCOUNT_KEY.
 * The calendar must be shared with the service account email.
 *
 * Usage:
 *   npx tsx api.ts events              # today's events
 *   npx tsx api.ts events 7            # this week
 *   npx tsx api.ts availability        # free/busy blocks
 *   npx tsx api.ts create '{"summary":"Call","start_time":"...","end_time":"..."}'
 *   npx tsx api.ts update '{"event_id":"...","summary":"..."}'
 *   npx tsx api.ts delete <eventId>
 *
 * Or import as module:
 *   import { listEvents, createEvent, updateEvent, deleteEvent, checkAvailability } from "./calendar.ts";
 */

import { env } from "./env.ts";
import { createSign } from "crypto";
import { realpathSync } from "fs";

const GCAL_API = "https://www.googleapis.com/calendar/v3";
const TOKEN_URL = "https://oauth2.googleapis.com/token";
const SCOPE = "https://www.googleapis.com/auth/calendar";

let _accessToken: string | null = null;
let _tokenExpiry = 0;

function calendarId(): string {
  return env("GOOGLE_CALENDAR_ID", false) || "primary";
}

function base64url(input: Buffer | string): string {
  const buf = typeof input === "string" ? Buffer.from(input) : input;
  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

function buildJwt(): string {
  const email = env("GOOGLE_SERVICE_ACCOUNT_EMAIL");
  const key = env("GOOGLE_SERVICE_ACCOUNT_KEY").replace(/\\n/g, "\n");
  const now = Math.floor(Date.now() / 1000);

  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
  const payload = base64url(
    JSON.stringify({
      iss: email,
      scope: SCOPE,
      aud: TOKEN_URL,
      iat: now,
      exp: now + 3600,
    }),
  );

  const sign = createSign("RSA-SHA256");
  sign.update(`${header}.${payload}`);
  const signature = base64url(sign.sign(key));

  return `${header}.${payload}.${signature}`;
}

async function getAccessToken(): Promise<string> {
  if (_accessToken && Date.now() / 1000 < _tokenExpiry - 60) {
    return _accessToken;
  }

  const jwt = buildJwt();
  const res = await fetch(TOKEN_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: `grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=${jwt}`,
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(`Google token exchange failed (${res.status}): ${JSON.stringify(data)}`);
  }

  _accessToken = data.access_token;
  _tokenExpiry = Math.floor(Date.now() / 1000) + data.expires_in;
  return _accessToken!;
}

async function gcal(method: string, path: string, body?: Record<string, unknown>) {
  const token = await getAccessToken();
  const res = await fetch(`${GCAL_API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  if (res.status === 204) return {};

  const data = await res.json();
  if (!res.ok) {
    throw new Error(
      `Calendar API ${method} ${path} failed (${res.status}): ${JSON.stringify(data)}`,
    );
  }
  return data;
}

// --- Public API ---

export async function listEvents(days = 1) {
  const now = new Date();
  const timeMin = now.toISOString();
  const end = new Date(now);
  end.setDate(end.getDate() + days);
  const timeMax = end.toISOString();

  const params = new URLSearchParams({
    timeMin,
    timeMax,
    singleEvents: "true",
    orderBy: "startTime",
    maxResults: "100",
  });

  return gcal("GET", `/calendars/${encodeURIComponent(calendarId())}/events?${params}`);
}

export async function createEvent(data: {
  summary: string;
  start_time: string;
  end_time: string;
  description?: string;
  location?: string;
  attendees?: string[];
}) {
  const body: Record<string, unknown> = {
    summary: data.summary,
    start: { dateTime: data.start_time },
    end: { dateTime: data.end_time },
  };
  if (data.description) body.description = data.description;
  if (data.location) body.location = data.location;
  if (data.attendees?.length) {
    body.attendees = data.attendees.map((email) => ({ email }));
  }

  return gcal("POST", `/calendars/${encodeURIComponent(calendarId())}/events`, body);
}

export async function updateEvent(eventId: string, updates: Record<string, unknown>) {
  const mapped: Record<string, unknown> = {};

  if (updates.summary) mapped.summary = updates.summary;
  if (updates.description) mapped.description = updates.description;
  if (updates.location) mapped.location = updates.location;
  if (updates.start_time) mapped.start = { dateTime: updates.start_time };
  if (updates.end_time) mapped.end = { dateTime: updates.end_time };
  if (Array.isArray(updates.attendees)) {
    mapped.attendees = (updates.attendees as string[]).map((email) => ({ email }));
  }

  return gcal(
    "PATCH",
    `/calendars/${encodeURIComponent(calendarId())}/events/${encodeURIComponent(eventId)}`,
    mapped,
  );
}

export async function deleteEvent(eventId: string) {
  return gcal(
    "DELETE",
    `/calendars/${encodeURIComponent(calendarId())}/events/${encodeURIComponent(eventId)}`,
  );
}

/**
 * Return calendar events where `email` appears in the attendees list, looking
 * both backward and forward from today. Sorted by start desc, capped at 20.
 *
 * This backs snappy-knowledge.resolvePerson()'s `recent_calendar` field. The
 * previous listEvents(days) forward-only scan is a hack — use this instead.
 *
 * Default window: 90 days back, 60 days forward (configurable).
 */
export async function eventsByAttendee(
  email: string,
  opts: { daysBack?: number; daysForward?: number; limit?: number } = {},
): Promise<any[]> {
  const daysBack = opts.daysBack ?? 90;
  const daysForward = opts.daysForward ?? 60;
  const limit = opts.limit ?? 20;

  const now = new Date();
  const timeMin = new Date(now);
  timeMin.setDate(timeMin.getDate() - daysBack);
  const timeMax = new Date(now);
  timeMax.setDate(timeMax.getDate() + daysForward);

  const params = new URLSearchParams({
    timeMin: timeMin.toISOString(),
    timeMax: timeMax.toISOString(),
    singleEvents: "true",
    orderBy: "startTime",
    maxResults: "250",
    q: email, // server-side free-text hint; we still filter attendee list below
  });

  const data = await gcal("GET", `/calendars/${encodeURIComponent(calendarId())}/events?${params}`);

  const items: any[] = Array.isArray(data?.items) ? data.items : [];
  const needle = email.toLowerCase();

  const matches = items.filter((ev) => {
    const attendees: any[] = Array.isArray(ev?.attendees) ? ev.attendees : [];
    return attendees.some((a) => (a?.email || "").toLowerCase() === needle);
  });

  matches.sort((a, b) => {
    const ad = a?.start?.dateTime || a?.start?.date || "";
    const bd = b?.start?.dateTime || b?.start?.date || "";
    return bd.localeCompare(ad);
  });

  return matches.slice(0, limit);
}

export async function checkAvailability(days = 1) {
  const now = new Date();
  const end = new Date(now);
  end.setDate(end.getDate() + days);

  return gcal("POST", "/freeBusy", {
    timeMin: now.toISOString(),
    timeMax: end.toISOString(),
    items: [{ id: calendarId() }],
  });
}

// --- Scheduling (merged from snappy-scheduling) ---

const PREFERRED_WINDOWS = [
  { startHour: 11, endHour: 13 }, // 11 AM - 1 PM
  { startHour: 15, endHour: 17 }, // 3 PM - 5 PM
];
const HARD_END = 18;
const PROTECTED_END = 11; // 9-11 AM deep work
const BUFFER_MINUTES = 15;

/**
 * Find available slots in the next N days that respect Robert's preferences.
 * Returns proposed 30-min (or custom duration) slots.
 */
export async function proposeSlots(
  days = 3,
  durationMinutes = 30,
): Promise<Array<{ start: string; end: string; preferred: boolean }>> {
  const events = await listEvents(days);
  const busy: Array<{ start: number; end: number }> = [];

  if (events.items) {
    for (const ev of events.items) {
      const s = ev.start?.dateTime ? new Date(ev.start.dateTime).getTime() : null;
      const e = ev.end?.dateTime ? new Date(ev.end.dateTime).getTime() : null;
      if (s && e) {
        busy.push({
          start: s - BUFFER_MINUTES * 60 * 1000,
          end: e + BUFFER_MINUTES * 60 * 1000,
        });
      }
    }
  }

  const slots: Array<{ start: string; end: string; preferred: boolean }> = [];
  const now = new Date();

  for (let d = 0; d < days; d++) {
    const date = new Date(now);
    date.setDate(date.getDate() + d);
    const dow = date.getDay();
    if (dow === 0 || dow === 6) continue; // skip weekends
    if (dow === 5) continue; // skip Friday afternoon per preferences

    for (let hour = PROTECTED_END; hour < HARD_END; hour++) {
      const slotStart = new Date(date);
      slotStart.setHours(hour, 0, 0, 0);
      const slotEnd = new Date(slotStart.getTime() + durationMinutes * 60 * 1000);

      if (
        slotEnd.getHours() > HARD_END ||
        (slotEnd.getHours() === HARD_END && slotEnd.getMinutes() > 0)
      )
        continue;
      if (slotStart.getTime() < now.getTime()) continue;

      const conflict = busy.some((b) => slotStart.getTime() < b.end && slotEnd.getTime() > b.start);
      if (conflict) continue;

      const preferred = PREFERRED_WINDOWS.some((w) => hour >= w.startHour && hour < w.endHour);

      slots.push({
        start: slotStart.toISOString(),
        end: slotEnd.toISOString(),
        preferred,
      });
    }
  }

  slots.sort((a, b) => (b.preferred ? 1 : 0) - (a.preferred ? 1 : 0));
  return slots;
}

// --- CLI ---

if (
  (() => {
    try {
      return import.meta.url === `file://${realpathSync(process.argv[1])}`;
    } catch {
      return false;
    }
  })()
) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "today": {
        const data = await listEvents(1);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "events": {
        const days = args[0] ? parseInt(args[0], 10) : 1;
        const data = await listEvents(days);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "by-attendee": {
        const [email] = args;
        if (!email) {
          console.error("Usage: api.ts by-attendee <email>");
          process.exit(1);
        }
        const data = await eventsByAttendee(email);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "availability": {
        const days = args[0] ? parseInt(args[0], 10) : 1;
        const data = await checkAvailability(days);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "create": {
        if (!args[0]) {
          console.error(
            'Usage: api.ts create \'{"summary":"...","start_time":"...","end_time":"..."}\'',
          );
          process.exit(1);
        }
        const data = await createEvent(JSON.parse(args[0]));
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "update": {
        if (!args[0]) {
          console.error('Usage: api.ts update \'{"event_id":"...","summary":"..."}\'');
          process.exit(1);
        }
        const parsed = JSON.parse(args[0]);
        const { event_id, ...updates } = parsed;
        const data = await updateEvent(event_id, updates);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "delete": {
        if (!args[0]) {
          console.error("Usage: api.ts delete <eventId>");
          process.exit(1);
        }
        await deleteEvent(args[0]);
        console.log("deleted");
        break;
      }
      case "propose": {
        const days = args[0] ? parseInt(args[0], 10) : 3;
        const duration = args[1] ? parseInt(args[1], 10) : 30;
        const slots = await proposeSlots(days, duration);
        if (slots.length) {
          console.log(
            `Found ${slots.length} available ${duration}-min slots (next ${days} days):\n`,
          );
          for (const s of slots.slice(0, 10)) {
            const d = new Date(s.start);
            const day = d.toLocaleDateString("en-US", {
              weekday: "short",
              month: "short",
              day: "numeric",
            });
            const time = d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
            console.log(
              `  ${s.preferred ? "*" : " "} ${day} ${time}${s.preferred ? " (preferred)" : ""}`,
            );
          }
          if (slots.length > 10) console.log(`  ... and ${slots.length - 10} more`);
        } else {
          console.log("No available slots found.");
        }
        break;
      }
      default:
        console.log(
          "Usage: npx tsx api.ts [today|events|availability|create|update|delete|propose] ...",
        );
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs