@assembly-js/app-foundation 0.0.24 → 0.0.25-rc.1

package/CLAUDE.md

@@ -54,6 +54,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-db-transactions` — REQUIRED when a route makes more than one DB write: `db.transaction()` is unsupported on neon-http and 500s. Use `db.batch([...])` for atomic multi-writes, sequential awaits otherwise.
 - `assembly-session-token` — the bearer lifecycle and how to read identity or fetch data: `getSessionIdentity()`/`useAssembly()`, `useServerAction`/`callAction`, `authFetch`. You never handle a token yourself.
 - `assembly-route-auth` — REQUIRED on every `app/api/.../[id]/route.ts` handler: `requireAuth` + `requireCompanyScope` before returning or mutating data.
+- `assembly-scheduled-work` — REQUIRED when the prompt implies anything on a schedule or while nobody has the app open (remind, daily digest, every week, follow up in N days, at a specific time): one `*/30 * * * *` Vercel cron in `vercel.json` hitting one dispatcher route, every scheduled action a row in a schedule table, `CRON_SECRET` declared in `requiredSecrets` and verified on every tick, `getOfflineAssembly()` for platform calls. Checking for due work on page load ships a schedule that never fires.
 - `assembly-route-errors` — REQUIRED in every route handler: use `handleRouteError` from `@assembly-js/app-foundation/server` in catch blocks — never return `err.message`. Validate values before they hit typed DB columns (e.g. `parseUuid` before a uuid-column lookup).
 - `assembly-dev-server-logs` — the dev server's stdout/stderr (server-side errors, stack traces, console output) is readable at `/tmp/dev-server.log`; check it before guessing at a 500 or broken preview.
 
@@ -709,6 +710,8 @@ export async function PATCH(
 
 #### Offline bearer — background work with no user (cron, webhooks)
 
+**Anything on a schedule — a reminder, a digest, a recurring send — must first read the `assembly-scheduled-work` skill.** The route below only ever runs if `vercel.json` declares a cron for it and the route verifies `CRON_SECRET`; the offline bearer is the auth half, the skill is the scheduling half.
+
 Everything above resolves the **viewer's** bearer from the request cookie. Some code runs with **no user in the loop and no cookie**: a scheduled job, or an incoming third-party webhook. There, call `getOfflineAssembly()` — it mints a short-lived, **app-scoped** bearer from your app API key (`ASSEMBLY_API_KEY`) via `POST /v1/token` and returns a bearer-only client, exactly like the user path but authenticated as the app rather than a viewer.
 
 ```ts

package/bin/check-crons.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// Fails the build when scheduled work is half-wired. A cron route that no
+// `vercel.json` entry invokes never runs; an entry pointing at a missing route
+// 404s forever; a cron route without the platform-managed secret is a public
+// endpoint that mutates workspace data; and a cron faster than the platform's
+// floor keeps the app's database awake around the clock. Every one of those
+// passes typecheck and `next build` and only shows up after publish, when
+// nobody is looking — so the app's own build is the gate. Dependency free on
+// purpose: it runs inside the generated app's sandbox before any deps beyond
+// Node are guaranteed.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const APP_DIR = join(ROOT, 'app');
+const VERCEL_JSON = join(ROOT, 'vercel.json');
+const MANIFEST = join(ROOT, '.assembly', 'app.json');
+
+// The conventional home for cron routes; a route here with no schedule is the
+// "looked right in preview, never ran in production" bug this guard exists for.
+const CRON_ROUTE_PREFIX = '/api/cron/';
+// Vercel sends this env var as the bearer on every cron invocation; the platform
+// mints it at deploy when the manifest declares it.
+const CRON_SECRET_KEY = 'CRON_SECRET';
+// Platform floor: a poller faster than this never lets the app's database scale
+// to zero, which costs more than the work it does.
+const MIN_INTERVAL_MINUTES = 30;
+const ROUTE_FILE = /^route\.(tsx|ts|jsx|js)$/;
+
+function fail(lines) {
+  console.error('');
+  console.error('Scheduled work is not wired correctly:');
+  console.error('');
+  for (const l of lines) console.error('  - ' + l);
+  console.error('');
+  console.error('Every scheduled app needs all of these together:');
+  console.error('  1. One dispatcher route under app/api/cron/ that verifies the cron secret.');
+  console.error('  2. A matching entry in vercel.json, no more often than every 30 minutes:');
+  console.error('       { "crons": [{ "path": "/api/cron/dispatch", "schedule": "*/30 * * * *" }] }');
+  console.error(`  3. "${CRON_SECRET_KEY}" declared in .assembly/app.json requiredSecrets (the platform mints it).`);
+  console.error('See the assembly-scheduled-work skill.');
+  process.exit(1);
+}
+
+function readJson(file, label) {
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    fail([`${label} is not valid JSON: ${e.message}`]);
+  }
+  return doc;
+}
+
+function routeFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...routeFiles(full));
+    } else if (ROUTE_FILE.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// The URL segments a route file serves; route groups `(group)` and parallel
+// slots `@slot` never appear in the URL.
+function urlSegmentsForRouteFile(file) {
+  return relative(APP_DIR, file)
+    .split(sep)
+    .slice(0, -1)
+    .filter((seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'));
+}
+
+// A dynamic segment (`[id]`, `[...slug]`) matches anything Vercel could put in
+// that position of a cron path.
+function routeServes(routeSegments, pathSegments) {
+  if (routeSegments.some((seg) => seg.startsWith('[...') || seg.startsWith('[['))) {
+    const fixed = routeSegments.findIndex((seg) => seg.startsWith('[...') || seg.startsWith('[['));
+    return pathSegments.length >= fixed && routeSegments.slice(0, fixed).every((seg, i) => seg === pathSegments[i]);
+  }
+  if (routeSegments.length !== pathSegments.length) return false;
+  return routeSegments.every((seg, i) => (seg.startsWith('[') && seg.endsWith(']')) || seg === pathSegments[i]);
+}
+
+function expandField(field, lo, hi) {
+  const values = new Set();
+  for (const part of field.split(',')) {
+    let range = part;
+    let step = 1;
+    if (part.includes('/')) {
+      const [r, s] = part.split('/');
+      range = r;
+      step = Number(s);
+      if (!Number.isInteger(step) || step < 1) return null;
+    }
+    let start;
+    let end;
+    if (range === '*') {
+      start = lo;
+      end = hi;
+    } else if (range.includes('-')) {
+      [start, end] = range.split('-').map(Number);
+    } else {
+      start = Number(range);
+      end = part.includes('/') ? hi : start;
+    }
+    if (![start, end].every(Number.isInteger) || start < lo || end > hi || start > end) return null;
+    for (let v = start; v <= end; v += step) values.add(v);
+  }
+  return values;
+}
+
+const MONTH_NAMES = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
+const DAY_NAMES = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+
+// Month and day-of-week accept names as well as numbers; normalise to numbers
+// so one range parser covers all five fields. Only a whole token is a name —
+// `JAN-MAR` becomes `1-3`, while `JANJAN` or `MONDAY` stay as they are and
+// fail the numeric parse, as they would on Vercel.
+function numericField(field, names, base) {
+  return names.reduce(
+    (acc, name, i) => acc.replace(new RegExp(`\\b${name}\\b`, 'g'), String(i + base)),
+    field.toUpperCase(),
+  );
+}
+
+// Smallest gap, in minutes, between two consecutive firings of a 5-field cron
+// expression. Returns null for an expression Vercel would reject, in any field.
+function minIntervalMinutes(schedule) {
+  const fields = schedule.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const minutes = expandField(fields[0], 0, 59);
+  const hours = expandField(fields[1], 0, 23);
+  const daysOfMonth = expandField(fields[2], 1, 31);
+  const months = expandField(numericField(fields[3], MONTH_NAMES, 1), 1, 12);
+  // 7 is Sunday again in most cron dialects, so the range runs to 7.
+  const daysOfWeek = expandField(numericField(fields[4], DAY_NAMES, 0), 0, 7);
+  if ([minutes, hours, daysOfMonth, months, daysOfWeek].some((f) => !f || f.size === 0)) return null;
+  if (minutes.size === 1) return 60;
+  const sorted = [...minutes].sort((a, b) => a - b);
+  const gaps = sorted.slice(1).map((m, i) => m - sorted[i]);
+  // The last firing of one hour and the first of the next only neighbour when
+  // the expression fires in two consecutive hours.
+  const consecutiveHours = [...hours].some((h) => hours.has((h + 1) % 24));
+  if (consecutiveHours) gaps.push(60 - sorted[sorted.length - 1] + sorted[0]);
+  return Math.min(...gaps);
+}
+
+function declaredSecrets() {
+  if (!existsSync(MANIFEST)) return new Set();
+  const manifest = readJson(MANIFEST, '.assembly/app.json');
+  const secrets = Array.isArray(manifest?.requiredSecrets) ? manifest.requiredSecrets : [];
+  return new Set(secrets.map((s) => (typeof s?.key === 'string' ? s.key.trim() : '')));
+}
+
+// Only the two forms the skill prescribes count as verifying the secret, and
+// comments are stripped first so a copied auth comment above an unguarded
+// handler cannot pass. Form 1: the exported handler IS the cronRoute wrapper.
+// Form 2: the hand-rolled check the Go-tree skill has the agent copy — reads
+// the env var, compares the authorization header with the Bearer prefix, and
+// returns 401.
+const EXPORTED_CRON_ROUTE = /export\s+(?:const|let)\s+(?:GET|POST)\s*(?::[^=]+)?=\s*cronRoute\s*\(/;
+function verifiesCronSecret(source) {
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+  if (EXPORTED_CRON_ROUTE.test(code)) return true;
+  return (
+    code.includes(`process.env.${CRON_SECRET_KEY}`) &&
+    /headers\.get\(\s*['"`]authorization['"`]\s*\)/i.test(code) &&
+    /['"`]Bearer\s/.test(code) &&
+    /\b401\b/.test(code)
+  );
+}
+
+const crons = existsSync(VERCEL_JSON) ? readJson(VERCEL_JSON, 'vercel.json').crons : undefined;
+const allRoutes = routeFiles(APP_DIR).map((file) => ({ file, segments: urlSegmentsForRouteFile(file) }));
+const cronRoutes = allRoutes.filter((r) => ('/' + r.segments.join('/') + '/').startsWith(CRON_ROUTE_PREFIX));
+
+if (crons === undefined && cronRoutes.length === 0) process.exit(0);
+
+const problems = [];
+if (crons !== undefined && !Array.isArray(crons)) {
+  problems.push('vercel.json "crons" must be an array of { "path", "schedule" } entries.');
+}
+const entries = Array.isArray(crons) ? crons : [];
+const coveredRoutes = new Set();
+
+entries.forEach((entry, i) => {
+  const label = `vercel.json crons[${i}]`;
+  if (typeof entry?.path !== 'string' || !entry.path.startsWith('/')) {
+    problems.push(`${label}: "path" must be a string starting with "/".`);
+    return;
+  }
+  if (typeof entry?.schedule !== 'string' || !entry.schedule.trim()) {
+    problems.push(`${label} (${entry.path}): "schedule" must be a 5-field cron expression.`);
+    return;
+  }
+  const pathSegments = entry.path.replace(/\/+$/, '').split('/').filter(Boolean);
+  const route = allRoutes.find((r) => routeServes(r.segments, pathSegments));
+  if (!route) {
+    problems.push(
+      `${label}: "${entry.path}" has no route file — Vercel would call it and get a 404 on every tick. ` +
+        `Add app${entry.path}/route.ts or fix the path.`,
+    );
+  } else {
+    coveredRoutes.add(route.file);
+  }
+  const interval = minIntervalMinutes(entry.schedule);
+  if (interval === null) {
+    problems.push(`${label} (${entry.path}): "${entry.schedule}" is not a valid 5-field cron expression.`);
+  } else if (interval < MIN_INTERVAL_MINUTES) {
+    problems.push(
+      `${label} (${entry.path}): "${entry.schedule}" fires every ${interval} minutes; the floor is every ` +
+        `${MIN_INTERVAL_MINUTES}. Use "*/30 * * * *" and keep per-action cadences in the app's schedule table.`,
+    );
+  }
+});
+
+for (const route of cronRoutes) {
+  const url = '/' + route.segments.join('/');
+  if (!coveredRoutes.has(route.file)) {
+    problems.push(
+      `${relative(ROOT, route.file)} serves ${url} but no vercel.json cron entry invokes it — it will never run ` +
+        `after publish. Add { "path": "${url}", "schedule": "*/30 * * * *" } to "crons" or remove the route.`,
+    );
+  }
+}
+
+if (entries.length > 0) {
+  if (!declaredSecrets().has(CRON_SECRET_KEY)) {
+    problems.push(
+      `.assembly/app.json requiredSecrets does not declare "${CRON_SECRET_KEY}" — without it Vercel sends no ` +
+        `bearer and the cron route cannot tell a real tick from a stranger. Add ` +
+        `{ "key": "${CRON_SECRET_KEY}", "label": "Cron secret" }; the platform mints the value at deploy.`,
+    );
+  }
+  for (const file of coveredRoutes) {
+    if (!verifiesCronSecret(readFileSync(file, 'utf8'))) {
+      problems.push(
+        `${relative(ROOT, file)} is invoked by a cron but its exported handler does not verify ${CRON_SECRET_KEY} — ` +
+          `anyone who guesses the URL can trigger it. Either export the handler as ` +
+          `\`export const GET = cronRoute(async () => …)\`, or read \`process.env.${CRON_SECRET_KEY}\`, compare it ` +
+          `to the request's \`authorization\` header with the \`Bearer \` prefix, and return 401 before any work.`,
+      );
+    }
+  }
+}
+
+if (problems.length > 0) fail(problems);

package/dist/cron.d.ts

@@ -0,0 +1,40 @@
+import { type NextRequest } from 'next/server';
+export type CronHandler = (request: NextRequest) => Promise<Response> | Response;
+/**
+ * Reports whether a request carries the cron secret Vercel attaches to
+ * scheduled invocations. Fails closed when the env var is unset: a deploy that
+ * lost the secret must reject every tick rather than accept every caller.
+ */
+export declare function isCronRequest(request: NextRequest): boolean;
+/**
+ * Wraps a cron route handler so it only runs for Vercel's scheduler. Every
+ * other caller gets a 401 and the handler never executes.
+ *
+ * ```ts
+ * // app/api/cron/dispatch/route.ts
+ * export const GET = cronRoute(async () => {
+ *   // claim due rows, run them, advance next run
+ *   return Response.json({ ok: true });
+ * });
+ * ```
+ */
+export declare function cronRoute(handler: CronHandler): (request: NextRequest) => Promise<Response>;
+/** The fields of a schedule row that decide when it runs next. */
+export interface ScheduleCadence {
+    /** The run that just happened (or was due). Advancing from it, not from now, keeps a 9:00 daily at 9:00. */
+    nextRunAt: Date;
+    /** Minutes between runs. Whole days keep their wall-clock time across DST. */
+    cadenceMinutes: number;
+    /** IANA zone the wall-clock time is anchored in, e.g. `America/New_York`. */
+    timezone: string;
+}
+/**
+ * The first occurrence of a recurring schedule strictly after `now`.
+ *
+ * Advances from the scheduled time rather than from `now`, so a 9:00 daily
+ * stays a 9:00 daily, and skips every missed occurrence so a gap never causes
+ * a catch-up storm. Sub-daily cadences are fixed intervals; daily and coarser
+ * ones keep their wall-clock time in the row's timezone, so a 9:00 reminder is
+ * still 9:00 after a daylight-saving change.
+ */
+export declare function nextRunAfter(row: ScheduleCadence, now: Date): Date;

package/dist/cron.js

@@ -0,0 +1,87 @@
+import { NextResponse } from 'next/server';
+// Vercel sends the project's CRON_SECRET env var as `Authorization: Bearer
+// <value>` on every cron invocation. The platform mints that value at deploy,
+// so a route only has to compare — but hand-rolled comparisons are the single
+// most common way generated cron routes fail (wrong header, missing prefix,
+// comparing against a user-typed value), and a route that skips the check is a
+// public endpoint that mutates workspace data.
+const CRON_SECRET_ENV = 'CRON_SECRET';
+const BEARER_PREFIX = 'Bearer ';
+/**
+ * Reports whether a request carries the cron secret Vercel attaches to
+ * scheduled invocations. Fails closed when the env var is unset: a deploy that
+ * lost the secret must reject every tick rather than accept every caller.
+ */
+export function isCronRequest(request) {
+    const expected = process.env[CRON_SECRET_ENV];
+    if (!expected)
+        return false;
+    return request.headers.get('authorization') === `${BEARER_PREFIX}${expected}`;
+}
+/**
+ * Wraps a cron route handler so it only runs for Vercel's scheduler. Every
+ * other caller gets a 401 and the handler never executes.
+ *
+ * ```ts
+ * // app/api/cron/dispatch/route.ts
+ * export const GET = cronRoute(async () => {
+ *   // claim due rows, run them, advance next run
+ *   return Response.json({ ok: true });
+ * });
+ * ```
+ */
+export function cronRoute(handler) {
+    return async (request) => {
+        if (!isCronRequest(request)) {
+            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        }
+        return handler(request);
+    };
+}
+const DAY_MINUTES = 24 * 60;
+function wallClock(at, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+    }).formatToParts(at);
+    const read = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return { year: read('year'), month: read('month'), day: read('day'), hour: read('hour'), minute: read('minute') };
+}
+// The instant at which `timeZone` reads `wc`. Date.UTC rolls an overflowing
+// day into the next month, which is what makes "+N days" safe at month ends.
+function zonedToUtc(wc, timeZone) {
+    const guess = Date.UTC(wc.year, wc.month - 1, wc.day, wc.hour, wc.minute);
+    const seen = wallClock(new Date(guess), timeZone);
+    const seenAsUtc = Date.UTC(seen.year, seen.month - 1, seen.day, seen.hour, seen.minute);
+    return new Date(guess - (seenAsUtc - guess));
+}
+/**
+ * The first occurrence of a recurring schedule strictly after `now`.
+ *
+ * Advances from the scheduled time rather than from `now`, so a 9:00 daily
+ * stays a 9:00 daily, and skips every missed occurrence so a gap never causes
+ * a catch-up storm. Sub-daily cadences are fixed intervals; daily and coarser
+ * ones keep their wall-clock time in the row's timezone, so a 9:00 reminder is
+ * still 9:00 after a daylight-saving change.
+ */
+export function nextRunAfter(row, now) {
+    const step = row.cadenceMinutes;
+    if (step % DAY_MINUTES !== 0) {
+        let next = row.nextRunAt.getTime() + step * 60_000;
+        while (next <= now.getTime())
+            next += step * 60_000;
+        return new Date(next);
+    }
+    const days = step / DAY_MINUTES;
+    let next = row.nextRunAt;
+    do {
+        const wc = wallClock(next, row.timezone);
+        next = zonedToUtc({ ...wc, day: wc.day + days }, row.timezone);
+    } while (next.getTime() <= now.getTime());
+    return next;
+}

package/dist/lib-client.js

@@ -18,8 +18,8 @@ let renewalInFlight = null;
 // for the freshest session token (the parent keeps it alive) and posts it to the
 // re-exchange route, which mints a new bearer and sets the HttpOnly cookie — no
 // page reload. Returns true iff a fresh bearer was set. This is the only place
-// app code touches the raw session token, and only to re-mint; it is never sent
-// to the platform API.
+// app code touches the raw session token, to re-mint and keep the URL aligned
+// with the cookie; it is never sent to the platform API.
 export function reexchangeBearer() {
     if (renewalInFlight)
         return renewalInFlight;
@@ -30,6 +30,9 @@ export function reexchangeBearer() {
     return renewal;
 }
 async function renewBearer() {
+    const previousUrlToken = typeof window === 'undefined'
+        ? null
+        : new URL(window.location.href).searchParams.get('token');
     let token = AssemblyBridge.sessionToken.getCurrent()?.token ?? '';
     // Proactively refresh: we're recovering from an expiry, so avoid re-minting
     // from a session token that may itself be stale.
@@ -55,6 +58,19 @@ async function renewBearer() {
             bridgeRefreshFailed,
             status: res.status,
         });
+        if (res.ok && previousUrlToken !== null) {
+            try {
+                const url = new URL(window.location.href);
+                // Don't overwrite a new preview session opened while renewal was in flight.
+                if (url.searchParams.get('token') === previousUrlToken) {
+                    url.searchParams.set('token', token);
+                    window.history.replaceState(window.history.state, '', url.href);
+                }
+            }
+            catch {
+                // A history update failure must not invalidate the cookie just renewed.
+            }
+        }
         return res.ok;
     }
     catch {

package/dist/mint-bearer.js

@@ -55,7 +55,13 @@ export async function mintBearerFromSessionToken(token, options) {
     try {
         const resp = await assembly.fetch('/v1/session', {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'Content-Type': 'application/json',
+                // Let /session validate the token in the body. The SDK's three-part
+                // key makes the authorizer reject expired tokens with a generic 403
+                // before the handler can distinguish a replay from an outage.
+                'X-API-Key': `${payload.workspaceId}/${process.env.ASSEMBLY_API_KEY ?? ''}`,
+            },
             body: JSON.stringify({
                 sessionId: payload.tokenId,
                 ...(options?.cookieSessionId

package/dist/server.d.ts

@@ -9,6 +9,7 @@ export * from './gmail.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
+export * from './cron.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -13,6 +13,7 @@ export * from './gmail.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
+export * from './cron.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.24",
+  "version": "0.0.25-rc.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-scheduled-work/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: assembly-scheduled-work
+description: REQUIRED when the prompt implies anything happening on a schedule or while nobody has the app open — "remind", "every day/week/month", "daily digest", "follow up in N days", "at a specific time", "recurring", "expire after", "send later". Covers the one-dispatcher Vercel cron pattern (a schedule table + one cron entry + CRON_SECRET + cronRoute + getOfflineAssembly), the 30-minute floor, and the check-on-page-load anti-pattern that silently ships a schedule that never fires.
+---
+
+A published app has no process running between requests. Anything that must happen at a time — not because someone clicked — only happens if **Vercel's scheduler calls a route of yours**. That is a cron, and it is declared in `vercel.json`, not in code.
+
+## The anti-pattern this skill exists to stop
+
+❌ Store a `dueAt` on a row and check for due rows when a page loads, in a `useEffect`, or on a `setInterval`. It passes every test and works in the builder preview, because the preview always has the app open. Published, nothing runs until someone happens to open the app — a "remind me at 3pm" arrives the next morning. This is the single most common way scheduled apps fail.
+
+✅ One cron entry, one dispatcher route, every scheduled action as a row the dispatcher reads. The four parts below always ship **together** — any one missing makes the schedule silently dead, and the build check `check-crons.mjs` fails the build when they disagree.
+
+## The shape: one dispatcher, everything is a row
+
+| Part | Where | What |
+|---|---|---|
+| Schedule table | `lib/schema.ts` | one row per scheduled action: what to do, its cadence, when it next runs |
+| Cron entry | `vercel.json` | `{ "path": "/api/cron/dispatch", "schedule": "*/30 * * * *" }` |
+| Cron secret | `.assembly/app.json` → `requiredSecrets` | `{ "key": "CRON_SECRET", "label": "Cron secret" }` — the platform mints the value |
+| Dispatcher route | `app/api/cron/dispatch/route.ts` | wrapped in `cronRoute`; claims due rows, runs them, advances `nextRunAt` |
+
+Fixed cadences from the prompt ("daily summary at 9") and schedules users create at runtime ("remind Sarah on the 21st") are the **same thing**: rows. The cron list only changes on deploy, so never add a cron entry per action and never let a user-created schedule depend on one. "Notify every hour", "daily at 9", "monthly on the 1st" is one cron entry and three rows.
+
+## 1. Schedule table
+
+```ts
+// lib/schema.ts
+export const scheduledActions = pgTable('scheduled_actions', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  action: text('action').notNull(),                 // which handler runs, e.g. 'client-reminder'
+  payload: jsonb('payload').$type<Record<string, unknown>>().notNull(),
+  cadenceMinutes: integer('cadence_minutes'),       // null ⇒ one-off
+  timezone: text('timezone').notNull(),             // IANA, e.g. 'America/New_York' — for "9:00 local"
+  nextRunAt: timestamp('next_run_at', { withTimezone: true }).notNull(),
+  status: text('status').notNull().default('pending'), // pending | running | done | failed
+  claimedAt: timestamp('claimed_at', { withTimezone: true }), // set while running; frees a stuck row
+  lastRunAt: timestamp('last_run_at', { withTimezone: true }),
+  lastError: text('last_error'),
+});
+```
+
+Validate on write: **a recurrence is a multiple of 30 minutes** (`cadenceMinutes >= 30 && cadenceMinutes % 30 === 0`) and **a one-off time is on the hour or half hour**. Reject anything else in the route; how the form keeps the user inside those bounds is your design.
+
+## 2. Cron entry — merge into the existing `vercel.json`
+
+The repo already has a `vercel.json`. **Add the `crons` key; keep every existing key.** Replacing the file drops platform settings.
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "git": { "deploymentEnabled": false },
+  "crons": [{ "path": "/api/cron/dispatch", "schedule": "*/30 * * * *" }]
+}
+```
+
+`*/30 * * * *` is the tick. One entry per app is the rule; a second entry is only for a fixed job that genuinely cannot be a row. Never schedule anything more often than every 30 minutes — the build check rejects it, and a faster poller keeps the app's database awake around the clock for nothing.
+
+## 3. Cron secret — declare it, never ask for it
+
+Vercel authenticates its own invocations by sending the project's `CRON_SECRET` env var as `Authorization: Bearer <value>`. Declare it as a required secret and the platform generates the value at deploy and sets it on the Vercel project:
+
+```json
+{
+  "surfaces": { "internal": { "path": "/" } },
+  "requiredSecrets": [{ "key": "CRON_SECRET", "label": "Cron secret" }]
+}
+```
+
+It is **platform-managed**: it never appears in the user's config form, never gates publish, and the user never sees or types it. Do not invent a value, do not put it in `.env*`, do not fall back to a default when it is unset.
+
+## 4. Dispatcher route — claim, run, advance
+
+Create `lib/scheduled-actions.ts` yourself: it exports `runAction(assembly, row)`, which switches on `row.action` and does the actual work for that kind (send the notification, update the record). The dispatcher below stays generic — it never knows what an action does, only how to claim, run, and advance it.
+
+```ts
+// app/api/cron/dispatch/route.ts
+import { and, eq, lt, lte, or } from 'drizzle-orm';
+import { cronRoute, getOfflineAssembly, nextRunAfter } from '@assembly-js/app-foundation/server';
+import { db } from '@/lib/db';
+import { scheduledActions } from '@/lib/schema';
+import { runAction } from '@/lib/scheduled-actions';
+
+// A tick Vercel stops mid-run never reaches its catch block, so its rows stay
+// "running"; after this long the next tick may take them back.
+const STALE_CLAIM_MS = 15 * 60_000;
+
+export const GET = cronRoute(async () => {
+  const now = new Date();
+  const claimable = or(
+    eq(scheduledActions.status, 'pending'),
+    and(
+      eq(scheduledActions.status, 'running'),
+      lt(scheduledActions.claimedAt, new Date(now.getTime() - STALE_CLAIM_MS)),
+    ),
+  );
+  const due = await db.query.scheduledActions.findMany({
+    where: and(claimable, lte(scheduledActions.nextRunAt, now)),
+    limit: 50,
+  });
+
+  const assembly = await getOfflineAssembly(); // app-scoped bearer — no viewer here
+  let ran = 0;
+  for (const row of due) {
+    // Claim first: the conditional update wins for exactly one caller, so an
+    // overlapping or duplicated tick cannot run the same row twice.
+    const [claimed] = await db
+      .update(scheduledActions)
+      .set({ status: 'running', claimedAt: now })
+      .where(and(eq(scheduledActions.id, row.id), claimable))
+      .returning();
+    if (!claimed) continue;
+
+    try {
+      await runAction(assembly, claimed);
+      await db.update(scheduledActions).set(advance(claimed, now)).where(eq(scheduledActions.id, claimed.id));
+      ran++;
+    } catch (err) {
+      // One failing row must not poison the batch; leave it for the next tick.
+      await db
+        .update(scheduledActions)
+        .set({ status: 'pending', claimedAt: null, lastError: err instanceof Error ? err.message : String(err) })
+        .where(eq(scheduledActions.id, claimed.id));
+    }
+  }
+  return Response.json({ ok: true, ran });
+});
+
+// One-offs finish. Recurring rows get their next occurrence from the scheduled
+// time — never from now — skipping anything missed, and daily or coarser
+// cadences keep their wall-clock time in the row's timezone across DST.
+function advance(row: typeof scheduledActions.$inferSelect, now: Date) {
+  const cleared = { lastRunAt: now, lastError: null, claimedAt: null };
+  if (row.cadenceMinutes == null) return { ...cleared, status: 'done' as const };
+  const next = nextRunAfter({ ...row, cadenceMinutes: row.cadenceMinutes }, now);
+  return { ...cleared, status: 'pending' as const, nextRunAt: next };
+}
+```
+
+Rules that fall out of this:
+
+- **`cronRoute` is not optional.** The route is a public URL; without the wrapper anyone who guesses it can trigger the app's scheduled work under the app's own credentials. Never hand-roll the header check.
+- **Use `getOfflineAssembly()`** for every platform call — there is no viewer and no cookie. `getSessionIdentity()` is `null` here, so a notification's `senderId` must be chosen explicitly (a system/admin internal user); see `assembly-notifications`.
+- **A missed tick is harmless.** Vercel does not retry, but the row stays due until it is marked, so the next tick picks it up. Never mark a row done before its work succeeded.
+- **A stuck row frees itself.** If Vercel stops the function mid-run, the catch never runs and the row stays `running`; the stale-claim clause lets the next tick reclaim it after 15 minutes. Keep `claimedAt` and that clause — without them one hang parks a row forever.
+- **Never compute the next run by adding minutes to `now`.** Use `nextRunAfter`: it anchors to the scheduled time, skips missed occurrences, and keeps daily cadences on their local wall-clock time across daylight-saving changes.
+- **Keep each tick short.** Bound the batch (`limit`), do the work per row, return. A tick that runs past 30 minutes overlaps the next one; the claim makes that safe, but it is still a sign the work belongs in smaller pieces.
+
+## Cadence and time
+
+- **Every target is a tick.** Because recurrences are multiples of 30 minutes and one-off times sit on :00 or :30, each action fires on the tick that matches its target; a tick Vercel misses is picked up by the next one. Nothing needs to explain a delivery window.
+- **Cron runs in UTC.** Store `nextRunAt` as an absolute instant and keep the user's IANA `timezone` on the row so "every day at 9:00" recomputes correctly across DST. Convert the user's local pick to UTC when writing the row; never store a naive local time.
+- **Calendar cadences** that are not a fixed number of days ("monthly on the 1st", "last Friday") are one-off rows: `runAction` inserts the next occurrence when it runs, computing the date in the row's timezone.
+- **Floor is 30 minutes** for recurrence, and every recurrence is a multiple of it. "Every 5 minutes" and "every 45 minutes" are both rejected.
+
+## Verify before publish
+
+Crons **never fire in the builder preview**; only a published app has Vercel's scheduler. Exercise the dispatcher directly — `CRON_SECRET` is in the preview shell env:
+
+```bash
+curl -sS -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/dispatch
+```
+
+Insert a row with `nextRunAt` in the past, run that, and confirm the side effect and the advanced `nextRunAt`. Then tell the user, in plain words, that the schedule starts running once the app is published. `bun run build` runs `check-crons.mjs`, which fails on a cron route without an entry, an entry without a route, a missing `CRON_SECRET` declaration, or a schedule faster than every 30 minutes — fix the wiring it names rather than deleting the check.
+
+## Don'ts
+
+- ❌ Don't check for due work on page load, in a client timer, or in middleware. Only the cron runs when nobody is looking.
+- ❌ Don't add one cron entry per action or per user. Actions are rows; there is one dispatcher.
+- ❌ Don't declare a cron faster than `*/30 * * * *`, and don't accept a recurrence that is not a multiple of 30 minutes or a one-off time off the half hour.
+- ❌ Don't skip `cronRoute` or compare the header yourself.
+- ❌ Don't type, invent, or default `CRON_SECRET`. Declare it; the platform mints it.
+- ❌ Don't call `getAssembly()` in the dispatcher. There is no viewer; use `getOfflineAssembly()`.
+- ❌ Don't replace `vercel.json`. Add `crons` to it.