@pylonsync/create-pylon 0.3.273 → 0.3.275

package/templates/directory/functions/submitListing.ts

@@ -0,0 +1,63 @@
+import { mutation, v } from "@pylonsync/functions";
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/.+/i;
+
+// submitListing — a visitor proposes a new directory entry. A `mutation` (it
+// writes the Submission transactionally). `auth: "public"` — submitters have no
+// account.
+//
+// PRIVACY: returns only `{ ok }`, never a Submission row. The entry is NOT
+// public yet — it's written as a pending Submission (deny-all) for the owner to
+// review; approveSubmission is what turns it into a public Listing.
+export default mutation<
+  {
+    submitterName: string;
+    submitterEmail: string;
+    name: string;
+    tagline: string;
+    url: string;
+    category: string;
+    tags?: string;
+    description?: string;
+  },
+  { ok: boolean }
+>({
+  auth: "public",
+  args: {
+    submitterName: v.string(),
+    submitterEmail: v.string(),
+    name: v.string(),
+    tagline: v.string(),
+    url: v.string(),
+    category: v.string(),
+    tags: v.optional(v.string()),
+    description: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const submitterName = args.submitterName.trim();
+    const submitterEmail = args.submitterEmail.trim().toLowerCase();
+    const name = args.name.trim();
+    const url = args.url.trim();
+    if (!submitterName) throw ctx.error("INVALID_ARGS", "Your name is required.");
+    if (!EMAIL_RE.test(submitterEmail)) throw ctx.error("INVALID_ARGS", "Enter a valid email.");
+    if (!name) throw ctx.error("INVALID_ARGS", "The listing name is required.");
+    if (!URL_RE.test(url)) throw ctx.error("INVALID_ARGS", "Enter a valid URL (https://…).");
+
+    const clip = (s: string | undefined, n: number) => (s ? s.trim().slice(0, n) : null);
+
+    await ctx.db.unsafe.insert("Submission", {
+      submitterName: submitterName.slice(0, 120),
+      submitterEmail: submitterEmail.slice(0, 254),
+      name: name.slice(0, 120),
+      tagline: clip(args.tagline, 160) ?? "",
+      url: url.slice(0, 500),
+      category: clip(args.category, 60) ?? "",
+      tags: clip(args.tags, 160),
+      description: clip(args.description, 2000),
+      status: "new",
+      createdAt: new Date().toISOString(),
+    });
+    return { ok: true };
+  },
+});

package/templates/directory/functions/upvote.ts

@@ -0,0 +1,24 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// upvote — bump a listing's vote count. Public (anyone browsing can vote) and
+// the realtime heart of the template: the Listing.votes write syncs to every
+// open browse grid, so the count ticks up for everyone live. A per-listing
+// advisory lock makes the read-then-increment race-safe under concurrent votes.
+//
+// Listings are deny-write to clients, so votes can ONLY move through here — a
+// client can't forge a count. (Dedupe is best-effort on the client via
+// localStorage; a production directory would tie votes to a session/Vote row.)
+export default mutation<{ listingId: string }, { ok: boolean; votes: number }>({
+  auth: "public",
+  args: { listingId: v.id("Listing") },
+  async handler(ctx, args) {
+    await ctx.db.advisoryLock(`directory_listing:${args.listingId}`);
+    const listing = (await ctx.db.get("Listing", args.listingId)) as
+      | { votes: number }
+      | null;
+    if (!listing) throw ctx.error("NOT_FOUND", "Listing not found.");
+    const votes = (listing.votes ?? 0) + 1;
+    await ctx.db.unsafe.update("Listing", args.listingId, { votes });
+    return { ok: true, votes };
+  },
+});

package/templates/directory/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/directory/lib/directory.ts

@@ -0,0 +1,45 @@
+// Shared directory types. The Submission row is what the owner dashboard sees
+// (with PII); the client imports only the type, never server code.
+
+// A public listing as it syncs to the browse grid (no PII).
+export interface ListingRow {
+  id: string;
+  name: string;
+  tagline: string;
+  url: string;
+  category: string;
+  tags?: string | null;
+  description?: string | null;
+  votes: number;
+  featured: boolean;
+  createdAt: string;
+}
+
+export interface SubmissionRow {
+  id: string;
+  submitterName: string;
+  submitterEmail: string;
+  name: string;
+  tagline: string;
+  url: string;
+  category: string;
+  tags?: string | null;
+  description?: string | null;
+  status: string; // "new" | "approved" | "rejected"
+  createdAt: string;
+}
+
+// submissionsForOwner returns a discriminated result rather than throwing on a
+// non-owner (a query has no `ctx.error`; a bare throw becomes a stripped
+// HANDLER_ERROR). A non-owner gets `{ authorized: false }` and NO data.
+export type OwnerSubmissionsResult =
+  | { authorized: true; submissions: SubmissionRow[] }
+  | { authorized: false };
+
+// Split a comma-separated tag string into trimmed chips.
+export function parseTags(tags?: string | null): string[] {
+  return (tags ?? "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean);
+}

package/templates/directory/lib/owner.ts

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

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

@@ -0,0 +1,130 @@
+// THE single source of truth for everything business-specific on this directory
+// site. Rebrand the whole thing by editing this ONE file — the landing page,
+// layout, and the seedListings function all read from here. The create-pylon
+// scaffolder and Mast target this file: a whole directory is themed + seeded
+// from one typed object.
+//
+// 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 starter directory entry (seeds the public Listing table on first visit).
+export type SeedListing = {
+  name: string;
+  tagline: string;
+  url: string;
+  category: string;
+  tags?: string; // comma-separated
+  description?: string;
+  votes?: number;
+  featured?: boolean;
+};
+
+export type DirectoryConfig = BaseConfig & {
+  hero: {
+    tagline: string;
+    headline: string;
+    subcopy: string;
+    ctaLabel: string;
+    searchPlaceholder: string;
+  };
+  browse: { eyebrow: string; headline: string };
+  // The facet values offered in the submit form's category select. The browse
+  // facet sidebar is built live from the data, so this only needs to cover what
+  // submitters can pick.
+  categories: string[];
+  seedListings: SeedListing[];
+  submit: {
+    eyebrow: string;
+    headline: string;
+    subcopy: string;
+    confirmationMessage: string;
+  };
+};
+
+/* ----------------------------- config ---------------------------- */
+
+export const siteConfig: DirectoryConfig = {
+  brand: {
+    name: "Stacked",
+    letter: "S",
+    domain: "stacked.dev",
+    email: "hello@stacked.example",
+    footerBlurb:
+      "A hand-checked directory of the tools developers actually reach for. Search it, sort by votes, and submit the ones we're missing.",
+    copyrightName: "Stacked",
+    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: "#7c3aed", brandSoft: "#ede9fe", paper: "#faf9fc" },
+
+  seo: {
+    title: "Stacked — the developer tools directory.",
+    description:
+      "A searchable, community-voted directory of developer tools. Full-text search, filter by category, upvote your favorites, and submit the ones we're missing.",
+  },
+
+  hero: {
+    tagline: "The dev tools directory",
+    headline: "The tools developers actually use.",
+    subcopy:
+      "Search a hand-checked directory of developer tools, filter by category, and upvote the ones that earn it. Live results, live votes — no signup to browse.",
+    ctaLabel: "Submit a tool",
+    searchPlaceholder: "Search tools — try “database”, “deploy”, “auth”…",
+  },
+
+  browse: {
+    eyebrow: "Browse",
+    headline: "Find your next tool.",
+  },
+
+  categories: ["Database", "Hosting", "Auth", "AI", "Analytics", "Design", "Productivity", "DevOps"],
+
+  // Fictional-but-plausible starter entries across categories. Replace with your
+  // own; `votes` seeds the leaderboard so "Top voted" isn't a flat list.
+  seedListings: [
+    { name: "Quill", tagline: "Postgres with a realtime sync engine baked in.", url: "https://example.com/quill", category: "Database", tags: "postgres, realtime, sync", votes: 342, featured: true },
+    { name: "Tigris Store", tagline: "S3-compatible object storage at the edge.", url: "https://example.com/tigris", category: "Hosting", tags: "storage, edge, s3", votes: 218 },
+    { name: "Gatekeep", tagline: "Drop-in auth: passkeys, OAuth, and magic links.", url: "https://example.com/gatekeep", category: "Auth", tags: "auth, passkeys, oauth", votes: 287, featured: true },
+    { name: "Loom AI", tagline: "Self-hostable LLM gateway with caching + routing.", url: "https://example.com/loom", category: "AI", tags: "llm, gateway, cache", votes: 401, featured: true },
+    { name: "Pulse", tagline: "Privacy-first product analytics you can self-host.", url: "https://example.com/pulse", category: "Analytics", tags: "analytics, privacy", votes: 174 },
+    { name: "Frame", tagline: "A design-token pipeline from Figma to code.", url: "https://example.com/frame", category: "Design", tags: "design, tokens, figma", votes: 132 },
+    { name: "Cadence", tagline: "Background jobs + cron with a visual dashboard.", url: "https://example.com/cadence", category: "DevOps", tags: "jobs, cron, queue", votes: 209 },
+    { name: "Inbox Zero", tagline: "Transactional email with a real templating story.", url: "https://example.com/inbox", category: "Productivity", tags: "email, templates", votes: 96 },
+    { name: "Shipyard", tagline: "Preview deploys for every PR, in seconds.", url: "https://example.com/shipyard", category: "Hosting", tags: "deploy, ci, preview", votes: 263 },
+    { name: "Vector Vault", tagline: "Managed vector search without the ops.", url: "https://example.com/vectorvault", category: "AI", tags: "vector, search, rag", votes: 188 },
+    { name: "Schema", tagline: "Type-safe migrations that review themselves.", url: "https://example.com/schema", category: "Database", tags: "migrations, types", votes: 151 },
+    { name: "Watchtower", tagline: "Uptime + error tracking in one calm dashboard.", url: "https://example.com/watchtower", category: "DevOps", tags: "monitoring, errors", votes: 144 },
+  ],
+
+  submit: {
+    eyebrow: "Submit a tool",
+    headline: "Know one we're missing?",
+    subcopy:
+      "Send it over. Submissions land in the curator's queue — once it's approved it shows up in the directory for everyone.",
+    confirmationMessage: "Thanks — your submission's in the queue. We review new tools a few times a week.",
+  },
+};

package/templates/directory/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/directory/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/directory/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/local-service/.env.example

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

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

@@ -0,0 +1,82 @@
+# __APP_NAME__
+
+A booking site for an appointment business (salon, barber, trainer, clinic,
+trades…) built with [Pylon](https://pylonsync.com) — a server-rendered
+marketing page with **live slot availability** and a private owner dashboard,
+all served from one binary on one port. No Next.js, no separate API server.
+
+The realtime point: the time picker shows what's *actually* free, and a slot
+greys out for everyone the instant someone books it.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Pick a service and a time. Then **open a second
+tab**, book a slot in one, and watch that slot grey out in the other — with no
+refresh.
+
+## How the realtime works
+
+- `app/booking-widget.tsx` subscribes to the public, PII-free `BookedSlot`
+  projection with `db.useQuery`, so taken times grey out live across every tab.
+- `functions/createBooking.ts` is a public **mutation** that re-checks the slot
+  is still free (under a per-day advisory lock) before writing — so even a
+  dead-heat double-click can't double-book. It writes the `Booking` (with the
+  customer's details) and the `BookedSlot` (just the time range).
+- `functions/cancelBooking.ts` deletes the `BookedSlot`, which frees the time
+  on every open picker instantly.
+
+## Privacy — read this
+
+The `Booking` entity holds the customer's name, email, and phone (PII), so its
+policy in `app.ts` **denies every client read and write**. The public page only
+ever reads `BookedSlot` — a name/email-free `{ startsAt, endsAt }` projection.
+The full bookings, with contact details, are returned only by
+`bookingsForOwner`, gated to the owner server-side. A booking site must never
+leak its customers' contact details, and this is how that's guaranteed.
+
+## The owner dashboard
+
+`/dashboard` shows upcoming bookings grouped by day, with confirm/cancel and the
+customer's contact details — updating live as bookings land and cancel.
+
+Set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to the email you'll sign
+in with, then create that account at `/login`. Only that account can see
+bookings.
+
+## Rebrand + reconfigure it
+
+Everything lives in **`lib/site.config.ts`** — brand, colors, services (name /
+duration / price), weekly hours, slot length, lead time, reviews, location, FAQ.
+Edit that one file (or have a generator produce it) and the whole site — and the
+booking engine — reconfigures. Services and hours are config, not a database to
+manage.
+
+## Layout
+
+```
+app.ts                       data model (Booking, BookedSlot, User) + policies
+lib/site.config.ts           ALL copy + brand + services + hours (edit this)
+lib/slots.ts                 pure slot math, shared by picker + server re-check
+lib/booking.ts               shared booking-row types
+lib/owner.ts                 owner-email gate (PYLON_OWNER_EMAIL)
+functions/createBooking.ts   public mutation: re-check + book (race-safe)
+functions/bookingsForOwner.ts  owner-only query: bookings + customer PII
+functions/{confirm,cancel}Booking.ts  owner-only mutations
+app/page.tsx                 the landing page (server-rendered)
+app/booking-widget.tsx       client island: live slot picker + booking form
+app/login/page.tsx           owner sign-in
+app/dashboard/               owner dashboard (auth-gated, live)
+app/globals.css              Tailwind entrypoint (compiled by Pylon)
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com