@pylonsync/create-pylon 0.3.274 → 0.3.276

package/templates/ai-studio/functions/pollGeneration.ts

@@ -0,0 +1,134 @@
+import { action, v } from "@pylonsync/functions";
+import { placeholderImage } from "../lib/studio";
+
+// pollGeneration — the background job (enqueued by `generate` via
+// ctx.scheduler.runAfter). It runs OFF the request path, so slow models can take
+// as long as they need without blocking or timing out the user's call. It:
+//   1. starts the Replicate prediction (first run), then
+//   2. re-checks it and RESCHEDULES ITSELF every few seconds until it settles,
+//   3. writes the result/error to the Generation — which syncs live to the
+//      owner's gallery (pending → processing → done/failed) via db.useQuery.
+//
+// With no REPLICATE_API_TOKEN it returns a clearly-labeled placeholder instead,
+// so the whole flow (and this job) work with zero config.
+//
+// Not internal, but harmless if called directly: it only advances a generation's
+// own prediction; results sync only to the owner (Generation is owner-read).
+
+const REPLICATE = "https://api.replicate.com/v1";
+const POLL_MS = 3000;
+const MAX_ATTEMPTS = 200; // ~10 min ceiling, then give up
+
+export default action<{ id: string; attempts?: number }, { ok: boolean }>({
+  auth: "public",
+  args: { id: v.id("Generation"), attempts: v.optional(v.int()) },
+  async handler(ctx, args) {
+    const attempts = args.attempts ?? 0;
+    const gen = await ctx.runQuery<{
+      id: string;
+      kind: string;
+      prompt: string;
+      status: string;
+      predictionId?: string | null;
+    } | null>("_getGeneration", { id: args.id });
+    if (!gen || gen.status === "done" || gen.status === "failed") return { ok: true };
+
+    const update = (patch: Record<string, unknown>) => ctx.runMutation("_updateGeneration", { id: args.id, ...patch });
+    const reschedule = () =>
+      ctx.scheduler.runAfter(POLL_MS, "pollGeneration", { id: args.id, attempts: attempts + 1 });
+
+    if (attempts > MAX_ATTEMPTS) {
+      await update({ status: "failed", error: "Generation timed out." });
+      return { ok: true };
+    }
+
+    const token = ctx.env.REPLICATE_API_TOKEN?.trim();
+
+    // ── Demo mode: no token → a labeled placeholder, no provider call. ──
+    if (!token) {
+      await update({
+        status: "done",
+        demo: true,
+        resultUrl: gen.kind === "image" ? placeholderImage(gen.prompt) : null,
+      });
+      return { ok: true };
+    }
+
+    try {
+      // First run: kick off the Replicate prediction.
+      if (!gen.predictionId) {
+        const model = modelFor(gen.kind, ctx.env);
+        const pred = await replicateCreate(model, gen.prompt, token);
+        if (pred.error) {
+          await update({ status: "failed", error: String(pred.error).slice(0, 300) });
+          return { ok: true };
+        }
+        const out = pickOutput(pred.output);
+        if (pred.status === "succeeded" && out) {
+          await update({ status: "done", resultUrl: out });
+        } else if (pred.status === "failed" || pred.status === "canceled") {
+          await update({ status: "failed", error: "Provider rejected the request." });
+        } else {
+          await update({ status: "processing", predictionId: pred.id });
+          await reschedule();
+        }
+        return { ok: true };
+      }
+
+      // Subsequent runs: check the in-flight prediction.
+      const pred = await replicateGet(gen.predictionId, token);
+      const out = pickOutput(pred.output);
+      if (pred.status === "succeeded" && out) {
+        await update({ status: "done", resultUrl: out });
+      } else if (pred.status === "failed" || pred.status === "canceled") {
+        await update({ status: "failed", error: String(pred.error || "Generation failed.").slice(0, 300) });
+      } else {
+        await reschedule();
+      }
+    } catch (err) {
+      // Transient network blip → try again; otherwise the attempts cap ends it.
+      await reschedule();
+    }
+    return { ok: true };
+  },
+});
+
+// Default models (run the latest version via the model-name endpoint). Override
+// any of them with env so swapping models needs no code change.
+function modelFor(kind: string, env: Record<string, string>): string {
+  if (kind === "image") return env.REPLICATE_IMAGE_MODEL?.trim() || "black-forest-labs/flux-schnell";
+  if (kind === "video") return env.REPLICATE_VIDEO_MODEL?.trim() || "minimax/video-01";
+  return env.REPLICATE_AUDIO_MODEL?.trim() || "meta/musicgen";
+}
+
+function pickOutput(output: unknown): string | null {
+  if (Array.isArray(output)) return typeof output[0] === "string" ? output[0] : null;
+  return typeof output === "string" ? output : null;
+}
+
+interface Prediction {
+  id: string;
+  status: string;
+  output?: unknown;
+  error?: unknown;
+}
+
+async function replicateCreate(model: string, prompt: string, token: string): Promise<Prediction> {
+  const res = await fetch(`${REPLICATE}/models/${model}/predictions`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ input: { prompt } }),
+  });
+  const j = (await res.json().catch(() => ({}))) as Prediction & { detail?: string };
+  if (!res.ok) return { id: "", status: "failed", error: j?.detail || `Replicate ${res.status}` };
+  return j;
+}
+
+async function replicateGet(predictionId: string, token: string): Promise<Prediction> {
+  const res = await fetch(`${REPLICATE}/predictions/${predictionId}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const j = (await res.json().catch(() => ({}))) as Prediction;
+  if (!res.ok) return { id: predictionId, status: "processing" }; // transient — keep polling
+  return j;
+}

package/templates/ai-studio/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/ai-studio/lib/site.config.ts

@@ -0,0 +1,80 @@
+// THE single source of truth for everything brand-specific on this AI media
+// studio. Rebrand by editing this ONE file — the layout + studio UI read from
+// here. The create-pylon scaffolder and Mast target this file.
+//
+// Colors live here (applied as CSS variables on <html> in app/layout.tsx).
+// Fictional demo copy — replace the values, keep the shape.
+
+import type { GenerationKind } from "./studio";
+
+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 StudioConfig = BaseConfig & {
+  studio: {
+    headline: string;
+    subcopy: string;
+    inputPlaceholder: string;
+    // The generation kinds shown as a selector. `wired` flags which actually
+    // call a provider (image + audio); video is a labeled extension point.
+    kinds: { id: GenerationKind; label: string; wired: boolean }[];
+    // Starter prompts; clicking one fills the box.
+    examples: string[];
+  };
+};
+
+export const siteConfig: StudioConfig = {
+  brand: {
+    name: "Prism",
+    letter: "P",
+    domain: "prism.studio",
+    email: "hello@prism.example",
+    footerBlurb: "A generative media studio built on Pylon — image, audio, and video from a prompt.",
+    copyrightName: "Prism",
+    socials: [
+      {
+        label: "X",
+        href: "https://x.com",
+        path: "M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z",
+      },
+    ],
+  },
+
+  colors: { brand: "#c026d3", brandSoft: "#fae8ff", paper: "#fdf9fe" },
+
+  seo: {
+    title: "Prism — a generative AI media studio.",
+    description:
+      "Generate images, audio, and video from a prompt. A live gallery that updates in realtime as each generation finishes, built on Pylon. Your API key stays server-side.",
+  },
+
+  studio: {
+    headline: "Make something.",
+    subcopy: "Describe it, pick a medium, and watch it land in your gallery — live, the moment it's done.",
+    inputPlaceholder: "A neon koi swimming through a rainy Tokyo alley at night…",
+    kinds: [
+      { id: "image", label: "Image", wired: true },
+      { id: "audio", label: "Audio", wired: true },
+      { id: "video", label: "Video", wired: true },
+    ],
+    examples: [
+      "A cozy reading nook in a treehouse, golden hour, watercolor",
+      "An upbeat lo-fi hip-hop loop with mellow piano",
+      "Isometric illustration of a tiny island data center",
+      "A timelapse of a city skyline as day turns to night",
+    ],
+  },
+};

package/templates/ai-studio/lib/studio.ts

@@ -0,0 +1,52 @@
+// Shared studio types + the no-API-key placeholder generator (pure, so the
+// generate action can call it server-side and the client imports only the type).
+
+export type GenerationKind = "image" | "audio" | "video";
+
+export interface GenerationRow {
+  id: string;
+  userId: string;
+  kind: string;
+  prompt: string;
+  status: string; // "pending" | "done" | "failed"
+  resultUrl?: string | null;
+  error?: string | null;
+  demo: boolean;
+  createdAt: string;
+}
+
+// Deterministic small hash → drives the placeholder gradient hue.
+function hashHue(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  return h % 360;
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+// A self-contained SVG "image" data URL — used when no REPLICATE_API_TOKEN is
+// set, so the gallery + realtime flow work with zero config. Clearly a
+// placeholder (it renders the prompt over a gradient), not a fake photo. Returns
+// a `data:` URL that drops straight into an <img>.
+export function placeholderImage(prompt: string): string {
+  const hue = hashHue(prompt);
+  const hue2 = (hue + 60) % 360;
+  const text = escapeXml(prompt.slice(0, 80));
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="640" viewBox="0 0 640 640">
+  <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+    <stop offset="0" stop-color="hsl(${hue} 70% 55%)"/>
+    <stop offset="1" stop-color="hsl(${hue2} 70% 45%)"/>
+  </linearGradient></defs>
+  <rect width="640" height="640" fill="url(#g)"/>
+  <text x="50%" y="44%" fill="rgba(255,255,255,0.95)" font-family="system-ui,sans-serif" font-size="26" font-weight="600" text-anchor="middle">${text}</text>
+  <text x="50%" y="54%" fill="rgba(255,255,255,0.7)" font-family="system-ui,sans-serif" font-size="15" text-anchor="middle">placeholder · set REPLICATE_API_TOKEN for real images</text>
+</svg>`;
+  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}

package/templates/ai-studio/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/ai-studio/package.json

@@ -0,0 +1,34 @@
+{
+  "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__",
+    "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/ai-studio/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/creator/.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/creator/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/creator/README.md

@@ -0,0 +1,67 @@
+# __APP_NAME__
+
+A personal-brand / creator site built with [Pylon](https://pylonsync.com) — a
+server-rendered landing page with a **live newsletter subscriber counter** and a
+private owner dashboard, all from one binary on one port. No Next.js, no
+separate API server.
+
+The realtime point: the subscriber count ticks up for everyone with the page
+open the instant someone subscribes.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Then **open a second tab**, subscribe in one, and
+watch the counter increment in the other — with no refresh.
+
+## How the realtime works
+
+- `functions/subscribe.ts` — a public **mutation** that validates, lowercases,
+  and dedupes the email, inserts one `Subscriber` row, and bumps a public,
+  PII-free `SubscriberCount` row.
+- `app/newsletter-signup.tsx` subscribes to `SubscriberCount` with
+  `db.useQuery`, so the live count syncs to every open tab. No polling.
+
+## Privacy — read this
+
+The `Subscriber` entity holds reader emails (PII), so its policy in `app.ts`
+**denies every client read and write**. The public page only ever reads the
+aggregate `SubscriberCount` (a bare integer); the full list — with emails —
+comes back only through `subscriberStats`, gated to the owner server-side.
+
+## The owner dashboard
+
+`/dashboard` shows total subscribers, a growth chart, a searchable list, and CSV
+export — updating live as people subscribe.
+
+Set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to the email you'll sign
+in with, then create that account at `/login`.
+
+## Rebrand it
+
+Everything lives in **`lib/site.config.ts`** — your name, colors, bio,
+offerings, testimonials, newsletter copy, links. Edit that one file (or have a
+generator produce it) and the whole page re-themes.
+
+## Layout
+
+```
+app.ts                       Subscriber + SubscriberCount + User + policies
+lib/site.config.ts           ALL copy + brand + offerings + newsletter (edit this)
+functions/subscribe.ts       public mutation: validate + dedupe + count
+functions/subscriberStats.ts owner-only query: subscribers + emails
+app/page.tsx                 the landing page (server-rendered)
+app/newsletter-signup.tsx    client island: signup form + live counter
+app/dashboard/               owner dashboard (auth-gated, live)
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com

package/templates/creator/app/auth-form.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import React, { useState } from "react";
+import {
+  passwordLogin,
+  passwordRegister,
+  persistSession,
+  ApiError,
+} from "@pylonsync/client";
+
+// The owner's email/password form — one form, two modes. It calls the built-in
+// auth API directly (`passwordLogin` / `passwordRegister` POST to
+// `/api/auth/password/*`), then `persistSession` writes the freshly-minted
+// token to local storage so the sync engine + `callFn` authenticate AS THE
+// OWNER on the next load. This step matters here specifically: the landing page
+// mints an anonymous guest session (for the live counter), and without
+// persisting the real session that stale guest token would shadow the owner's
+// — so the owner-only `subscriberStats` call would come back as a guest and get
+// rejected. We then do a full navigation to /dashboard so the SSR runtime
+// re-resolves auth from the HttpOnly cookie and renders server-side.
+//
+// A newsletter is single-tenant: there's no public subscriber funnel, just the owner
+// creating their one account. Whoever signs in only sees data if their email
+// matches PYLON_OWNER_EMAIL — enforced by the subscriberStats function.
+export function AuthForm() {
+  const [mode, setMode] = useState<"login" | "subscriber">("login");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    setPending(true);
+    try {
+      const session =
+        mode === "login"
+          ? await passwordLogin({ email, password })
+          : await passwordRegister({ email, password });
+      // Make this session authoritative, replacing any anonymous guest token.
+      persistSession(session);
+      window.location.assign("/dashboard");
+    } catch (err) {
+      setError(messageFor(err));
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="space-y-5">
+      <form onSubmit={onSubmit} className="space-y-4">
+        <label className="block">
+          <span className="mb-1.5 block text-[13px] font-medium text-zinc-700">Email</span>
+          <input
+            type="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            required
+            autoComplete="email"
+            placeholder="you@yourbusiness.com"
+            className="h-10 w-full rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 outline-none transition placeholder:text-zinc-400 focus:border-brand focus:ring-2 focus:ring-brand/20"
+          />
+        </label>
+        <label className="block">
+          <span className="mb-1.5 block text-[13px] font-medium text-zinc-700">Password</span>
+          <input
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            required
+            autoComplete={mode === "login" ? "current-password" : "new-password"}
+            placeholder={mode === "login" ? "Your password" : "At least 10 characters"}
+            className="h-10 w-full rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 outline-none transition placeholder:text-zinc-400 focus:border-brand focus:ring-2 focus:ring-brand/20"
+          />
+        </label>
+        {error ? (
+          <p className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-[13px] leading-snug text-red-700">
+            {error}
+          </p>
+        ) : null}
+        <button
+          type="submit"
+          disabled={pending}
+          className="inline-flex h-10 w-full items-center justify-center rounded-lg bg-zinc-900 text-sm font-medium text-white transition-colors hover:bg-zinc-700 disabled:opacity-60"
+        >
+          {pending ? "…" : mode === "login" ? "Sign in" : "Create account"}
+        </button>
+      </form>
+
+      <p className="text-center text-[13px] text-zinc-500">
+        {mode === "login" ? "First time here?" : "Already have an account?"}{" "}
+        <button
+          type="button"
+          onClick={() => {
+            setMode(mode === "login" ? "subscriber" : "login");
+            setError(null);
+          }}
+          className="font-medium text-zinc-900 underline underline-offset-2"
+        >
+          {mode === "login" ? "Create the owner account" : "Sign in"}
+        </button>
+      </p>
+    </div>
+  );
+}
+
+// Map the framework's auth error codes to friendly copy. `ApiError` carries a
+// stable `.code` so you branch on the code, not the message.
+function messageFor(err: unknown): string {
+  if (err instanceof ApiError) {
+    switch (err.code) {
+      case "INVALID_CREDENTIALS":
+        return "Wrong email or password.";
+      case "USER_EXISTS":
+        return "That email is already registered — sign in instead.";
+      case "WEAK_PASSWORD":
+        return "Pick a longer password — at least 10 characters.";
+      case "PWNED_PASSWORD":
+        return "That password has appeared in a known data breach. Choose a different one.";
+      case "RATE_LIMITED":
+        return "Too many attempts — try again in a minute.";
+      default:
+        return err.message;
+    }
+  }
+  if (err instanceof Error) return err.message;
+  return "Something went wrong. Try again.";
+}