@pylonsync/create-pylon 0.3.274 → 0.3.275

package/templates/ai-chat/app/login/page.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+import { Link, type Metadata, type PageProps } from "@pylonsync/react";
+import { AuthForm } from "../auth-form";
+import { siteConfig } from "@/lib/site.config";
+
+export const metadata: Metadata = {
+  title: `Sign in — ${siteConfig.brand.name}`,
+  robots: "noindex",
+};
+
+// `app/login/page.tsx` → `/login`. Sign-in is required to use the chat (chats
+// are tied to your account). Rendered bare. Already signed in? Skip back to the
+// chat — `response.redirect` in the synchronous shell render is a real 307
+// before any HTML is sent.
+export default function LoginPage({ auth, response }: PageProps) {
+  // Already signed in (a real account, not an anonymous guest)? Skip the form.
+  if (auth.user_id && !auth.user_id.startsWith("guest_")) response.redirect("/");
+  const { brand } = siteConfig;
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-white px-6 py-12">
+      <div className="w-full max-w-[400px] rounded-2xl border border-zinc-200/70 p-8">
+        <Link href="/" className="inline-flex">
+          <span className="flex size-9 items-center justify-center rounded-xl bg-zinc-900 text-base font-bold text-white">
+            {brand.letter}
+          </span>
+        </Link>
+        <h1 className="mt-5 text-[22px] font-semibold tracking-tight text-zinc-900">
+          Sign in to {brand.name}
+        </h1>
+        <p className="mt-1 text-[13px] text-zinc-500">
+          Create an account or sign in to start chatting.
+        </p>
+        <div className="mt-6">
+          <AuthForm />
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/ai-chat/app/not-found.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { Link, type NotFoundProps } from "@pylonsync/react";
+
+// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when a
+// page calls `response.notFound()`). Hydrated, so the link is a client nav.
+export default function NotFound(_props: NotFoundProps) {
+  return (
+    <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">
+      <h1 className="text-3xl font-semibold tracking-tight">404</h1>
+      <p className="mt-2 text-zinc-500">We couldn&apos;t find that page.</p>
+      <Link
+        href="/"
+        className="mt-6 inline-flex h-10 items-center rounded-full bg-zinc-900 px-5 text-sm font-medium text-white transition-colors hover:bg-zinc-700"
+      >
+        Back home
+      </Link>
+    </div>
+  );
+}

package/templates/ai-chat/app/page.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { type Metadata, type PageProps } from "@pylonsync/react";
+import { ChatApp } from "./chat-client";
+import { siteConfig } from "@/lib/site.config";
+
+export const metadata: Metadata = {
+  title: siteConfig.seo.title,
+  description: siteConfig.seo.description,
+  openGraph: { title: siteConfig.seo.title, description: siteConfig.seo.description, type: "website" },
+};
+
+// `app/page.tsx` → `/`. The whole app is the chat island — a sidebar of
+// conversations + the streaming thread. Sign-in is REQUIRED: chats are tied to
+// your account, so an unauthenticated visitor is redirected to /login (a real
+// 307 from the synchronous shell render, before any HTML is sent).
+export default function Home({ auth, response }: PageProps) {
+  // Real account required — reject anonymous + guest (guest_…) sessions.
+  if (!auth.user_id || auth.user_id.startsWith("guest_")) {
+    response.redirect("/login");
+    return null;
+  }
+  return <ChatApp />;
+}

package/templates/ai-chat/app.ts

@@ -0,0 +1,121 @@
+import {
+  entity,
+  field,
+  policy,
+  auth,
+  buildManifest,
+  discoverAppRoutes,
+} from "@pylonsync/sdk";
+
+// ---------------------------------------------------------------------------
+// ai-chat — a streaming AI chat app. Tokens stream from the built-in
+// `POST /api/ai/stream` endpoint (your PYLON_AI_API_KEY never leaves the
+// server); the conversation itself is sync-backed, so your chats follow you
+// across tabs and devices in realtime — open two tabs and a reply you send in
+// one shows up in the other as it's saved.
+//
+// Two data entities (+ User):
+//   • Conversation — a chat thread. Owner-scoped: you only ever see your own.
+//   • Message      — one turn (user or assistant). Owner-scoped too. Both use
+//                    `field.owner()` on userId, so the client can insert with a
+//                    plain optimistic `db.insert` and the id is stamped from the
+//                    session — unspoofable, no server function needed to write.
+//   • User         — the account (email/password is built in).
+//
+// There's no single "owner"/admin — it's multi-user: every signed-in (or guest)
+// visitor gets their own private chats.
+// ---------------------------------------------------------------------------
+
+const Conversation = entity(
+  "Conversation",
+  {
+    userId: field.string().owner(),
+    title: field.string().default("New chat"),
+    createdAt: field.datetime().defaultNow(),
+  },
+  {
+    indexes: [
+      { name: "by_user", fields: ["userId"], unique: false },
+      { name: "by_created", fields: ["createdAt"], unique: false },
+    ],
+  },
+);
+
+const Message = entity(
+  "Message",
+  {
+    conversationId: field.string(),
+    userId: field.string().owner(),
+    role: field.string(), // "user" | "assistant"
+    content: field.string(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  {
+    indexes: [
+      { name: "by_conversation", fields: ["conversationId"], unique: false },
+      { name: "by_user", fields: ["userId"], unique: false },
+    ],
+  },
+);
+
+const User = entity(
+  "User",
+  {
+    email: field.string(),
+    displayName: field.string().optional(),
+    passwordHash: field.string().serverOnly().optional(),
+    avatarColor: field.string().optional(),
+    emailVerified: field.datetime().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_email", fields: ["email"], unique: true }] },
+);
+
+// Conversations + messages are PRIVATE: a signed-in (or guest) user can only
+// read, create, and modify their OWN rows. `field.owner()` stamps userId from
+// the session on insert, so "create your own" is enforced at write time and
+// reads are scoped by the same id — your chats never leak to anyone else, and
+// the sync engine only ever ships you yours.
+const conversationPolicy = policy({
+  name: "conversation_owner",
+  entity: "Conversation",
+  allowRead: "auth.userId == data.userId",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "auth.userId == data.userId",
+  allowDelete: "auth.userId == data.userId",
+});
+
+const messagePolicy = policy({
+  name: "message_owner",
+  entity: "Message",
+  allowRead: "auth.userId == data.userId",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "auth.userId == data.userId",
+  allowDelete: "auth.userId == data.userId",
+});
+
+const userPolicy = policy({
+  name: "user_self",
+  entity: "User",
+  allowRead: "auth.userId == data.id",
+  allowInsert: "false",
+  allowUpdate: "false",
+  allowDelete: "false",
+});
+
+const manifest = buildManifest({
+  name: "__APP_NAME__",
+  version: "0.1.0",
+  entities: [Conversation, Message, User],
+  // No custom functions needed: messages are written with optimistic db.insert
+  // (owner-stamped), and streaming uses the built-in POST /api/ai/stream.
+  queries: [],
+  actions: [],
+  policies: [conversationPolicy, messagePolicy, userPolicy],
+  auth: auth(),
+  routes: await discoverAppRoutes(),
+});
+
+console.log(JSON.stringify(manifest, null, 2));
+
+export default manifest;

package/templates/ai-chat/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

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

@@ -0,0 +1,103 @@
+// THE single source of truth for everything brand-specific on this AI chat app.
+// Rebrand the whole thing by editing this ONE file — the layout + chat 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.
+
+/* ----------------------------- 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 };
+};
+
+// A selectable model. `id` is what's sent to /api/ai/stream; `provider` is just
+// a label for the picker. Which models are actually accepted is gated server-side
+// by PYLON_AI_MODELS_ALLOWED (+ the configured provider / gateway) — see README.
+export type ChatModel = { id: string; label: string; provider: string };
+
+export type ChatConfig = BaseConfig & {
+  chat: {
+    assistantName: string;
+    // Prepended as a system message on every request — sets the assistant's
+    // persona. Edit to retune the assistant without touching code.
+    systemPrompt: string;
+    emptyHeadline: string;
+    emptySubcopy: string;
+    inputPlaceholder: string;
+    // Starter prompts shown on the empty state; clicking one sends it.
+    suggestions: string[];
+    // The model picker. Curate to your setup: a single provider's models, or —
+    // with an OpenRouter-style gateway (PYLON_AI_PROVIDER=custom) — models across
+    // providers in one list. The selected id is sent as `model` per request.
+    models: ChatModel[];
+    defaultModel: string;
+  };
+};
+
+/* ----------------------------- config ---------------------------- */
+
+export const siteConfig: ChatConfig = {
+  brand: {
+    name: "Lumen",
+    letter: "L",
+    domain: "lumen.chat",
+    email: "hello@lumen.example",
+    footerBlurb: "A fast, streaming AI assistant built on Pylon.",
+    copyrightName: "Lumen",
+    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: "#6d28d9", brandSoft: "#ede9fe", paper: "#faf9fc" },
+
+  seo: {
+    title: "Lumen — a fast streaming AI assistant.",
+    description:
+      "A streaming AI chat app built on Pylon. Conversations sync across your tabs and devices in realtime; your API key never leaves the server.",
+  },
+
+  chat: {
+    assistantName: "Lumen",
+    systemPrompt:
+      "You are Lumen, a friendly, concise AI assistant. Answer clearly and get to the point. Use Markdown when it helps.",
+    emptyHeadline: "How can I help?",
+    emptySubcopy: "Ask anything. Your conversations are saved and stay in sync across your tabs.",
+    inputPlaceholder: "Message Lumen…",
+    suggestions: [
+      "Explain WebSockets like I'm five.",
+      "Draft a friendly out-of-office reply.",
+      "Give me 5 dinner ideas using chicken and rice.",
+      "What's the difference between SSR and SSG?",
+    ],
+    // Current Claude models (verify the ids for your provider before shipping —
+    // model names move fast). Whichever you keep here must be in
+    // PYLON_AI_MODELS_ALLOWED for switching to work (see .env.example). To offer
+    // models from OTHER providers (OpenAI, Google, …) in the same list, route
+    // through an OpenRouter-style gateway (PYLON_AI_PROVIDER=custom +
+    // PYLON_AI_BASE_URL) and use that gateway's slugs here.
+    models: [
+      { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6", provider: "Anthropic" },
+      { id: "claude-opus-4-8", label: "Claude Opus 4.8", provider: "Anthropic" },
+      { id: "claude-haiku-4-5", label: "Claude Haiku 4.5", provider: "Anthropic" },
+    ],
+    defaultModel: "claude-sonnet-4-6",
+  },
+};

package/templates/ai-chat/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-chat/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-chat/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/ai-studio/.env.example

@@ -0,0 +1,19 @@
+# Copy to `.env` and fill in. `pylon dev` loads `.env` automatically.
+#
+# The studio boots with NO config — generations return a clearly-labeled
+# placeholder so the flow + live gallery work out of the box. Add a Replicate
+# token to generate real image / audio / video. The token + provider call stay
+# on the server (read only inside the pollGeneration background job).
+
+# ── Replicate (optional — enables real generation) ───────────────────────────
+# Get a token at https://replicate.com/account/api-tokens
+# REPLICATE_API_TOKEN=r8_...
+
+# Override the model for any medium (defaults shown). They run the model's
+# latest version via Replicate's model-name endpoint, so no version hashes.
+# REPLICATE_IMAGE_MODEL=black-forest-labs/flux-schnell
+# REPLICATE_AUDIO_MODEL=meta/musicgen
+# REPLICATE_VIDEO_MODEL=minimax/video-01
+
+# ── Site URL (optional) ──────────────────────────────────────────────────────
+# SITE_URL=https://yourstudio.com

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

@@ -0,0 +1,83 @@
+# __APP_NAME__
+
+A generative **AI media studio** (image / audio / video) built with
+[Pylon](https://pylonsync.com) — a live gallery that fills in as each generation
+finishes, from one binary on one port. No Next.js, no separate job service.
+
+Kick off a generation and a card appears instantly, then flips to the finished
+result the moment the generation completes — live, across every open tab. The
+generation runs in a **background job** (so even a minutes-long video never
+blocks your request), and the provider call + API token stay on the server.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321 and generate something — it works with **no config**
+(a clearly-labeled placeholder). Add a Replicate token for real media (below).
+Then **open a second tab** — your gallery stays in sync.
+
+## Enable real generation (Replicate)
+
+```bash
+# .env  — get a token at https://replicate.com/account/api-tokens
+REPLICATE_API_TOKEN=r8_...
+# optional model overrides (defaults shown):
+REPLICATE_IMAGE_MODEL=black-forest-labs/flux-schnell
+REPLICATE_AUDIO_MODEL=meta/musicgen
+REPLICATE_VIDEO_MODEL=minimax/video-01
+```
+
+One provider, all three media. Models run via Replicate's model-name endpoint
+(latest version — no version hashes to maintain). Results are the provider's
+hosted URLs.
+
+## How it works (background jobs + realtime)
+
+- `Generation` is an **owner-scoped** entity read with `db.useQuery` — private
+  per user. Clients can't write it; only the server-side pipeline does.
+- `functions/generate.ts` (a `mutation`) inserts a `pending` row and enqueues a
+  job with `ctx.scheduler.runAfter` — then returns. No network I/O on the
+  request path, so slow models can't time it out.
+- `functions/pollGeneration.ts` (a scheduled `action`) starts the Replicate
+  prediction, then **reschedules itself** every few seconds until it settles,
+  writing the result via the internal `_updateGeneration` mutation. Each write
+  syncs to the owner's gallery — `pending → processing → done` — live.
+
+## Notes
+
+- Without a token, image generations return an SVG placeholder; audio/video
+  cards show a "add a token" note. The whole flow (and the background job) still
+  runs, so you can see the realtime gallery with zero config.
+- Results are Replicate's hosted URLs (fine for a live studio). For permanent
+  storage, download the asset in the job and persist via `/api/files`.
+- Video is genuinely wired (Replicate has text-to-video models) — it just takes
+  longer, which is exactly why the work runs in a background job.
+
+## Rebrand it
+
+Brand, colors, the generation kinds, and the starter prompts all live in
+**`lib/site.config.ts`**.
+
+## Layout
+
+```
+app.ts                          Generation (owner-scoped) + User
+lib/site.config.ts              brand + kinds + example prompts (edit this)
+lib/studio.ts                   types + the no-token placeholder generator
+functions/generate.ts           mutation: insert pending + enqueue the job
+functions/pollGeneration.ts     scheduled action: Replicate call + self-poll
+functions/_getGeneration.ts, _updateGeneration.ts   internal read/write
+app/page.tsx                    header + studio island
+app/studio-client.tsx           prompt bar + kind selector + live gallery
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com