@pylonsync/create-pylon 0.3.266 → 0.3.267

package/bin/create-pylon.js

@@ -86,8 +86,10 @@ const TEMPLATE_REGISTRY = {
 		platforms: ["web", "ios", "mac", "expo"],
 	},
 	todo: {
-		blurb: "CRUD + drag-reorder + optimistic mutations.",
-		platforms: ["web", "vite", "ios", "mac", "expo"],
+		blurb:
+			"Live, optimistic todo list — guest auth, owner-scoped, one server, no Next.js.",
+		platforms: [],
+		unified: true,
 	},
 	b2b: {
 		blurb: "Multi-tenant SaaS: orgs, members, roles, RBAC policies.",
@@ -116,6 +118,15 @@ const flags = {
 	template: takeValue(args, "--template"),
 	platforms: takeValue(args, "--platforms"),
 	skipInstall: args.includes("--skip-install"),
+	// --skill / --no-skill: install the Pylon skill into the new project via
+	// `npx skills add pylonsync/pylon` — the skills.sh CLI detects the coding
+	// agent (Claude Code / Codex / Cursor) and drops the always-current skill
+	// from this repo's skills/pylon/SKILL.md. undefined => prompt (default yes).
+	skill: args.includes("--skill")
+		? true
+		: args.includes("--no-skill")
+			? false
+			: undefined,
 	help: args.includes("--help") || args.includes("-h"),
 };
 
@@ -154,8 +165,8 @@ ${tmplLines.join("\n")}
 
 Examples:
   npm create @pylonsync/pylon my-app --template ssr         # full-stack SSR, no Next.js
+  npm create @pylonsync/pylon my-app --template todo        # live, optimistic todo (SSR, one port)
   npm create @pylonsync/pylon my-app
-  npm create @pylonsync/pylon my-app --template todo --platforms web,ios
   npm create @pylonsync/pylon my-app --template b2b --platforms web,mac
   npm create @pylonsync/pylon my-app --template chat --platforms ios,mac,expo
 `);
@@ -202,6 +213,16 @@ if (!flags.pm) {
 		.toLowerCase();
 	flags.pm = ["bun", "pnpm", "yarn", "npm"].includes(choice) ? choice : def;
 }
+if (flags.skill === undefined) {
+	const ans = (
+		await rl.question(
+			"Add the Pylon skill to your coding agent (Claude Code / Codex / Cursor)? [Y/n]: ",
+		)
+	)
+		.trim()
+		.toLowerCase();
+	flags.skill = ans !== "n" && ans !== "no";
+}
 rl.close();
 
 // Unified templates own no platforms — they ARE the whole app. For
@@ -467,6 +488,34 @@ if (!flags.skipInstall) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Optional: install the Pylon skill into the project's coding agent.
+//
+// `npx skills add pylonsync/pylon` (skills.sh) detects the installed agent
+// (Claude Code / Codex / Cursor) and drops the canonical skill from this
+// repo's skills/pylon/SKILL.md — always current, no stale bundled copy. We
+// only auto-run it when stdin is a TTY: the skills CLI prompts for scope and
+// agent, which would hang a non-interactive scaffold (CI, piped input). When
+// we can't run it, the footer prints the one-liner so the user can opt in.
+// ---------------------------------------------------------------------------
+
+const SKILL_INSTALL_CMD = "npx skills add pylonsync/pylon";
+let skillInstalled = false;
+if (flags.skill && stdin.isTTY) {
+	console.log("\nAdding the Pylon skill to your coding agent...");
+	const { spawnSync } = await import("node:child_process");
+	const result = spawnSync("npx", ["-y", "skills", "add", "pylonsync/pylon"], {
+		cwd: root,
+		stdio: "inherit",
+	});
+	skillInstalled = result.status === 0;
+	if (!skillInstalled) {
+		console.warn(
+			`\nCouldn't add the skill automatically. Run it yourself anytime:\n  ${SKILL_INSTALL_CMD}\n`,
+		);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Final instructions
 // ---------------------------------------------------------------------------
@@ -512,6 +561,12 @@ if (platforms.includes("mac"))
 if (platforms.includes("expo"))
 	layoutLines.push("  apps/expo         Expo + React Native");
 
+const skillLine = skillInstalled
+	? "\nPylon skill added to your coding agent (Claude Code / Codex / Cursor).\n"
+	: flags.skill
+		? `\nAdd the Pylon skill to your coding agent:\n  ${SKILL_INSTALL_CMD}\n`
+		: "";
+
 console.log(`
 ✓ Created ${projectName}
 
@@ -522,7 +577,7 @@ ${platformLines.join("\n")}
 
 Layout:
 ${layoutLines.join("\n")}
-
+${skillLine}
 Docs: https://docs.pylonsync.com
 `);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.266",
+  "version": "0.3.267",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,59 @@
+# __APP_NAME__
+
+A full-stack [Pylon](https://pylonsync.com) todo app — a server-rendered page
+and a live, optimistic, per-user todo list over a synced database, all served
+from one binary on one port. No Next.js, no separate API server.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Add a todo — it appears instantly (optimistic) and
+syncs; open a second tab to watch writes arrive live. Edit any file under
+`app/` and save — the page reloads instantly.
+
+## Layout
+
+```
+app.ts              data model + manifest (entities, policies, auth, routes)
+app/page.tsx        "/" — the server-rendered page (heading + intro)
+app/todo-app.tsx    client island: guest session + live, optimistic todo list
+app/layout.tsx      root layout wrapping every page
+app/globals.css     Tailwind entrypoint (compiled by Pylon)
+functions/          server functions (query/action) — typed RPC, if you need them
+```
+
+## How it works
+
+No login wall: `app/todo-app.tsx` wraps the list in `<EnsureGuest>`, which
+POSTs `/api/auth/guest` on first load so every visitor implicitly becomes their
+own user. Todos are private per browser — the `todo_access` policy in `app.ts`
+gates every read and write to the owner, and `userId: field.owner()` stamps the
+session's id server-side so the optimistic `db.insert("Todo", { title })` can't
+be spoofed. `db.useQuery("Todo")` is a live subscription; `db.insert` /
+`db.update` / `db.delete` are optimistic.
+
+To require real accounts instead, enable email/password (built in, against a
+`User` entity) and swap `<EnsureGuest>` for `<SignedIn>` / `<SignedOut>` from
+`@pylonsync/client`.
+
+## Add a route
+
+Drop a file at `app/about/page.tsx` and visit `/about`. Pages receive
+`{ url, params, searchParams, auth, response, serverData }` from the SSR
+runtime — all typed via `PageProps` from `@pylonsync/react`.
+
+## Add data
+
+Edit `app.ts`. Every `entity()` becomes a synced table with a REST + realtime
+API and a typed client — no migrations, no resolvers.
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com

package/templates/todo/app/error.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { type ErrorBoundaryProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+
+// `app/error.tsx` → the error boundary for this segment. It catches a throw
+// in any page/layout below it and renders at HTTP 500. It's HYDRATED, so
+// this is a real interactive client component: `reset()` re-attempts the
+// route, and useState/onClick work. The thrown error reaches the client as
+// `{ message, digest }` only — the stack stays in the dev overlay
+// (PYLON_DEV_MODE) and the server logs, never in the page.
+export default function Error({ error, reset }: ErrorBoundaryProps) {
+  const [tries, setTries] = React.useState(0);
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">
+          Something went wrong
+        </h1>
+        <p className="mt-2 text-muted-foreground">{error.message}</p>
+        {error.digest ? (
+          <p className="mt-1 text-xs text-muted-foreground/70">
+            Reference: <code>{error.digest}</code>
+          </p>
+        ) : null}
+      </section>
+      <div className="flex items-center gap-3">
+        <Button
+          onClick={() => {
+            setTries((n) => n + 1);
+            reset();
+          }}
+        >
+          Try again
+        </Button>
+        {tries > 0 ? (
+          <span className="text-sm text-muted-foreground">
+            Retried {tries} {tries === 1 ? "time" : "times"}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/templates/todo/app/globals.css

@@ -0,0 +1,139 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+/* Tailwind v4 scans these globs for class names. `components/` is here so
+   shadcn/ui component classes are seen — add more @source lines if you put
+   markup elsewhere. */
+@source "../app/**/*.{tsx,ts,jsx,js}";
+@source "../components/**/*.{tsx,ts,jsx,js}";
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* shadcn/ui design tokens (new-york / zinc). Edit these to re-theme the
+   whole app; `npx shadcn@latest add <component>` drops new components that
+   consume the same variables. Toggle dark mode by putting `class="dark"`
+   on <html>. */
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.92 0.004 286.32);
+  --primary-foreground: oklch(0.21 0.006 285.885);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-border, currentColor);
+    outline-color: var(--color-ring);
+  }
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+  button {
+    cursor: pointer;
+  }
+}

package/templates/todo/app/layout.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+
+// A layout wraps every page. This one is intentionally minimal — a header
+// and a centered column. The page below it is server-rendered first (so the
+// shell and copy are in the HTML), then hydrates into the live todo UI.
+interface LayoutProps {
+  children: React.ReactNode;
+}
+
+export default function RootLayout({ children }: LayoutProps) {
+  // Add `className="dark"` to this <html> to flip every shadcn token to its
+  // dark value. The classes below use semantic tokens (bg-background,
+  // text-foreground, …) so the whole UI re-themes from app/globals.css.
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>__APP_NAME__</title>
+        {/* Tailwind is compiled by Pylon from app/globals.css and the
+            stylesheet link is injected here automatically — nothing to
+            wire up. */}
+      </head>
+      <body className="min-h-screen bg-background text-foreground antialiased">
+        <main className="mx-auto flex min-h-screen max-w-xl flex-col px-4 py-12">
+          {children}
+        </main>
+      </body>
+    </html>
+  );
+}

package/templates/todo/app/not-found.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import { Link, useRouter, type NotFoundProps } from "@pylonsync/react";
+import { Button } from "@/components/ui/button";
+
+// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when
+// a page calls `response.notFound()`). It's HYDRATED, so it's interactive:
+// the buttons below use the client router. Not-found boundaries receive the
+// standard page props (and, matching Next, no `reset`).
+export default function NotFound(_props: NotFoundProps) {
+  const router = useRouter();
+  return (
+    <div className="space-y-6">
+      <section>
+        <h1 className="text-2xl font-semibold tracking-tight">404</h1>
+        <p className="mt-2 text-muted-foreground">
+          We couldn&apos;t find that page.
+        </p>
+      </section>
+      <div className="flex items-center gap-3">
+        <Button onClick={() => router.back()} variant="outline">
+          ← Go back
+        </Button>
+        <Button asChild>
+          <Link href="/">Home</Link>
+        </Button>
+      </div>
+    </div>
+  );
+}

package/templates/todo/app/page.tsx

@@ -0,0 +1,37 @@
+import React from "react";
+import { type Metadata } from "@pylonsync/react";
+import { TodoApp } from "./todo-app";
+
+// SEO metadata. Export `metadata` (static) or `generateMetadata(props)`
+// (dynamic) from any page or layout — Pylon renders the <title>/<meta>
+// into <head> server-side. The `Metadata` type is exported from
+// @pylonsync/react.
+export const metadata: Metadata = {
+  title: "__APP_NAME__ — a live Pylon todo",
+  description:
+    "A server-rendered todo list with live, optimistic, per-user sync — one binary, one port. Open two tabs and watch them stay in sync.",
+};
+
+// `app/page.tsx` → `/`. The heading and intro are server-rendered (view
+// source and they're in the HTML — good for SEO and first paint). The list
+// itself is a client island: `<TodoApp>` mints a guest session and runs the
+// live query + optimistic writes in the browser.
+export default function IndexPage() {
+  return (
+    <div className="flex flex-1 flex-col">
+      <header className="mb-8">
+        <h1 className="text-3xl font-semibold tracking-tight">Todos</h1>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Live and optimistic over one Pylon backend. Open a second tab —
+          changes sync instantly.
+        </p>
+      </header>
+      <TodoApp />
+      <p className="mt-8 text-xs text-muted-foreground">
+        Edit <code className="rounded bg-muted px-1">app/todo-app.tsx</code> for
+        the UI, or <code className="rounded bg-muted px-1">app.ts</code> for the
+        data model and access policies.
+      </p>
+    </div>
+  );
+}

package/templates/todo/app/robots.ts

@@ -0,0 +1,12 @@
+import type { Robots } from "@pylonsync/react";
+
+// app/robots.ts → served at /robots.txt. The default export may also be async.
+const SITE = process.env.SITE_URL ?? "http://localhost:4321";
+
+export default function robots(): Robots {
+  return {
+    // Keep the authenticated app and the API out of the index.
+    rules: { userAgent: "*", allow: "/", disallow: ["/dashboard", "/api/"] },
+    sitemap: `${SITE}/sitemap.xml`,
+  };
+}

package/templates/todo/app/sitemap.ts

@@ -0,0 +1,27 @@
+import type { Sitemap } from "@pylonsync/react";
+
+// app/sitemap.ts → served at /sitemap.xml. The default export can be async, so
+// it can enumerate dynamic pages from your database. Point SITE_URL at your
+// domain in production.
+const SITE = process.env.SITE_URL ?? "http://localhost:4321";
+
+export default async function sitemap(): Promise<Sitemap> {
+  // Only public pages belong here — /dashboard is private (and noindex), so
+  // it's intentionally left out.
+  const staticRoutes: Sitemap = [
+    { url: `${SITE}/`, changeFrequency: "weekly", priority: 1 },
+    { url: `${SITE}/login`, changeFrequency: "yearly", priority: 0.3 },
+    { url: `${SITE}/signup`, changeFrequency: "yearly", priority: 0.5 },
+  ];
+
+  // The export is async, so you can enumerate dynamic pages from a DB read:
+  //
+  //   const posts = await fetchPublishedPosts();
+  //   const postRoutes: Sitemap = posts.map((p) => ({
+  //     url: `${SITE}/blog/${p.slug}`,
+  //     lastModified: p.updatedAt,
+  //   }));
+  //   return [...staticRoutes, ...postRoutes];
+
+  return staticRoutes;
+}

package/templates/todo/app/todo-app.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import React, { useState } from "react";
+import { db } from "@pylonsync/react";
+import { EnsureGuest } from "@pylonsync/client";
+import { Button } from "@/components/ui/button";
+
+export interface Todo {
+  id: string;
+  title: string;
+  done: boolean;
+}
+
+// `<EnsureGuest>` mints a guest session (POST /api/auth/guest) on first load
+// if the browser doesn't already have one, so the list works with no login —
+// every visitor implicitly becomes their own user and their todos stay
+// private. The list itself is gated to the owner by the policy in app.ts.
+export function TodoApp() {
+  return (
+    <EnsureGuest fallback={<ListSkeleton />}>
+      <TodoList />
+    </EnsureGuest>
+  );
+}
+
+// `db.useQuery` is a LIVE subscription — it re-renders the instant a Todo is
+// added, toggled, or removed, in this tab or another. `db.insert` /
+// `db.update` / `db.delete` are OPTIMISTIC: they apply to the local store
+// immediately (zero-latency UI) and sync in the background, rolling back
+// automatically if a policy rejects the write.
+function TodoList() {
+  const [title, setTitle] = useState("");
+  const { data: todos, loading } = db.useQuery<Todo>("Todo");
+
+  async function addTodo(e: React.FormEvent) {
+    e.preventDefault();
+    const text = title.trim();
+    if (!text) return;
+    setTitle("");
+    // We don't send userId — `field.owner()` stamps it from the session
+    // server-side and rejects any forged value, so this optimistic insert is
+    // safe.
+    await db.insert("Todo", { title: text, done: false });
+  }
+
+  const remaining = todos.filter((t) => !t.done).length;
+
+  return (
+    <div className="space-y-5">
+      <form onSubmit={addTodo} className="flex items-center gap-2">
+        <input
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="Add a todo…"
+          aria-label="Todo"
+          autoComplete="off"
+          className="flex h-10 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        />
+        <Button type="submit">Add</Button>
+      </form>
+
+      {loading && todos.length === 0 ? (
+        <ListSkeleton />
+      ) : todos.length === 0 ? (
+        <p className="text-sm text-muted-foreground">
+          Nothing yet — add a todo above. It appears instantly (optimistic) and
+          syncs; open this page in a second tab to watch it arrive live.
+        </p>
+      ) : (
+        <>
+          <ul className="space-y-2">
+            {todos.map((todo) => (
+              <li
+                key={todo.id}
+                className="flex items-center gap-3 rounded-md border px-3 py-2.5 text-sm"
+              >
+                <button
+                  type="button"
+                  aria-label={todo.done ? "Mark not done" : "Mark done"}
+                  onClick={() => db.update("Todo", todo.id, { done: !todo.done })}
+                  className={
+                    "flex size-5 items-center justify-center rounded-full border text-xs transition-colors " +
+                    (todo.done
+                      ? "border-emerald-600 bg-emerald-600 text-white"
+                      : "border-muted-foreground/30 text-transparent hover:border-muted-foreground")
+                  }
+                >
+                  ✓
+                </button>
+                <span
+                  className={
+                    todo.done
+                      ? "flex-1 text-muted-foreground line-through"
+                      : "flex-1"
+                  }
+                >
+                  {todo.title}
+                </span>
+                <button
+                  type="button"
+                  aria-label="Delete todo"
+                  onClick={() => db.delete("Todo", todo.id)}
+                  className="text-muted-foreground/40 transition-colors hover:text-red-600"
+                >
+                  ✕
+                </button>
+              </li>
+            ))}
+          </ul>
+          <p className="text-xs text-muted-foreground">
+            {remaining} {remaining === 1 ? "todo" : "todos"} left
+          </p>
+        </>
+      )}
+    </div>
+  );
+}
+
+function ListSkeleton() {
+  return (
+    <ul className="space-y-2" aria-hidden>
+      {[0, 1, 2].map((i) => (
+        <li
+          key={i}
+          className="flex items-center gap-3 rounded-md border px-3 py-2.5"
+        >
+          <span className="size-5 rounded-full bg-muted" />
+          <span className="h-4 flex-1 rounded bg-muted" />
+        </li>
+      ))}
+    </ul>
+  );
+}

package/templates/todo/app.ts

@@ -0,0 +1,72 @@
+import {
+  entity,
+  field,
+  policy,
+  auth,
+  buildManifest,
+  discoverAppRoutes,
+} from "@pylonsync/sdk";
+
+// A todo that belongs to one person. `userId: field.owner()` is the key
+// move: the framework stamps the signed-in (here: guest) user's id
+// server-side on insert and rejects any forged value — so the UI can do a
+// plain, optimistic `db.insert("Todo", { title })` (the row shows instantly,
+// no round-trip) while ownership stays unspoofable. No createTodo function to
+// write — every verb is a direct, policy-checked entity call.
+const Todo = entity(
+  "Todo",
+  {
+    userId: field.string().owner(),
+    title: field.string(),
+    done: field.boolean().default(false),
+    // Float sort key so a drag-reorder can drop a row between two others by
+    // taking their midpoint — no renumbering the whole list. New rows seed
+    // with createdAt so the default order is chronological.
+    sortKey: field.float().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_user", fields: ["userId"], unique: false }] },
+);
+
+// Todos are private — every read and write is gated to the owner. An entity
+// with NO policy is denied to clients by default, so this is exactly what
+// makes the live query + optimistic writes work, and only for your own rows.
+// `auth.userId` is the session user (a guest id here); `data.userId` is the
+// row's owner.
+const todoPolicy = policy({
+  name: "todo_access",
+  entity: "Todo",
+  allowRead: "auth.userId == data.userId",
+  allowInsert: "auth.userId != null",
+  allowUpdate: "auth.userId == data.userId",
+  allowDelete: "auth.userId == data.userId",
+});
+
+// The manifest is your whole app in one object: data, policies, and the
+// file-based routes under `app/`. `pylon dev` reads this, serves the SSR
+// frontend and the API from one port, and regenerates a typed client on
+// every change.
+//
+// This starter uses guest sessions: the page wraps its UI in `<EnsureGuest>`,
+// which POSTs `/api/auth/guest` on first load so every visitor implicitly
+// becomes their own user — no login wall, todos still private per browser.
+// To require real accounts instead, enable email/password (it's built in
+// against a `User` entity) and swap `<EnsureGuest>` for `<SignedIn>` /
+// `<SignedOut>` from `@pylonsync/client`.
+const manifest = buildManifest({
+  name: "__APP_NAME__",
+  version: "0.1.0",
+  entities: [Todo],
+  queries: [],
+  actions: [],
+  policies: [todoPolicy],
+  auth: auth(),
+  // File-based routing: `discoverAppRoutes()` walks `app/**/page.tsx` and
+  // emits one route per page. Drop `app/about/page.tsx` to add `/about`.
+  routes: await discoverAppRoutes(),
+});
+
+// Emit canonical manifest JSON to stdout for `pylon codegen`.
+console.log(JSON.stringify(manifest, null, 2));
+
+export default manifest;

package/templates/todo/components/ui/button.tsx

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  },
+);
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

package/templates/todo/components/ui/card.tsx

@@ -0,0 +1,90 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "rounded-xl border bg-card text-card-foreground shadow-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardHeader({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn("flex flex-col space-y-1.5 p-6", className)}
+      {...props}
+    />
+  );
+}
+
+function CardTitle({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("font-semibold leading-none tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+function CardContent({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("p-6 pt-0", className)}
+      {...props}
+    />
+  );
+}
+
+function CardFooter({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center p-6 pt-0", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+};

package/templates/todo/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/todo/functions/_keep.ts

@@ -0,0 +1,13 @@
+// Server functions go here. Each file in this directory that exports a
+// query() or action() becomes a typed RPC endpoint, callable from your
+// pages and client with full type inference. Delete this placeholder when
+// you add your first one.
+//
+// Example (functions/notes.ts):
+//
+//   import { query } from "@pylonsync/functions";
+//
+//   export const listNotes = query(async (ctx) => {
+//     return ctx.db.list("Note");
+//   });
+export {};

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

@@ -0,0 +1,33 @@
+{
+  "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/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/todo/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"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["app.ts", "app/**/*", "components/**/*", "lib/**/*"]
+}