@pylonsync/create-pylon 0.3.274 → 0.3.275

package/templates/shop/functions/restockProduct.ts

@@ -0,0 +1,23 @@
+import { mutation, v } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+
+// restockProduct — owner-only. Adds units to a product's stock. The bump syncs
+// to every open grid, so the shelf updates live (a sold-out item reappears).
+export default mutation<{ slug: string; add: number }, { ok: boolean; stock: number }>({
+  auth: "user",
+  args: { slug: v.string(), add: v.int() },
+  async handler(ctx, args) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can manage stock.");
+    }
+    const add = Math.max(0, Math.trunc(args.add));
+    const product = (await ctx.db.unsafe.lookup("Product", "slug", args.slug)) as
+      | { id: string; stock: number }
+      | null;
+    if (!product) throw ctx.error("NOT_FOUND", "Product not found.");
+    const stock = product.stock + add;
+    await ctx.db.unsafe.update("Product", product.id, { stock });
+    return { ok: true, stock };
+  },
+});

package/templates/shop/functions/seedProducts.ts

@@ -0,0 +1,30 @@
+import { mutation } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+
+// seedProducts — idempotently load the catalog (incl. starting stock) from
+// config into the Product table on first visit. The product grid calls this on
+// mount; it's a no-op once products exist, so it's safe to call every load. A
+// lock keeps two concurrent first-visits from double-seeding.
+//
+// Public so an anonymous first visitor seeds the shelf — it only ever writes
+// the config catalog, never reads or returns anything sensitive.
+export default mutation<Record<string, never>, { seeded: boolean; count: number }>({
+  auth: "public",
+  async handler(ctx) {
+    await ctx.db.advisoryLock("shop_seed_products");
+    const existing = await ctx.db.unsafe.list("Product");
+    if (existing.length > 0) return { seeded: false, count: existing.length };
+
+    for (const p of siteConfig.products.items) {
+      await ctx.db.unsafe.insert("Product", {
+        slug: p.slug,
+        name: p.name,
+        priceCents: p.priceCents,
+        description: p.description ?? null,
+        image: p.image,
+        stock: p.stock,
+      });
+    }
+    return { seeded: true, count: siteConfig.products.items.length };
+  },
+});

package/templates/shop/functions/stripeWebhook.ts

@@ -0,0 +1,72 @@
+import { action } from "@pylonsync/functions";
+import { verifyStripeSignature } from "@pylonsync/stripe";
+
+// stripeWebhook — Stripe's callback that settles a checkout. Mounted at
+// POST /api/webhooks/stripeWebhook (the webhook route gives an action the EXACT
+// raw request bytes Stripe signed; `/api/fn/...` would re-encode them and break
+// the signature). Point your Stripe dashboard webhook there and put the signing
+// secret in STRIPE_WEBHOOK_SECRET.
+//
+// SECURITY: the request is unauthenticated, so the HMAC signature IS the auth.
+// We verify it with the vetted constant-time `verifyStripeSignature` BEFORE
+// trusting a single byte — never parse-then-trust. A bad/missing/stale/replayed
+// signature is rejected with 400.
+//
+// On success it settles the cart's order lines by `client_reference_id` (the
+// orderGroupId set at checkout): paid → mark "paid"; expired/failed → release
+// the held stock. Both settle mutations are idempotent, so Stripe's retries are
+// safe.
+export default action({
+  auth: "public",
+  args: {},
+  async handler(ctx) {
+    if (!ctx.request) {
+      throw ctx.error("BAD_INVOCATION", "stripeWebhook must be called as a webhook.");
+    }
+    const secret = ctx.env.STRIPE_WEBHOOK_SECRET?.trim();
+    if (!secret) {
+      throw ctx.error("NOT_CONFIGURED", "STRIPE_WEBHOOK_SECRET is not set.");
+    }
+
+    const sig = ctx.request.headers["stripe-signature"];
+    const verdict = await verifyStripeSignature(secret, ctx.request.rawBody, sig);
+    if (verdict !== true) {
+      throw ctx.error("INVALID_SIGNATURE", `stripe signature: ${verdict}`);
+    }
+
+    let event: {
+      type?: string;
+      data?: { object?: { client_reference_id?: string; payment_status?: string; metadata?: { orderGroupId?: string } } };
+    };
+    try {
+      event = JSON.parse(ctx.request.rawBody);
+    } catch {
+      throw ctx.error("BAD_BODY", "Webhook body is not valid JSON.");
+    }
+
+    const session = event.data?.object ?? {};
+    const orderGroupId = session.client_reference_id || session.metadata?.orderGroupId;
+
+    switch (event.type) {
+      case "checkout.session.completed":
+        // Card payments are paid on completion; delayed methods arrive as
+        // "unpaid" here and confirm later via async_payment_succeeded.
+        if (orderGroupId && session.payment_status === "paid") {
+          await ctx.runMutation("markGroupPaid", { orderGroupId });
+        }
+        return { ok: true, type: event.type };
+
+      case "checkout.session.async_payment_succeeded":
+        if (orderGroupId) await ctx.runMutation("markGroupPaid", { orderGroupId });
+        return { ok: true, type: event.type };
+
+      case "checkout.session.expired":
+      case "checkout.session.async_payment_failed":
+        if (orderGroupId) await ctx.runMutation("releaseGroup", { orderGroupId });
+        return { ok: true, type: event.type };
+
+      default:
+        return { ignored: event.type ?? "unknown" };
+    }
+  },
+});

package/templates/shop/gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.pylon/
+pylon.manifest.json
+pylon.client.ts
+web/dist/
+*.db
+*.db-*
+.env
+.env.local
+.DS_Store

package/templates/shop/lib/owner.ts

@@ -0,0 +1,26 @@
+// Who owns this waitlist? A waitlist is single-tenant — one business, one
+// owner — so ownership is just "the email the owner signs in with", configured
+// once via the PYLON_OWNER_EMAIL env var. The owner-only `waitlistStats`
+// function reads that env (via `ctx.env`) and compares it here.
+//
+// Fail closed: if PYLON_OWNER_EMAIL is unset, NOBODY is the owner and the
+// dashboard stays locked. That's deliberate — an unset owner on a public site
+// must not mean "everyone can read the signups". Set it in .env (see
+// .env.example) before signing in.
+
+export function normalizeOwner(raw: string | null | undefined): string | null {
+  const v = raw?.trim().toLowerCase();
+  return v && v.length > 0 ? v : null;
+}
+
+// Pure comparator — the caller supplies the configured owner value (from
+// `ctx.env.PYLON_OWNER_EMAIL`), so the rule lives in one place and stays
+// testable without reaching for the environment here.
+export function emailMatchesOwner(
+  email: string | null | undefined,
+  ownerRaw: string | null | undefined,
+): boolean {
+  const owner = normalizeOwner(ownerRaw);
+  if (!owner) return false;
+  return (email ?? "").trim().toLowerCase() === owner;
+}

package/templates/shop/lib/shop.ts

@@ -0,0 +1,45 @@
+// Shared shop types. The Order row is what the owner dashboard sees (with PII);
+// the client imports only the type, never server code.
+
+export interface OrderRow {
+  id: string;
+  orderGroupId: string;
+  productSlug: string;
+  productName: string;
+  qty: number;
+  unitPriceCents: number;
+  customerName: string;
+  customerEmail: string;
+  // "pending" | "paid" | "reserved" | "fulfilled" | "cancelled"
+  status: string;
+  createdAt: string;
+}
+
+// ordersForOwner returns a discriminated result rather than throwing on a
+// non-owner (a query has no `ctx.error`; a bare throw becomes a stripped
+// HANDLER_ERROR). A non-owner gets `{ authorized: false }` and NO data.
+export type OwnerOrdersResult =
+  | { authorized: true; orders: OrderRow[] }
+  | { authorized: false };
+
+// One cart line on its way to checkout. The client sends slug + qty; the
+// server re-prices from the catalog so the price is never client-trusted.
+export interface CheckoutItem {
+  slug: string;
+  qty: number;
+}
+
+// What `checkout` returns to the client.
+//   • mode "stripe"   → redirect the browser to `checkoutUrl` (hosted Stripe).
+//   • mode "reserved" → no payment processor configured; the order is held and
+//                       the owner follows up. Show the confirmation message.
+// `soldOut` lists any cart lines that sold out between page-load and checkout
+// (they were dropped from the order); the rest still went through.
+export type CheckoutResult =
+  | { ok: true; mode: "stripe"; checkoutUrl: string; soldOut: string[] }
+  | { ok: true; mode: "reserved"; orderGroupId: string; soldOut: string[] }
+  | { ok: false; reason: "empty" | "sold_out" | "invalid"; soldOut: string[] };
+
+export function formatPrice(cents: number): string {
+  return `$${(cents / 100).toFixed(cents % 100 === 0 ? 0 : 2)}`;
+}

package/templates/shop/lib/site.config.ts

@@ -0,0 +1,198 @@
+// THE single source of truth for everything business-specific. Rebrand the
+// whole store by editing this ONE file — the landing page and layout read from
+// here. The product list (incl. starting stock) seeds the Product table on
+// first visit; after that, stock lives in the database and updates live.
+//
+// Colors live here (applied as CSS variables on <html> in app/layout.tsx).
+// Fictional demo copy — replace the values, keep the shape.
+
+/* ----------------------------- types ----------------------------- */
+
+export type Social = { label: string; href: string; path: string };
+
+export type BaseConfig = {
+  brand: {
+    name: string;
+    letter: string;
+    domain: string;
+    email: string;
+    footerBlurb: string;
+    copyrightName: string;
+    socials: Social[];
+  };
+  colors: { brand: string; brandSoft: string; paper: string };
+  seo: { title: string; description: string };
+};
+
+export type ProductItem = {
+  slug: string;
+  name: string;
+  priceCents: number;
+  description?: string;
+  image: string; // a product photo URL/path → shown as the photo; or an emoji stand-in (tagged "sample image")
+  stock: number; // STARTING stock — seeded once, then live in the DB
+};
+
+export type ValueProp = { title: string; body: string; icon?: string };
+export type Review = { quote: string; name: string; rating?: number };
+export type Policy = { title: string; body: string };
+
+export type ShopConfig = BaseConfig & {
+  hero: { tagline: string; headline: string; subcopy: string; ctaLabel: string };
+  products: { eyebrow: string; headline: string; items: ProductItem[] };
+  checkout: { confirmationMessage: string };
+  valueProps: { eyebrow: string; headline: string; items: ValueProp[] };
+  reviews?: { eyebrow: string; headline: string; items: Review[] };
+  policies: { eyebrow: string; headline: string; items: Policy[] };
+};
+
+/* ----------------------------- config ---------------------------- */
+
+export const siteConfig: ShopConfig = {
+  brand: {
+    name: "Ember Goods",
+    letter: "E",
+    domain: "embergoods.com",
+    email: "hello@embergoods.example",
+    footerBlurb:
+      "Hand-poured candles and small-batch home goods, made in Dallas. Slow, simple, and built to last. Free shipping over $50.",
+    copyrightName: "Ember Goods",
+    socials: [
+      {
+        label: "Instagram",
+        href: "https://instagram.com",
+        path: "M12 2.2c3.2 0 3.6 0 4.85.07 1.17.05 1.8.25 2.23.41.56.22.96.48 1.38.9.42.42.68.82.9 1.38.16.42.36 1.06.41 2.23.06 1.27.07 1.65.07 4.85s0 3.58-.07 4.85c-.05 1.17-.25 1.8-.41 2.23-.22.56-.48.96-.9 1.38-.42.42-.82.68-1.38.9-.42.16-1.06.36-2.23.41-1.27.06-1.65.07-4.85.07s-3.58 0-4.85-.07c-1.17-.05-1.8-.25-2.23-.41a3.7 3.7 0 0 1-1.38-.9 3.7 3.7 0 0 1-.9-1.38c-.16-.42-.36-1.06-.41-2.23C2.2 15.58 2.2 15.2 2.2 12s0-3.58.07-4.85c.05-1.17.25-1.8.41-2.23.22-.56.48-.96.9-1.38.42-.42.82-.68 1.38-.9.42-.16 1.06-.36 2.23-.41C8.42 2.2 8.8 2.2 12 2.2zm0 1.8c-3.15 0-3.5 0-4.74.07-.9.04-1.38.19-1.7.32-.43.16-.74.36-1.06.68-.32.32-.52.63-.68 1.06-.13.32-.28.8-.32 1.7C3.8 8.5 3.8 8.85 3.8 12s0 3.5.07 4.74c.04.9.19 1.38.32 1.7.16.43.36.74.68 1.06.32.32.63.52 1.06.68.32.13.8.28 1.7.32 1.24.07 1.59.07 4.74.07s3.5 0 4.74-.07c.9-.04 1.38-.19 1.7-.32.43-.16.74-.36 1.06-.68.32-.32.52-.63.68-1.06.13-.32.28-.8.32-1.7.07-1.24.07-1.59.07-4.74s0-3.5-.07-4.74c-.04-.9-.19-1.38-.32-1.7a2.85 2.85 0 0 0-.68-1.06 2.85 2.85 0 0 0-1.06-.68c-.32-.13-.8-.28-1.7-.32C15.5 4 15.15 4 12 4zm0 3.06A4.94 4.94 0 1 0 12 16.94 4.94 4.94 0 0 0 12 7.06zm0 8.15A3.21 3.21 0 1 1 12 8.8a3.21 3.21 0 0 1 0 6.4zm6.3-8.35a1.15 1.15 0 1 1-2.3 0 1.15 1.15 0 0 1 2.3 0z",
+      },
+    ],
+  },
+
+  colors: { brand: "#9a3412", brandSoft: "#ffedd5", paper: "#faf8f5" },
+
+  seo: {
+    title: "Ember Goods — hand-poured candles, made in Dallas.",
+    description:
+      "Small-batch candles and home goods, hand-poured in Dallas. Live stock — what you see is what's in the studio. Free shipping over $50.",
+  },
+
+  hero: {
+    tagline: "Small batch · Made in Dallas",
+    headline: "Hand-poured candles, made to last.",
+    subcopy:
+      "We pour everything by hand in small batches, so quantities are real and limited. The stock you see below is exactly what's on the studio shelf right now.",
+    ctaLabel: "Shop the shelf",
+  },
+
+  products: {
+    eyebrow: "The shelf",
+    headline: "What's in the studio right now.",
+    items: [
+      {
+        slug: "cedar-smoke",
+        name: "Cedar & Smoke",
+        priceCents: 3200,
+        description: "Cedarwood, smoked vanilla, a little leather. 60-hour burn.",
+        image: "🕯️",
+        stock: 8,
+      },
+      {
+        slug: "linen",
+        name: "Fresh Linen",
+        priceCents: 3200,
+        description: "Clean cotton and white musk. The everyday one.",
+        image: "🤍",
+        stock: 3,
+      },
+      {
+        slug: "brass-holder",
+        name: "Brass matchstick holder",
+        priceCents: 2400,
+        description: "Solid brass, striker on the base. Ages beautifully.",
+        image: "🟫",
+        stock: 12,
+      },
+      {
+        slug: "ceramic-vessel",
+        name: "Ceramic vessel candle",
+        priceCents: 4800,
+        description: "Hand-thrown stoneware you'll keep long after the wax.",
+        image: "🏺",
+        stock: 5,
+      },
+      {
+        slug: "wick-trimmer",
+        name: "Wick trimmer",
+        priceCents: 1800,
+        description: "The one tool that makes a candle last. Matte black.",
+        image: "✂️",
+        stock: 0,
+      },
+      {
+        slug: "gift-set",
+        name: "The trio gift set",
+        priceCents: 8400,
+        description: "Three minis, boxed and ready to give.",
+        image: "🎁",
+        stock: 6,
+      },
+    ],
+  },
+
+  checkout: {
+    confirmationMessage:
+      "Order placed! We'll email you a payment link and ship within two business days.",
+  },
+
+  valueProps: {
+    eyebrow: "Why Ember",
+    headline: "Made slow, on purpose.",
+    items: [
+      {
+        icon: "◍",
+        title: "Hand-poured",
+        body: "Every candle is poured, wicked, and labelled by hand in our Dallas studio.",
+      },
+      {
+        icon: "◇",
+        title: "Real small batch",
+        body: "We make what we can do well. When the shelf says 3 left, there are 3 left.",
+      },
+      {
+        icon: "✦",
+        title: "Free shipping over $50",
+        body: "Carbon-neutral shipping, plastic-free packaging, and easy returns.",
+      },
+    ],
+  },
+
+  reviews: {
+    eyebrow: "Reviews",
+    headline: "What people say.",
+    items: [
+      {
+        quote: "Cedar & Smoke is the best candle I've ever bought, full stop. The brass holder is gorgeous too.",
+        name: "Maya C.",
+        rating: 5,
+      },
+      {
+        quote: "Ordered the gift set for my mom. Beautiful packaging and it arrived in two days. Will reorder.",
+        name: "Daniel R.",
+        rating: 5,
+      },
+      {
+        quote: "You can tell these are made by hand. The ceramic vessel is on my shelf forever now.",
+        name: "Hannah K.",
+        rating: 5,
+      },
+    ],
+  },
+
+  policies: {
+    eyebrow: "Good to know",
+    headline: "Shipping & returns.",
+    items: [
+      { title: "Shipping", body: "Ships in 2 business days from Dallas. Free over $50, $6 flat otherwise." },
+      { title: "Returns", body: "Unused and unburned? Return within 30 days for a full refund." },
+      { title: "Wholesale", body: "Run a shop? Email us for the line sheet and wholesale pricing." },
+    ],
+  },
+};

package/templates/shop/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+// `cn` — the shadcn class merger. clsx resolves conditional/array class
+// inputs; tailwind-merge then dedupes conflicting Tailwind utilities so
+// the last one wins (e.g. `cn("px-2", "px-4")` → "px-4"). Every shadcn
+// component routes its className through this.
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/shop/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__APP_NAME_KEBAB__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev",
+    "deploy": "pylon deploy",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@pylonsync/react": "^__PYLON_VERSION__",
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__",
+    "@pylonsync/client": "^__PYLON_VERSION__",
+    "@pylonsync/stripe": "^__PYLON_VERSION__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "@tailwindcss/cli": "^4.3.0",
+    "tw-animate-css": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.0",
+    "lucide-react": "^0.460.0",
+    "@radix-ui/react-slot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/shop/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM"],
+    "types": ["react", "react-dom", "node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["app.ts", "app/**/*", "components/**/*", "lib/**/*", "functions/**/*"]
+}

package/templates/waitlist/.env.example

@@ -0,0 +1,12 @@
+# Copy to `.env` and fill in. `pylon dev` loads `.env` automatically.
+
+# ── Owner (required to use the dashboard) ────────────────────────────────────
+# A waitlist is single-tenant: one business, one owner. The /dashboard is
+# unlocked only for the account whose email matches this value, and the
+# owner-only data function refuses to return any signups otherwise. Set this to
+# the email you'll sign in with, then create that account at /login.
+PYLON_OWNER_EMAIL=you@yourbusiness.com
+
+# ── Site URL (optional) ──────────────────────────────────────────────────────
+# Used by robots.txt + sitemap.xml. Point it at your real domain in production.
+# SITE_URL=https://yourbusiness.com

package/templates/waitlist/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md — working in a Pylon project
+
+Operating rules for a coding agent in this Pylon app. Pylon is a Rails-like framework for realtime apps: you declare entities, policies, and server functions in TypeScript, and a single Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR — one process, one port. The full API reference is at **/llms-full.txt** (served at `/llms-full.txt`; in the repo at `apps/web/public/llms-full.txt`). Read it before guessing an API name.
+
+## 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))`.
+- `app/` — file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the 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).
+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.** Wide-open dev policies (`allow*: "true"`) are flagged by `pylon lint` — tighten 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 `{ url, params, searchParams, auth, response, serverData }`; `PageProps<{ slug: string }>` types a `[slug]` route's params. 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 + earned.** `export const revalidate = 60` (seconds) on a page makes it CDN-cacheable (`public, s-maxage=60`) — but ONLY if the render is auth-INDEPENDENT: it must NOT read `props.auth` (reading it at all opts out, even for anonymous), set no cookie, and the app must not run strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. Fail-closed: without the opt-in (or if any condition fails) the page is `no-cache`. A page that reads `auth` or sets a cookie is never shared. The SAME earned render is also kept in an **origin disk cache** (`.pylon/.cache/ssr`): a cookie-less GET with no query string is served straight off disk for the TTL — skipping the render entirely — then re-rendered live when stale. The disk cache is namespaced per deploy (wiped on each new build) and OFF in `pylon dev` (so an edit is never masked by a stale entry); invalidation is by the `revalidate` TTL or the next deploy.
+- **No-JS forms use `route.ts` + `<Form>`.** Drop `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=...>` — works with JS off (native POST→handler→redirect) and is enhanced to no-reload when JS is on. The handler's `db` is read+write (mutation trust model — gate on `auth`); CSRF is automatic (Origin gate + SameSite=Lax). Multipart/file uploads aren't supported yet — use urlencoded forms + `/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 OWN inner `<Suspense>` boundaries.** Without it (and without a `loading.tsx`), a page is BUFFERED — the whole document, including suspended children, resolves before the first byte. Opt in and the shell + each inner `<Suspense>` fallback flush immediately, then each boundary's real content streams in as its data resolves (multi-boundary progressive streaming). It's opt-in because it changes the response timing contract: a streaming render commits its HTTP head BEFORE suspended subtrees finish, so (a) it's never CDN/disk cacheable — don't combine with `export const revalidate`; (b) `response.setStatus/setCookie/redirect/notFound` only take effect from the SYNCHRONOUS shell render — a call from inside a suspended subtree is dropped (the runtime logs a loud warning naming what was lost); (c) a `throw` from a deep `<Suspense>` child resolves via its nearest `error.tsx` at HTTP 200, not a 5xx. Hydration is clean for any number of boundaries (the data blob ships before hydration runs). 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 `url` / `searchParams` page props.
+- **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.
+- **`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` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db` — use `ctx.runQuery` / `ctx.runMutation`.
+- **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
+- **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
+
+## Use the CLI — don't guess
+
+| 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 | `pylon build` |
+| 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: **/llms-full.txt**.

package/templates/waitlist/README.md

@@ -0,0 +1,81 @@
+# __APP_NAME__
+
+A pre-launch / coming-soon landing page built with [Pylon](https://pylonsync.com) —
+a server-rendered marketing page with a **live signup counter** and a private
+owner dashboard, all served from one binary on one port. No Next.js, no separate
+API server.
+
+The whole point is that it's a *real live app*, not a static page: the signup
+counter ticks up in realtime for everyone with the page open.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Then **open a second tab**, submit an email in one,
+and watch the counter increment in the other — with no refresh. That's the live
+backend doing its thing.
+
+## How the realtime works
+
+- `functions/joinWaitlist.ts` — a public **mutation** that validates, lowercases,
+  and dedupes the email, then inserts one `Signup` row. The insert fires a
+  change event.
+- `functions/waitlistCount.ts` — a public **query** the landing page subscribes
+  to with `db.useReactiveQuery`. The server records that it read the `Signup`
+  table, so every new signup re-runs it and pushes the fresh count to every open
+  tab. No polling.
+- The counter island (`app/waitlist-hero.tsx`) is wrapped in `<EnsureGuest>`,
+  which mints an anonymous session so the live WebSocket can connect.
+
+## Privacy — read this
+
+The `Signup` entity holds visitor emails (PII), so its policy in `app.ts`
+**denies every client read and write**. Emails can never be pulled from the
+browser. The public page only ever receives an aggregate *count* (a bare
+integer); the full list — including emails — is returned only by
+`waitlistStats`, which is gated to the owner server-side. A marketing site must
+never leak its own customers' emails, and this is how that's guaranteed.
+
+## The owner dashboard
+
+`/dashboard` shows the total, a signups-over-time chart, a searchable list, and
+a CSV export — all updating live as people join.
+
+It's single-tenant: set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to
+the email you'll sign in with, then create that account at `/login`. Only that
+account can see signups; anyone else gets a locked screen.
+
+## Rebrand it
+
+Everything business-specific lives in **`lib/site.config.ts`** — brand, colors,
+hero copy, value props, social proof, FAQ. Edit that one file (or have a
+generator produce it) and the whole page re-themes; you never touch the JSX or
+CSS.
+
+## Layout
+
+```
+app.ts                       data model + manifest (Signup, User, policies, auth)
+lib/site.config.ts           ALL business copy + brand + colors (edit this)
+lib/owner.ts                 owner-email gate (PYLON_OWNER_EMAIL)
+lib/stats.ts                 shared dashboard-stats types
+functions/joinWaitlist.ts    public mutation: validate + dedupe + insert
+functions/waitlistCount.ts   public reactive query: the live counter
+functions/waitlistStats.ts   owner-only reactive query: total + chart + list
+app/page.tsx                 the landing page (server-rendered)
+app/waitlist-hero.tsx        client island: signup form + live counter
+app/login/page.tsx           owner sign-in
+app/dashboard/               owner dashboard (auth-gated, live)
+app/globals.css              Tailwind entrypoint (compiled by Pylon)
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com