@pylonsync/create-pylon 0.3.274 → 0.3.276

package/bin/create-pylon.js

@@ -111,6 +111,72 @@ const TEMPLATE_REGISTRY = {
 		platforms: [],
 		unified: true,
 	},
+	waitlist: {
+		blurb:
+			"Coming-soon landing — email capture + a LIVE signup counter (two tabs, no refresh) + owner dashboard. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	"local-service": {
+		blurb:
+			"Appointment business — services + booking with LIVE slot availability (a slot greys out for everyone the instant it's booked) + owner dashboard. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	saas: {
+		blurb:
+			"SaaS app — marketing landing + multi-tenant dashboard (orgs, members, tenant-scoped data). The 'saas' archetype; identical to the default template.",
+		platforms: [],
+		unified: true,
+	},
+	restaurant: {
+		blurb:
+			"Restaurant — menu + reservations with LIVE table availability (each seating shows tables-left, greys to 'Full' instantly) + owner dashboard. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	creator: {
+		blurb:
+			"Personal brand / creator — bio + offerings + a newsletter signup with a LIVE subscriber counter + owner dashboard. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	shop: {
+		blurb:
+			"DTC store — product grid with LIVE inventory (stock ticks down, flips to 'Sold out' instantly), cart + real Stripe checkout (graceful no-key fallback) + owner dashboard (orders + stock). One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	agency: {
+		blurb:
+			"Design/dev studio — services, case-study portfolio, team + a project inquiry form. LIVE availability (hero shows open project slots; booking a lead from the dashboard drops it instantly) + owner pipeline. Clearly-marked photo placeholders. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	marketplace: {
+		blurb:
+			"Two-sided marketplace — SSR browse grid + listing detail pages (SEO) with REALTIME offers, a live 'just listed' ticker, buy-now/make-offer/watch, and per-user inbox. Email/password auth, owner-stamped listings/offers. Multi-user (no single owner). One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	directory: {
+		blurb:
+			"Curated directory — LIVE full-text search + category facets (db.useSearch), community upvotes that tick up across tabs, and a moderated submit flow (deny-all PII → curator approves → public). Showcases Pylon FTS. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	"ai-chat": {
+		blurb:
+			"Streaming AI chat — token streaming via the built-in /api/ai/stream (your key stays server-side), multi-conversation history that's owner-scoped + synced across tabs in realtime, guest or signed-in. Set PYLON_AI_API_KEY to enable. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
+	"ai-studio": {
+		blurb:
+			"Generative media studio (image/audio/video) — a LIVE gallery that fills in as each background job finishes (pending card → result, synced across tabs). Owner-scoped generations; provider call + key stay server-side. Boots with a no-key placeholder; set REPLICATE_API_TOKEN for real image/audio/video. One SSR app.",
+		platforms: [],
+		unified: true,
+	},
 };
 const TEMPLATES_AVAILABLE = Object.keys(TEMPLATE_REGISTRY);
 
@@ -176,6 +242,16 @@ Examples:
   npm create @pylonsync/pylon my-app --template todo        # live, optimistic todo (SSR, one port)
   npm create @pylonsync/pylon my-app --template b2b          # minimal multi-tenant (orgs, members, RBAC)
   npm create @pylonsync/pylon my-app --template chat         # realtime live chat room
+  npm create @pylonsync/pylon my-app --template waitlist     # coming-soon landing + live signup counter
+  npm create @pylonsync/pylon my-app --template local-service # appointment business + live booking availability
+  npm create @pylonsync/pylon my-app --template restaurant   # restaurant menu + live reservation availability
+  npm create @pylonsync/pylon my-app --template creator      # personal brand + live newsletter subscriber count
+  npm create @pylonsync/pylon my-app --template shop         # DTC store + live inventory
+  npm create @pylonsync/pylon my-app --template agency       # studio/agency + live project availability
+  npm create @pylonsync/pylon my-app --template marketplace  # two-sided marketplace + realtime offers
+  npm create @pylonsync/pylon my-app --template directory    # searchable directory + facets + live upvotes
+  npm create @pylonsync/pylon my-app --template ai-chat      # streaming LLM chat + synced history
+  npm create @pylonsync/pylon my-app --template ai-studio    # generative media studio + live gallery
 `);
 	exit(0);
 }
@@ -201,6 +277,10 @@ if (!flags.template) {
 // `ssr` was the original name of the default template; keep it working as a
 // quiet alias so older `--template ssr` invocations don't break.
 if (flags.template === "ssr") flags.template = "default";
+// `saas` is the archetype NAME for the default template (a SaaS landing +
+// multi-tenant dashboard). It scaffolds the exact same app as `default`; we
+// alias rather than duplicate the whole tree so there's one source of truth.
+if (flags.template === "saas") flags.template = "default";
 // `unified` templates (default) are a single app, not a monorepo — they take
 // no platforms. Skip the platform prompt + validation for them entirely.
 const isUnified = TEMPLATE_REGISTRY[flags.template]?.unified === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.274",
+  "version": "0.3.276",
   "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/ARCHETYPES.md

@@ -0,0 +1,339 @@
+# Landing-page archetype templates
+
+Default templates Mast picks from when it builds a site for a new business. Each
+is a real `create-pylon` template (landing + dashboard + a live backend), so
+they're useful to every Pylon user too — Mast just adds a classifier that maps a
+business description to one of these and fills its config.
+
+## Principles
+- **An archetype is a section structure + one real realtime feature, not just
+  copy/colors.** Anyone can have an LLM emit a static landing page now. The edge
+  is that the generated site has a live backend doing something. Every template
+  ships with exactly one genuinely-realtime hook.
+- **Shared foundation.** All templates share the brand/colors/seo config base
+  (see the default template's `lib/site.config.ts`) and the marketing component
+  kit (`WRAP`, `Eyebrow`, `SectionHead`, `FeatureGrid`, `Shot`, etc.). An
+  archetype adds its own sections, config slots, and backend entities.
+- **Customization = generate one `site.config.ts`** (plus optional seed rows for
+  archetypes with lists, e.g. services/menu). Same contract as the default.
+- **Privacy is part of the spec.** Landing pages are public. Any entity holding
+  visitor PII (emails, phones) must deny client reads — writes go through a
+  server action, and only aggregates (a count) or non-PII fields (busy time
+  slots) are exposed to the page. Never let a marketing site leak its own
+  customers' emails.
+
+## Shared config base
+```ts
+type BaseConfig = {
+  brand: { name; letter; domain; email; footerBlurb; copyrightName; socials };
+  colors: { brand; brandSoft; paper };
+  seo: { title; description };
+};
+```
+Each archetype below is `BaseConfig & { ...archetype slots }`.
+
+## Mast classifier contract
+Input: the business description. Output:
+```ts
+{ template: "waitlist" | "local-service" | "saas" | "restaurant" | "shop" | "creator" | "agency" | "marketplace" | "directory",
+  siteConfig: <that template's typed config>,
+  seed?: { services?: [...]; menu?: [...] }  // list rows for archetypes that have them
+}
+```
+Ambiguous or clearly pre-revenue → `waitlist` (safe universal default). Known
+operating business → the matching archetype.
+
+---
+
+# 1. `waitlist` — pre-launch / coming-soon  ★ build first (dogfood target)
+
+**Who:** validating demand, "I just started," pre-revenue, or fallback when the
+business type is unclear.
+
+**Sections (single page):**
+1. Hero — badge ("Coming soon"), headline, subcopy, **email capture form + live
+   signup counter** ("1,247 people waiting").
+2. Value props — 3 items (what it is / who it's for / why now).
+3. Social proof — optional logos or quotes.
+4. FAQ — optional, short.
+5. Footer.
+
+**Realtime feature:** the signup counter ticks up for everyone with the page
+open. Open two tabs, submit in one, the other increments without refresh. That's
+the whole "it's a real live app" proof.
+
+**Config (`WaitlistConfig`):**
+```ts
+BaseConfig & {
+  hero: { badge; headline; subcopy; emailPlaceholder; ctaLabel; successMessage };
+  counter: { enabled: boolean; label: string; seedCount?: number };
+  valueProps: { eyebrow; headline; items: { title; body; icon? }[] };
+  socialProof?: { label; logos?: string[]; quotes?: { quote; name; role }[] };
+  faq?: { eyebrow; headline; items: { q; a }[] };
+}
+```
+
+**Backend (`app.ts`):**
+```ts
+Signup = entity("Signup", {
+  email: field.string().unique(),   // unique → dedupe
+  createdAt: field.datetime(),
+}, { indexes: [{ name: "by_email", fields: ["email"], unique: true }] });
+```
+- `joinWaitlist({ email })` — public action: validate + lowercase + dedupe +
+  rate-limit, insert. Returns `{ ok, alreadyJoined? }`. Never returns other rows.
+- `waitlistCount()` — query returning `count(Signup)`; the page live-subscribes
+  so the number updates on every insert.
+- **Privacy:** `Signup` policy denies ALL client read/write (like
+  `cliAuthCodePolicy`). The page only ever sees the count, never emails.
+
+**Dashboard:** total signups, signups-over-time chart, searchable list, CSV
+export.
+
+---
+
+# 2. `local-service` — appointment businesses (booking)  ★ build second
+
+**Who:** salon, barber, trades (plumber/electrician/cleaner), trainer, clinic,
+studio, tutor — anyone who sells time slots.
+
+**Sections:**
+1. Hero — business name, tagline, **"Book now"** CTA, hero image, quick facts
+   (hours / area / phone).
+2. Services + prices — list/grid: name, duration, price.
+3. **Booking** — pick service → pick a time from **live availability** → name /
+   email / phone → confirm.
+4. Reviews.
+5. Hours + location — address, map embed, hours, contact.
+6. Gallery — optional.
+7. FAQ — optional. Footer.
+
+**Realtime feature:** live slot availability. The time picker subscribes to the
+day's bookings; the moment someone books a slot it greys out for everyone else —
+no double-booking. Server also re-checks at insert time to close the race.
+
+**Config (`LocalServiceConfig`):**
+```ts
+BaseConfig & {
+  hero: { tagline; headline; subcopy; ctaLabel; heroImage?;
+          quickFacts: { hours; area; phone } };
+  services: { eyebrow; headline;
+              items: { slug; name; durationMin; price; description? }[] };
+  booking: { enabled; headline; slotMinutes;       // e.g. 30
+             hours: { [day in 0..6]: { open; close } | null };  // weekly
+             leadTimeHours?; confirmationMessage };
+  reviews?: { eyebrow; headline; items: { quote; name; rating? }[] };
+  location: { address; mapEmbedUrl?; hoursText; phone; email };
+  gallery?: { images: string[] };
+  faq?: { eyebrow; headline; items: { q; a }[] };
+}
+```
+
+**Backend (`app.ts`):**
+```ts
+Service = entity("Service", {
+  slug; name; durationMin: field.int(); priceCents: field.int();
+  description: field.string().optional(); active: field.bool();
+});
+Booking = entity("Booking", {
+  serviceId: field.id("Service");
+  startsAt: field.datetime(); endsAt: field.datetime();
+  customerName; customerEmail; customerPhone: field.string().optional();
+  status: field.string();   // "confirmed" | "cancelled"
+  createdAt: field.datetime();
+}, { indexes: [{ name: "by_start", fields: ["startsAt"] }] });
+```
+- `createBooking({ serviceId, startsAt, customer })` — public action: server-side
+  re-check that the slot is still free (overlap query) before insert, to close
+  the race the live UI already mostly prevents.
+- `bookedSlotsForRange({ from, to })` — query returning only `{ startsAt, endsAt }`
+  (NO customer fields); the picker subscribes and computes free slots = hours −
+  booked. **Privacy:** `Booking` denies client read of full rows; only this
+  PII-stripped projection is exposed. `Service` is public-read (it's menu data).
+
+**Dashboard:** day/week calendar of bookings, confirm/cancel, manage services +
+weekly hours.
+
+---
+
+# 3. `saas` — app / tool / digital product  (≈ the current default, renamed)
+
+**Who:** software founders ("I'm building an app").
+**Sections:** hero + dashboard preview, logo cloud, feature sections
+(products), pricing tiers, testimonials, FAQ. (Already built — this is the
+refactored `default` template; rename `default` → `saas`, keep `default` as an
+alias.)
+**Realtime feature:** the live dashboard behind "Open dashboard" (the workspace
+itself).
+**Config:** the existing `SiteConfig` (`lib/site.config.ts`).
+
+---
+
+# 4. `restaurant` — food & hospitality
+
+**Who:** restaurant, cafe, bar, food truck, bakery.
+**Sections:** hero (name + "Reserve" / "Order"), **menu** (sections → items with
+price/description), hours + location + map, reservations or order-ahead, gallery,
+reviews, footer.
+**Realtime feature:** live table/reservation availability (same engine as
+local-service booking) OR live order-ahead status board.
+**Config highlights:** `menu: { sections: { name; items: { name; price; desc?;
+tags? }[] }[] }`, `reservations` (reuse booking shape), `location`, `hours`.
+**Entities:** `MenuItem` (public read), `Reservation` (PII-private, like
+`Booking`).
+
+---
+
+# 5. `shop` — DTC product / small store
+
+**Who:** product brands, makers, single-product or small-catalog sellers.
+**Sections:** hero, featured products / product grid, value props, reviews,
+shipping & returns, footer; cart.
+**Realtime feature:** live inventory (stock count updates as orders land) + live
+cart count.
+**Config highlights:** `products: { items: { slug; name; priceCents; image;
+description; stock? }[] }`, `valueProps`, `policies` (shipping/returns text).
+**Entities:** `Product` (public read, live stock), `Order` (PII-private; cart
+lines share an `orderGroupId`).
+**Checkout:** real **Stripe Checkout** via `@pylonsync/stripe`'s `stripeRequest`
++ `verifyStripeSignature` (one-time `price_data` line items; signed webhook at
+`/api/webhooks/stripeWebhook` settles paid / releases held stock on expiry).
+Stock is held under a per-product advisory lock at checkout so the cart can't
+oversell. **Graceful degradation:** with no `STRIPE_SECRET_KEY` the order is held
+as `reserved` for the owner to follow up — the store boots and demos live
+inventory with zero config.
+
+---
+
+# 6. `creator` — personal brand / coach / consultant
+
+**Who:** solo creators, coaches, consultants, freelancers, newsletter authors.
+**Sections:** hero (you), about, offerings/services, portfolio or testimonials,
+**lead magnet / newsletter signup**, book-a-call, links, footer.
+**Realtime feature:** live newsletter signup count (reuse the `waitlist`
+`Signup` + counter) and/or live call-booking availability (reuse `local-service`
+booking).
+**Config highlights:** `profile: { name; tagline; photo; bio }`, `offerings`,
+`portfolio?`, `newsletter` (reuse waitlist counter), `booking?` (reuse
+local-service).
+**Entities:** `Signup` and/or `Booking`, reused from the other archetypes.
+
+---
+
+# 7. `agency` — design / dev / marketing studio
+
+**Who:** boutique product/design/dev/marketing studios that take on a limited
+number of clients at once.
+**Sections:** hero (+ live availability pill), logo cloud, services, **work /
+case-study grid** (marked project-shot placeholders), process, **team** (marked
+headshot placeholders), testimonials, **project inquiry form** (#contact), footer.
+**Realtime feature:** scarcity — a public `Capacity` row holds the booking window
++ open project slots; the hero pill (`db.useQuery("Capacity")`) shows "N slots
+open" live, and the owner booking a lead from the dashboard decrements it for
+everyone instantly (same shape as `shop` inventory).
+**Config highlights:** `hero`, `capacity: { label; openSlots }` (seed), `logos`,
+`services`, `work: CaseStudy[]`, `process`, `team: TeamMember[]`, `testimonials?`,
+`contact: { projectTypes[]; budgets[]; confirmationMessage }`.
+**Entities:** `Inquiry` (PII deny-all: name/email/company/budget/message + status),
+`Capacity` (public-read single row, live openSlots), `User`.
+**Placeholders:** hero photo, each case-study project shot, each team headshot —
+all clearly marked via the shared `ImagePlaceholder`.
+
+---
+
+# 8. `marketplace` — two-sided buy/sell platform  (ported from examples/market)
+
+**Who:** local/vertical marketplaces, classifieds, gear resale, any buyer↔seller
+platform.
+**Sections:** SSR browse grid + category facets (`/`), listing detail (`/listing/:slug`),
+sell form (`/sell`, sign-in gated), per-user inbox (`/me`).
+**Realtime feature:** a live "just listed" ticker + live offers on a listing +
+your `/me` inbox, all via `db.useQuery` over public `Listing`/`Offer` (and
+private `Watch`). List in one tab → it appears in another instantly.
+**Entities:** `User`, `Listing` (`sellerId: field.owner()`, slug, price,
+category, condition, status, seed-gradient photo), `Offer` (`buyerId:
+field.owner()`, amount, status), `Watch` (private). Public-read listings/offers,
+owner-scoped writes; accept-marks-sold-and-declines-siblings in
+`respondToOffer`. **Multi-user** (email/password, no single owner) — unlike the
+single-tenant archetypes above.
+**Note:** ported from `examples/market` (not config-driven — rebrand in
+`app/layout.tsx` + `functions/seedMarket.ts`). Listing photos are generated
+gradients; swap for real `<img>` + `/api/files` upload for production.
+
+---
+
+# 9. `directory` — curated, searchable listing site
+
+**Who:** "best X" lists, tool/company/local directories, awesome-lists with a UI.
+**Sections:** hero + a live faceted-search browse (`#browse`), a `/submit` page,
+a `/dashboard` moderation queue.
+**Realtime feature:** the showcase for Pylon **FTS + facets** — `db.useSearch`
+re-runs on every keystroke AND on every write, so it doubles as the live layer;
+public `upvote` bumps `Listing.votes` and the count ticks up across all tabs.
+**Entities:** `Listing` (public-read, no PII; `search: { text, facets, sortable }`
+→ FTS5 + facet shadow tables) + `Submission` (deny-all PII: submitter
+name/email + proposed entry, status) + `User`. submitListing/upvote public;
+submissionsForOwner/approveSubmission/rejectSubmission owner-gated;
+approveSubmission copies ONLY public fields into a Listing (PII never published).
+**Key API:** `db.useSearch<T>(entity, { query, filters, facets, sort:[field,dir],
+page, pageSize })` → `{ hits, facetCounts, total, loading }` (reference:
+examples/store/client/Catalog.tsx).
+
+---
+
+# 10. `ai-chat` — streaming AI assistant
+
+**Who:** any LLM chat product / internal assistant.
+**Sections:** a full-screen chat — conversation sidebar + streaming thread +
+composer (`/`), optional `/login`.
+**Realtime feature:** token streaming from the built-in `POST /api/ai/stream`
+(SSE; the API key never leaves the server), PLUS owner-scoped `Conversation` +
+`Message` synced across the user's tabs via `db.useQuery`.
+**Entities:** `Conversation` + `Message` (both `userId: field.owner()`,
+owner-scoped read/write — private per user; messages written with optimistic
+`db.insert`, no custom functions) + `User`. Multi-user (guest or signed-in).
+**Config:** `PYLON_AI_PROVIDER` + `PYLON_AI_API_KEY` + `PYLON_AI_MODEL` enable
+replies; without them the app boots and shows a friendly "configure AI" notice.
+**SSE contract:** `data: {"choices":[{"delta":{"content":"…"}}]}` … `data:
+[DONE]`; 503 `AI_NOT_CONFIGURED` / 429 `RATE_LIMITED` shims handled in the client.
+
+---
+
+# 11. `ai-studio` — generative media studio (image / audio / video)
+
+**Who:** AI image/audio/video generators, creative tools.
+**Sections:** a prompt bar + medium selector over a live gallery (`/`), optional
+`/login`.
+**Realtime feature:** the generation gallery — the `generate` action inserts a
+`pending` Generation (card appears instantly), runs the provider call
+server-side, then flips the row to `done`/`failed`; `db.useQuery` syncs that to
+every open tab so the card updates live.
+**Entities:** `Generation` (owner-scoped READ, `allowInsert:"false"` — only the
+server pipeline writes it) + `User`. Multi-user (guest or signed-in).
+**Functions:** `generate` (public action) brackets the provider call with
+internal `_createGeneration` / `_finishGeneration` mutations. Image → OpenAI
+Images, audio → OpenAI TTS (both when `OPENAI_API_KEY` is set), video → a labeled
+extension point. **No key → a clearly-labeled placeholder** (SVG for image) so
+the flow + gallery work with zero config. Key + media stay server-side.
+**Note:** image uses the provider's hosted URL (small to sync, ~1h TTL);
+persist via `/api/files` for permanence. lib/studio.ts holds the placeholder gen.
+
+---
+
+## Build order
+1. **`waitlist`** — smallest, proves the whole pipeline, already the dogfood
+   target. (`Signup` + counter + `joinWaitlist`.)
+2. **`local-service`** — biggest SMB market; booking is the strongest realtime
+   demo. (`Service` + `Booking` + live availability.)
+3. **`saas`** — rename/finish the refactored default.
+4. **`restaurant`**, **`shop`**, **`creator`** — breadth; each heavily reuses the
+   `booking`/`signup` engines above, so they're mostly config + a couple of
+   bespoke sections.
+
+## Reuse map (so 6 archetypes aren't 6 from-scratch builds)
+- `Signup` + live counter → waitlist, creator (newsletter).
+- `Booking` + live availability → local-service, restaurant (reservations),
+  creator (call booking).
+- `Product` grid + inventory → shop.
+- Marketing component kit + BaseConfig → all.
+Two real backend engines (signup, booking) + one (product) cover every archetype.

package/templates/agency/.env.example

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

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

@@ -0,0 +1,90 @@
+# __APP_NAME__
+
+A studio / agency site built with [Pylon](https://pylonsync.com) — a
+server-rendered marketing page with **live availability**, a private project
+inquiry form, and an owner dashboard, all from one binary on one port. No
+Next.js, no separate API server.
+
+The realtime point: boutique studios take on a few projects at a time. The hero
+shows how many slots are open this quarter, and the moment the owner books a new
+client from the dashboard, that number drops for everyone with the page open.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321. Then **open a second tab**, sign in as the owner
+(see below), book a lead from the dashboard, and watch the "N slots open" pill on
+the public page tick down — with no refresh.
+
+## How the realtime works
+
+- `Capacity` is a public-read, PII-free row holding the booking window + open
+  slot count. `app/contact-form.tsx` reads it with `db.useQuery("Capacity")`, so
+  the hero's "N project slots open" pill is live everywhere.
+- `functions/submitInquiry.ts` is a public **mutation** — anyone can send a
+  project lead. It does NOT consume a slot (a lead isn't a booking).
+- `functions/bookInquiry.ts` / `declineInquiry.ts` are owner-only mutations that
+  mark a lead booked/declined AND adjust `Capacity.openSlots` (under an advisory
+  lock), so the public counter moves live.
+- `functions/seedCapacity.ts` creates the Capacity row from config on first
+  visit (idempotent).
+
+## Privacy — read this
+
+The `Inquiry` entity holds the prospect's name, email, company, and budget (PII),
+so its policy in `app.ts` **denies every client read and write**. The public page
+only reads `Capacity` (a label + a number). Inquiries come back only through
+`inquiriesForOwner`, gated to the owner server-side — the contact details never
+travel over entity sync.
+
+## The owner dashboard
+
+`/dashboard` is the pipeline: every lead (with its details), Book / Decline /
+Release actions, and a live availability editor (set the booking window + open
+slots). It updates live as leads land.
+
+Set `PYLON_OWNER_EMAIL` in `.env` (see `.env.example`) to the email you'll sign
+in with, then create that account at `/login`.
+
+## Placeholders to replace
+
+The page renders **clearly marked** placeholders anywhere a real photo belongs —
+swap each for an `<img>` when you have the asset:
+
+- the hero photo ("A photo of your studio or work")
+- each case study's project shot (the `#work` grid)
+- each team member's headshot
+
+The logo cloud uses sample names — replace with your real client logos.
+
+## Rebrand it
+
+Everything lives in **`lib/site.config.ts`** — brand, colors, hero, services,
+case studies, process, team, testimonials, and the contact form's project-type
+and budget options. Edit that one file (or have Mast generate it) and the whole
+studio re-themes; the capacity re-seeds on a fresh database.
+
+## Layout
+
+```
+app.ts                        Inquiry (PII) + Capacity (public, live) + User
+lib/site.config.ts            ALL copy + brand + work/team/services (edit this)
+functions/seedCapacity.ts     idempotent capacity seed from config
+functions/submitInquiry.ts    public mutation: write a lead (PII), no slot change
+functions/inquiriesForOwner.ts  owner-only query: leads + PII
+functions/{book,decline}Inquiry.ts, setCapacity.ts  owner-only mutations
+app/page.tsx                  the studio site (server-rendered)
+app/contact-form.tsx          client island: live slots pill + inquiry form
+app/dashboard/                owner dashboard (auth-gated, live)
+```
+
+## Deploy
+
+```bash
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com