@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/helpdesk/lib/search.ts

@@ -1,15 +1,16 @@
 // Client-side search powering the ⌘K palette.
 //
-// A small team's CRM fits in the synced replica, so search runs locally against
+// A small team's workspace fits in the synced replica, so search runs locally against
 // data already in memory: results appear as you type, with no request per
 // keystroke. Swap in `db.useSearch` (Pylon's FTS) when a workspace outgrows
 // that — the component boundary doesn't change, only this file.
 
 export interface SearchItem {
   id: string;
-  type: "deal" | "company" | "contact";
+  /** The record kind, such as "deal". The palette picks its icon from this. */
+  type: string;
   title: string;
-  /** Second line: the company for a contact, the domain for a company. */
+  /** Shown on the right of the row: the company for a contact, say. */
   subtitle?: string;
   href: string;
   /** Extra text matched but not displayed — an email, say. */

package/templates/helpdesk/lib/seed.ts

@@ -7,6 +7,40 @@
 //
 // Pure data + pure shaping; `functions/seedWorkspace.ts` stays a thin wrapper.
 
+/**
+ * The demo support team. Each becomes a User row with no
+ * password (see lib/demo-team.ts); they exist so tickets have realistic assignees.
+ */
+export interface SeedAgent {
+  name: string;
+  email: string;
+}
+
+export const SEED_TEAM: SeedAgent[] = [
+  { name: "Maya Castillo", email: "maya.castillo@demo.invalid" },
+  { name: "Jordan Ellis", email: "jordan.ellis@demo.invalid" },
+  { name: "Aisha Karim", email: "aisha.karim@demo.invalid" },
+  { name: "Noah Brandt", email: "noah.brandt@demo.invalid" },
+];
+
+/** How many unanswered tickets, from the top of SEED_TICKETS, stay unassigned. */
+export const SEED_UNASSIGNED = 4;
+
+/**
+ * Who the seeded ticket at `index` is assigned to, as a position in
+ * `[you, ...SEED_TEAM]`, or null for unassigned. The first SEED_UNASSIGNED
+ * unanswered tickets in SEED_TICKETS wait in the queue; everything else is spread across the
+ * team, including the person who signed up.
+ */
+export function seedAssignee(
+  index: number,
+  answered: boolean,
+  teamSize: number = SEED_TEAM.length + 1,
+): number | null {
+  if (!answered && index < SEED_UNASSIGNED) return null;
+  return (index * 3 + 1) % teamSize;
+}
+
 export interface SeedCustomer {
   key: string;
   name: string;
@@ -226,7 +260,13 @@ export const SEED_MESSAGES: SeedMessage[] = [
 
 export interface ShapedSeed {
   customers: Array<{ key: string; row: Record<string, unknown> }>;
-  tickets: Array<{ key: string; customer: string; row: Record<string, unknown> }>;
+  /** `assignee` is a position in `[you, ...SEED_TEAM]`, or null; see seedAssignee. */
+  tickets: Array<{
+    key: string;
+    customer: string;
+    assignee: number | null;
+    row: Record<string, unknown>;
+  }>;
   messages: Array<{ ticket: string; row: Record<string, unknown> }>;
 }
 
@@ -244,9 +284,10 @@ export function shapeSeed(now: number = Date.now()): ShapedSeed {
       key: c.key,
       row: { name: c.name, email: c.email, company: c.company, createdAt: hoursAgo(2000 - index * 60) },
     })),
-    tickets: SEED_TICKETS.map((t) => ({
+    tickets: SEED_TICKETS.map((t, index) => ({
       key: t.key,
       customer: t.customer,
+      assignee: seedAssignee(index, t.respondedAgo !== null),
       row: {
         subject: t.subject,
         status: t.status,

package/templates/helpdesk/lib/tickets.ts

@@ -69,40 +69,52 @@ export function isOpen(ticket: { status: string }): boolean {
 
 export type SlaState = "met" | "due" | "breached" | "none";
 
+export interface Sla {
+  state: SlaState;
+  /**
+   * Whole minutes to the first-response target while `due` (at least 1), or
+   * minutes past it once `breached` (at most -1). Null when there is no
+   * target to chase. Rounded away from zero, so a label never reads "0m".
+   */
+  minutes: number | null;
+}
+
 /**
  * Where a ticket stands against its first-response target.
  *
  *   met      — an agent has already replied
- *   breached — no reply and the window has passed
- *   due      — no reply, inside the window
+ *   breached — no reply and the deadline has passed
+ *   due      — no reply, before the deadline
  *   none     — terminal, or unparseable dates; nothing to chase
  *
  * A solved ticket that was answered late is still `met`: the SLA question is
  * "did we reply", and re-flagging closed work just adds noise to the queue.
+ *
+ * State and minutes come from one calculation, so the badge can't say
+ * "breached" next to a number that rounds to zero.
  */
-export function slaState(
-  ticket: Ticket,
-  now: number = Date.now(),
-): SlaState {
-  if (!isOpen(ticket)) return "none";
-  if (ticket.firstRespondedAt) return "met";
+export function sla(ticket: Ticket, now: number = Date.now()): Sla {
+  if (!isOpen(ticket)) return { state: "none", minutes: null };
+  if (ticket.firstRespondedAt) return { state: "met", minutes: null };
   const created = Date.parse(ticket.createdAt ?? "");
-  if (!Number.isFinite(created)) return "none";
   const hours = priorityById(ticket.priority)?.firstResponseHours;
-  if (hours === undefined) return "none";
-  return now > created + hours * 3_600_000 ? "breached" : "due";
+  if (!Number.isFinite(created) || hours === undefined) {
+    return { state: "none", minutes: null };
+  }
+  const remainingMs = created + hours * 3_600_000 - now;
+  if (remainingMs > 0) {
+    return { state: "due", minutes: Math.ceil(remainingMs / 60_000) };
+  }
+  return { state: "breached", minutes: -Math.max(1, Math.ceil(-remainingMs / 60_000)) };
+}
+
+export function slaState(ticket: Ticket, now: number = Date.now()): SlaState {
+  return sla(ticket, now).state;
 }
 
 /** Minutes left before the first-response target, negative once breached. */
-export function minutesToBreach(
-  ticket: Ticket,
-  now: number = Date.now(),
-): number | null {
-  if (!isOpen(ticket) || ticket.firstRespondedAt) return null;
-  const created = Date.parse(ticket.createdAt ?? "");
-  const hours = priorityById(ticket.priority)?.firstResponseHours;
-  if (!Number.isFinite(created) || hours === undefined) return null;
-  return Math.round((created + hours * 3_600_000 - now) / 60_000);
+export function minutesToBreach(ticket: Ticket, now: number = Date.now()): number | null {
+  return sla(ticket, now).minutes;
 }
 
 /**
@@ -171,6 +183,42 @@ export function applyFilter(tickets: Ticket[], filter: Filter): Ticket[] {
   });
 }
 
+export interface InboxTab {
+  id: string;
+  label: string;
+  /** Status the tab shows; undefined shows every status. */
+  status?: string;
+}
+
+/** The inbox's tabs, left to right. */
+export const INBOX_TABS: InboxTab[] = [
+  { id: "open", label: "Open", status: "open" },
+  { id: "pending", label: "Pending", status: "pending" },
+  { id: "solved", label: "Solved", status: "solved" },
+  { id: "closed", label: "Closed", status: "closed" },
+  { id: "all", label: "All" },
+];
+
+/** The tab the inbox opens on. The sidebar's Inbox count is this tab's count. */
+export const DEFAULT_INBOX_TAB = "open";
+
+/** The filter behind an inbox tab, optionally narrowed to unassigned tickets. */
+export function inboxFilter(tabId: string, unassigned = false): Filter {
+  const tab = INBOX_TABS.find((t) => t.id === tabId);
+  return {
+    ...(tab?.status ? { status: tab.status } : {}),
+    ...(unassigned ? { unassigned: true } : {}),
+  };
+}
+
+/**
+ * How many tickets an inbox tab lists. The sidebar badge, the tab counts, and
+ * the list all go through this and `inboxFilter`, so they always agree.
+ */
+export function inboxCount(tickets: Ticket[], tabId: string, unassigned = false): number {
+  return applyFilter(tickets, inboxFilter(tabId, unassigned)).length;
+}
+
 /** "#1042" — short, stable, and greppable in an email thread. */
 export function ticketNumber(id: string, createdAt?: string | null): string {
   // Derived from the id so it needs no counter and can't collide across

package/templates/helpdesk/tests/components.test.tsx

@@ -88,6 +88,16 @@ describe("SlaIndicator", () => {
     expect(container.textContent).toContain("over");
   });
 
+  test("a ticket seconds past its deadline reads 1m over, not 0m over", () => {
+    const justLate = {
+      ...tickets[0],
+      priority: "urgent",
+      createdAt: new Date(NOW - 3_600_000 - 5_000).toISOString(),
+    };
+    const { container } = render(<SlaIndicator ticket={justLate} now={NOW} />);
+    expect(container.textContent).toBe("1m over");
+  });
+
   test("renders nothing once answered", () => {
     // A badge on every row is a badge that means nothing.
     const { container } = render(<SlaIndicator ticket={tickets[1]} now={NOW} />);

package/templates/helpdesk/tests/demo-team.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { demoEmail, isDemoRow } from "../lib/demo-team";
+
+describe("demo teammates", () => {
+  test("the first address is the person's own, then numbered aliases", () => {
+    expect(demoEmail("maya.castillo@demo.invalid", 0)).toBe("maya.castillo@demo.invalid");
+    expect(demoEmail("maya.castillo@demo.invalid", 1)).toBe("maya.castillo+2@demo.invalid");
+    expect(demoEmail("maya.castillo@demo.invalid", 2)).toBe("maya.castillo+3@demo.invalid");
+  });
+
+  test("a registered account is never reused as a demo teammate", () => {
+    // Someone who registered a demo address first must not be handed the
+    // seeded records.
+    expect(isDemoRow({ email: "x@demo.invalid", passwordHash: "argon2id$..." })).toBe(false);
+    expect(isDemoRow({ email: "x@demo.invalid", emailVerified: "2026-07-01T00:00:00Z" })).toBe(false);
+    expect(isDemoRow({ email: "x@demo.invalid", displayName: "Maya Castillo" })).toBe(true);
+  });
+});

package/templates/helpdesk/tests/tickets.test.ts

@@ -8,6 +8,11 @@ import {
   isValidPriority,
   isValidStatus,
   minutesToBreach,
+  DEFAULT_INBOX_TAB,
+  INBOX_TABS,
+  inboxCount,
+  inboxFilter,
+  sla,
   queueOrder,
   slaState,
   ticketNumber,
@@ -112,6 +117,41 @@ describe("minutesToBreach", () => {
     ).toBeNull();
     expect(minutesToBreach(ticket({ status: "closed" }), NOW)).toBeNull();
   });
+
+  test("seconds past the deadline is breached by 1m, never 0m", () => {
+    // An urgent ticket (1h window) that arrived 1h and 20s ago used to read
+    // "0m over": breached by the clock, rounded to zero minutes.
+    const late = ticket({
+      priority: "urgent",
+      createdAt: new Date(NOW - 3_600_000 - 20_000).toISOString(),
+    });
+    expect(slaState(late, NOW)).toBe("breached");
+    expect(minutesToBreach(late, NOW)).toBe(-1);
+  });
+
+  test("seconds before the deadline is due in 1m, never 0m", () => {
+    const close = ticket({
+      priority: "urgent",
+      createdAt: new Date(NOW - 3_600_000 + 20_000).toISOString(),
+    });
+    expect(slaState(close, NOW)).toBe("due");
+    expect(minutesToBreach(close, NOW)).toBe(1);
+  });
+
+  test("exactly at the deadline counts as breached", () => {
+    const edge = ticket({ priority: "urgent", createdAt: hoursAgo(1) });
+    expect(slaState(edge, NOW)).toBe("breached");
+    expect(minutesToBreach(edge, NOW)).toBe(-1);
+  });
+
+  test("state and minutes always agree in sign", () => {
+    for (let s = 3_500; s <= 3_700; s += 1) {
+      const t = ticket({ priority: "urgent", createdAt: new Date(NOW - s * 1000).toISOString() });
+      const result = sla(t, NOW);
+      if (result.state === "breached") expect(result.minutes!).toBeLessThanOrEqual(-1);
+      if (result.state === "due") expect(result.minutes!).toBeGreaterThanOrEqual(1);
+    }
+  });
 });
 
 describe("queueOrder", () => {
@@ -213,3 +253,33 @@ describe("ticketNumber", () => {
     expect(ticketNumber("abc", "2026-01-01")).toMatch(/^#\d{4}$/);
   });
 });
+
+describe("inbox counts", () => {
+  const queue = [
+    ticket({ id: "a", status: "open" }),
+    ticket({ id: "b", status: "open", assigneeId: "u1" }),
+    ticket({ id: "c", status: "pending" }),
+    ticket({ id: "d", status: "solved" }),
+  ];
+
+  test("the default tab's count is exactly the rows it lists", () => {
+    // The sidebar once counted open + pending (3) while the list showed only
+    // open (2). Both now come from inboxCount on the default tab.
+    expect(inboxCount(queue, DEFAULT_INBOX_TAB)).toBe(
+      applyFilter(queue, inboxFilter(DEFAULT_INBOX_TAB)).length,
+    );
+    expect(inboxCount(queue, DEFAULT_INBOX_TAB)).toBe(2);
+  });
+
+  test("every tab counts what it lists, with and without the unassigned toggle", () => {
+    for (const tab of INBOX_TABS) {
+      for (const unassigned of [false, true]) {
+        expect(inboxCount(queue, tab.id, unassigned)).toBe(
+          applyFilter(queue, inboxFilter(tab.id, unassigned)).length,
+        );
+      }
+    }
+    expect(inboxCount(queue, "all")).toBe(4);
+    expect(inboxCount(queue, "open", true)).toBe(1);
+  });
+});

package/templates/imessage/.env.example

@@ -0,0 +1,49 @@
+# Copy to `.env` and fill in. `pylon dev` loads `.env` automatically.
+# Never commit .env: it holds your API keys and shared secrets.
+
+# ── Owner ────────────────────────────────────────────────────────────────────
+# The dashboard belongs to the account with this email. Sign in at /login with
+# an email code; Pylon promotes the account to admin once the code proves the
+# address. Everyone else sees nothing.
+PYLON_ADMIN_EMAILS=you@example.com
+
+# ── Model provider (required for replies) ───────────────────────────────────
+# Without a key, texts are stored and marked "Waiting for setup"; nothing is
+# sent back. The model id is in lib/assistant.ts (ASSISTANT_MODEL).
+# ANTHROPIC_API_KEY=sk-ant-...
+# or: PYLON_LLM_PROVIDER=openai + OPENAI_API_KEY=sk-...  (also change ASSISTANT_MODEL)
+
+# ── Transport: pick one ──────────────────────────────────────────────────────
+# sendblue: Sendblue's hosted iMessage API
+# relay:    the relay script on your own Mac (relay/)
+IMESSAGE_TRANSPORT=sendblue
+
+# Sendblue (https://dashboard.sendblue.com → API keys)
+# SENDBLUE_API_KEY=
+# SENDBLUE_API_SECRET=
+# SENDBLUE_FROM_NUMBER=+15125550100
+# Webhook secret: at least 24 random characters (openssl rand -hex 32). Set the
+# same value as the webhook secret in Sendblue for the receive webhook
+# https://<your app>/api/webhooks/sendblueWebhook
+# SENDBLUE_WEBHOOK_SECRET=
+
+# Mac relay: at least 24 random characters (openssl rand -hex 32). The relay's
+# relay/.env holds the same value. Treat it like your Apple ID password: its
+# holder can post texts as any sender and read every queued reply.
+# RELAY_TOKEN=
+
+# Record outbound messages without sending them (both transports).
+# IMESSAGE_DRY_RUN=1
+#
+# `pylon dev` never sends: replies are recorded as "Dry run". A dev server
+# listens on your local network and returns sign-in codes in its responses, so
+# anyone on the network who knows your email could act as you. Set this only
+# on a trusted network, to test real delivery:
+# IMESSAGE_ALLOW_DEV_SENDS=1
+
+# ── Production only ──────────────────────────────────────────────────────────
+# The server runs the agent as the owner by calling its own API. It needs its
+# public origin and the admin token to open that session. `pylon dev` needs
+# neither (it falls back to http://127.0.0.1:$PYLON_PORT).
+# APP_URL=https://assistant.example.com
+# PYLON_ADMIN_TOKEN=

package/templates/imessage/AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md: working in a Pylon project
+
+Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one Rust process on one port. Treat this app as production infrastructure: it supports real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploys. Declare entities, policies, and server functions in TypeScript; the binary handles the runtime. Read the full API reference at https://docs.pylonsync.com/llms-full.txt before guessing an API name.
+
+## This app
+
+An AI assistant people text over iMessage. Read README.md first; it covers the
+transports, the owner model, and production setup.
+
+- **Two transports behind one interface** (`lib/transport.ts`): Sendblue
+  (`lib/sendblue.ts`, webhook at `/api/webhooks/sendblueWebhook`) and the Mac
+  relay (`relay/`, endpoint `/api/fn/relaySync`). `IMESSAGE_TRANSPORT` picks one.
+- **Every inbound text goes through `ingestInbound` in `lib/store.ts`**: dedupe
+  on the transport's message id, allowlist and rate limit (`lib/gate.ts`), then
+  schedule `processTurn`. Do not add a second path that skips it.
+- **The agent is `functions/assistant.ts` (`agent()`, `auth: "admin"`).**
+  `processTurn` runs it as the owner through `lib/agent-call.ts`. Tools must
+  resolve their contact with `currentTurn(ctx)` and never accept a contact,
+  handle, or id from the model.
+- **The dashboard is owner-only.** Every entity policy is `auth.isAdmin`; the
+  owner is the verified email in `PYLON_ADMIN_EMAILS`.
+- **AppleScript:** `relay/applescript.ts` passes text and handle as argv to a
+  fixed script. Never build AppleScript source from message content.
+- **Tests:** `bun test tests` covers webhook verification, idempotency, the
+  allowlist, relay auth, AppleScript argv, the chat.db reader (against a
+  fixture database), and reply chunking. Run it after every change.
+
+## Directory conventions
+
+**Unified SSR app:**
+- `app.ts`: data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))` — that line is the manifest handoff (the CLI parses this file's stdout), not debug output. Never remove it.
+- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. A `(group)` directory is stripped from the URL — `app/(marketing)/about/page.tsx` still serves `/about` — so a group's `layout.tsx` gives one section its own chrome (nav, footer) without changing any path; routes outside the group render without it. `app/layout.tsx` is the document shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/globals.css`: Tailwind v4 entrypoint (auto-compiled and injected).
+- `functions/`: server functions, one per file, `default`-exported.
+- `.pylon/`: local dev state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
+
+**Monorepo app:** backend is `apps/api/` (entry `apps/api/schema.ts`, handlers in `apps/api/functions/`); frontend in `apps/web/`. `pylon.manifest.json` / `pylon.client.ts` are generated; do not hand-edit.
+
+## The core authoring loop
+
+1. **Define an entity:** `entity("Thing", { name: field.string(), done: field.boolean().default(false) })`. Modifiers: `.optional()`, `.unique()`, `.readonly()` (settable on insert, rejected on client update; use for `authorId`/`orgId`), `.serverOnly()` (never in HTTP responses), `.encrypted()` (AEAD at rest, needs `PYLON_ENCRYPTION_KEY`), `.crdt("text")` (collaborative). `field.json()` stores an arbitrary JSON value (object/array/scalar), parsed-on-read on every surface; validator twin is `v.json()`.
+2. **Write a policy:** `policy({ entity: "Thing", allowRead, allowInsert, allowUpdate, allowDelete })` with CEL-like expressions over `auth.*` / `data.*` (e.g. `"auth.userId == data.authorId"`). Omitted actions deny by default. `pylon lint` flags wide-open development policies such as `allow*: "true"`; tighten them before shipping.
+3. **Author a function** in `functions/<name>.ts`: `query` (read-only), `mutation` (transactional read+write), or `action` (external I/O, no direct `ctx.db`). Import `{ query, mutation, action, v }` from `@pylonsync/functions`. `auth` defaults to `"user"` (secure-by-default); set `"public"` explicitly for unauthenticated access. Use `ctx.db.*`, `ctx.auth.userId`, `ctx.error(code, msg)`.
+4. **Read it on the client:** `db.useQuery("Thing")` (live, re-renders on any write) or `db.useQueryOne("Thing", id)`. Call functions with `db.fn(name, args)` / `callFn`. On SSR pages, read via `use(serverData.list("Thing"))` inside `<Suspense>`.
+
+## Key gotchas
+
+- **Policies deny by default; server functions BYPASS them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full DB access; enforce trust with `ctx.auth` checks inside the handler, not policies.
+- **Type page props from the SDK, don't hand-roll them.** `import type { PageProps, Metadata } from "@pylonsync/react"`. Every page/layout gets `{ pathname, host, params, searchParams, auth, response, serverData }`; `PageProps<{ slug: string }>` types a `[slug]` route's params. `host` is the request host when the server trusts it (its own URL, `PYLON_TRUSTED_HOSTS`, a ready `ctx.domains` customer domain), else `""`; it is part of the SSR cache key, so a page may render per host. Request headers/cookies are intentionally NOT on `PageProps`; they're server-only and stripped from hydration, so reading them in the render would mismatch.
+- **Anonymous output caching is opt-in and conditional.** `export const revalidate = 60` makes a page CDN-cacheable (`public, s-maxage=60`) only when the render is auth-independent: it must not read `props.auth`, set a cookie, or run with strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. When any condition fails, the page is `no-cache`. Eligible renders also use the origin disk cache at `.pylon/.cache/ssr`: a cookie-less GET without a query string is served from disk for the TTL and rerendered when stale. The cache is namespaced per deploy, cleared by each build, disabled in `pylon dev`, and invalidated by the `revalidate` TTL or the next deploy.
+- **No-JS forms use `route.ts` and `<Form>`.** Add `app/.../route.ts` exporting `export const POST: RouteHandler = async ({ form, db, response, auth }) => { await db.insert("X", {...}); response.redirect("/x?ok=1"); }` (303 POST-redirect-GET by default). Render `<Form action="/x">` from `@pylonsync/react` with plain `<input name=...>`. It uses native POST → handler → redirect without JavaScript and no-reload enhancement with JavaScript. The handler's `db` is read+write under the mutation trust model, so gate it on `auth`. CSRF protection is automatic through the Origin gate and SameSite=Lax. Multipart uploads are not supported yet; use URL-encoded forms and `/api/files`.
+- **`loading.tsx` streams a skeleton while the page's data resolves.** Drop `app/.../loading.tsx` (default export, page props) and the nearest one becomes a route-level Suspense fallback: Pylon flushes the shell + skeleton immediately, then reveals the real page when its top-level `use(serverData…)` resolves (no blank page). It only shows when the PAGE suspends; a page that wraps its own `<Suspense>` around a child (like `/dashboard` in this template) handles that itself. The skeleton is SERVER-ONLY: don't read `serverData` in it. A page with no `loading.tsx` is buffered (unchanged).
+- **`export const streaming = true` streams a page's inner `<Suspense>` boundaries.** Without it or a `loading.tsx`, the page is buffered until all suspended children resolve. With it, the shell and fallbacks flush immediately, then each boundary streams its content. Streaming commits the HTTP head before suspended subtrees finish, so the page is never CDN- or disk-cacheable; do not combine it with `export const revalidate`. Calls to `response.setStatus`, `setCookie`, `redirect`, or `notFound` only take effect during the synchronous shell render. A call from a suspended subtree is dropped and logged. An error from a deep `<Suspense>` child resolves through the nearest `error.tsx` at HTTP 200 rather than 5xx. Type the config with `import type { RouteSegmentConfig } from "@pylonsync/react"`.
+- **`error.tsx` / `not-found.tsx` boundaries are HYDRATED (interactive).** `app/.../error.tsx` catches a throw below it (HTTP 500) and receives `{ error: { message, digest }, reset }` (`import type { ErrorBoundaryProps }`); `reset()` re-attempts the route; the stack NEVER reaches the client (dev overlay + logs only). `app/.../not-found.tsx` renders at 404 (also for `response.notFound()`) and gets the page props (`NotFoundProps`), no `reset`. Both run useState/onClick/hooks.
+- **Client navigation hooks live in @pylonsync/react.** `useRouter()` → `{ push, replace, back, forward, refresh, prefetch }`; `useSearchParams()` → reactive `URLSearchParams`; `usePathname()` → reactive pathname. The hooks are CLIENT-reactive; during SSR they return defaults (empty params / "/"); for server-side URL values read the `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
+- **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"`; `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
+- **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
+- **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
+- **`ctx.llm`, `ctx.rooms`, and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
+- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. Streaming does NOT extend the call deadline (`PYLON_FN_CALL_TIMEOUT`, 30s default) — set `timeout: <secs>` on the def for a long run.
+- **`ctx.stream.write(text)` streams to the caller — and every fn stream is RESUMABLE**: the server buffers frames under a stream id (`streamFn`'s `onStreamId`), so a dropped connection or closed tab catches up via `resumeStream(id)`, including the final result after the handler finished. `ctx.rooms.broadcast(room, topic, data)` fans out to every CURRENTLY-CONNECTED subscriber (second device, second tab) but does not replay missed messages — use the stream id for anything that must survive a gap. Broadcast resolves `{ delivered: false }` when the room has no members — a no-op, not an error. Clients receive with `useRoomMessages(room, cb)` from `@pylonsync/react`; `useRoom` is the send side.
+- **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
+- **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; an upload is readable by its uploader only, so pass `visibility: "public"` to `uploadFile` or `<FileUpload>` for files every visitor sees; there is no `ctx.files`. One-shot work uses `ctx.scheduler.runAfter`, `runAt`, or `cancel`; there is no `defineWorkflow` or `defineJob`. Recurring work uses `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })`, imported from `@pylonsync/sdk`. Make the target function `internal: true`. It runs with anonymous auth, but its own `ctx.db.*` calls are server-side and bypass policies. Use `ctx.auth.elevate({ admin: true, reason: "..." })`, with a mandatory reason, only when chaining another internal function through `ctx.scheduler`.
+
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/`; replace them with your own.
+
+**Tier 1: pure logic (start here).** Keep access and plan gating, pricing, credit math, validation, and formatting in pure functions under `lib/`, and test them exhaustively. These tests need no server and run instantly. Keep `query`, `mutation`, and `action` handlers as thin wrappers so their decision logic remains testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2: React components.** `@testing-library/react` and happy-dom are already wired through `tests/setup.ts`. Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, mock the boundary, then dynamically import the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3: functions over HTTP.** Use this tier when pure logic tests cannot cover the behavior. A handler's policies, `ctx.db` calls, and auth run in the app. Start `pylon dev` in another terminal and call the API. `resetDb()` from `@pylonsync/functions` clears the in-memory database between cases; it does nothing when the server is down and refuses to run in production.
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe; it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
+## Use the CLI
+
+| Need | Command |
+|---|---|
+| Run the app (SSR + API, hot reload, one port `:4321`) | `pylon dev` (or `npm run dev`) |
+| Regenerate manifest + typed client | `pylon codegen` (Swift client: `pylon codegen client --target swift`) |
+| Validate / diff / push schema | `pylon schema check` \| `diff` \| `push` |
+| Migrations | `pylon migrate create <name>` \| `plan` \| `apply` |
+| Lint policies (PYL001–PYL004) | `pylon lint --strict` |
+| Tests | `pylon test` |
+| Adversarial security probe | `pylon test:security` |
+| Inspect cloud request logs (agent-safe) | `pylon logs --json --limit 50` |
+| Inspect data / entities | `pylon data entities` \| `pylon data list <Entity>` |
+| Call a function | `pylon fn <name> key=value` |
+| Health snapshot | `pylon status` |
+| Build for prod (writes `dist/`) | `pylon build` |
+| Run the production build | `pylon start dist` |
+| Deploy (Pylon Cloud by default) | `pylon deploy` |
+| Look up an error code | `pylon explain <CODE>` |
+
+`--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
+
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/imessage/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md**, the cross-editor
+standard read by Claude Code, Cursor, Codex, and other agents. The import below
+makes it available to Claude Code:
+
+@AGENTS.md