@pylonsync/create-pylon 0.3.332 → 0.3.334

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.332",
+  "version": "0.3.334",
   "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

@@ -1,26 +1,25 @@
 # 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.
+Mast selects one of these `create-pylon` templates when it builds a site for a
+new business. Each template includes a landing page, dashboard, and live
+backend. Mast maps the business description to a template 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.
+
+- **Each archetype defines a section structure and one realtime feature.** The
+  generated site includes a working backend, and every template exposes one
+  live interaction.
 - **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.
+- **Customization happens in one `site.config.ts`.** Archetypes with lists,
+  such as services or menus, may also include seed rows. This matches the
+  default template's contract.
 - **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.
+  visitor PII (emails, phones) must deny client reads. Writes go through a
+  server action. Pages may expose aggregates such as counts or non-PII fields
+  such as busy time slots, but never customer emails.
 
 ## Shared config base
 ```ts
@@ -40,27 +39,26 @@ Input: the business description. Output:
   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.
+Use `waitlist` for ambiguous or pre-revenue businesses. Use the matching
+archetype for a known operating business.
 
 ---
 
-# 1. `waitlist` — pre-launch / coming-soon  ★ build first (dogfood target)
+# 1. `waitlist`: pre-launch or coming soon
 
 **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
+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.
+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.
+**Realtime feature:** the signup counter updates on every open page. Submit in
+one tab and the other increments without a refresh.
 
 **Config (`WaitlistConfig`):**
 ```ts
@@ -80,9 +78,9 @@ Signup = entity("Signup", {
   createdAt: field.datetime(),
 }, { indexes: [{ name: "by_email", fields: ["email"], unique: true }] });
 ```
-- `joinWaitlist({ email })` — public action: validate + lowercase + dedupe +
+- `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
+- `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.
@@ -92,25 +90,25 @@ export.
 
 ---
 
-# 2. `local-service` — appointment businesses (booking)  ★ build second
+# 2. `local-service`: appointment businesses
 
 **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
+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 /
+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.
+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.
+day's bookings, so a booked slot greys out for everyone else. The server also
+rechecks availability at insert time to prevent a race.
 
 **Config (`LocalServiceConfig`):**
 ```ts
@@ -143,10 +141,10 @@ Booking = entity("Booking", {
   createdAt: field.datetime();
 }, { indexes: [{ name: "by_start", fields: ["startsAt"] }] });
 ```
-- `createBooking({ serviceId, startsAt, customer })` — public action: server-side
+- `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 }`
+- `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).
@@ -156,11 +154,11 @@ weekly hours.
 
 ---
 
-# 3. `saas` — app / tool / digital product  (≈ the current default, renamed)
+# 3. `saas`: app, tool, or digital product
 
 **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
+(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
@@ -169,7 +167,7 @@ itself).
 
 ---
 
-# 4. `restaurant` — food & hospitality
+# 4. `restaurant`: food and hospitality
 
 **Who:** restaurant, cafe, bar, food truck, bakery.
 **Sections:** hero (name + "Reserve" / "Order"), **menu** (sections → items with
@@ -184,7 +182,7 @@ tags? }[] }[] }`, `reservations` (reuse booking shape), `location`, `hours`.
 
 ---
 
-# 5. `shop` — DTC product / small store
+# 5. `shop`: DTC product or small store
 
 **Who:** product brands, makers, single-product or small-catalog sellers.
 **Sections:** hero, featured products / product grid, value props, reviews,
@@ -198,14 +196,13 @@ 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.
+Stock is held under a per-product advisory lock at checkout so the cart cannot
+oversell. Without `STRIPE_SECRET_KEY`, the order remains `reserved` for the
+owner to follow up. This keeps the live-inventory demo usable without Stripe.
 
 ---
 
-# 6. `creator` — personal brand / coach / consultant
+# 6. `creator`: personal brand, coach, or consultant
 
 **Who:** solo creators, coaches, consultants, freelancers, newsletter authors.
 **Sections:** hero (you), about, offerings/services, portfolio or testimonials,
@@ -220,14 +217,14 @@ local-service).
 
 ---
 
-# 7. `agency` — design / dev / marketing studio
+# 7. `agency`: design, development, or 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
+**Realtime feature:** 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).
@@ -236,12 +233,12 @@ everyone instantly (same shape as `shop` inventory).
 `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`.
+**Placeholders:** the hero photo, each case-study project shot, and each team
+headshot use the shared `ImagePlaceholder`.
 
 ---
 
-# 8. `marketplace` — two-sided buy/sell platform  (ported from examples/market)
+# 8. `marketplace`: two-sided buy and sell platform
 
 **Who:** local/vertical marketplaces, classifieds, gear resale, any buyer↔seller
 platform.
@@ -254,20 +251,20 @@ private `Watch`). List in one tab → it appears in another instantly.
 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
+`respondToOffer`. It is multi-user through email/password, unlike the
+single-owner archetypes above.
+**Note:** ported from `examples/market`. Rebrand it in
+`app/layout.tsx` and `functions/seedMarket.ts`. Listing photos are generated
 gradients; swap for real `<img>` + `/api/files` upload for production.
 
 ---
 
-# 9. `directory` — curated, searchable listing site
+# 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`
+**Realtime feature:** Pylon FTS and 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 }`
@@ -281,16 +278,16 @@ examples/store/client/Catalog.tsx).
 
 ---
 
-# 10. `ai-chat` — streaming AI assistant
+# 10. `ai-chat`: streaming AI assistant
 
 **Who:** any LLM chat product / internal assistant.
-**Sections:** a full-screen chat — conversation sidebar + streaming thread +
+**Sections:** a full-screen chat with a 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
+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.
@@ -299,34 +296,35 @@ replies; without them the app boots and shows a friendly "configure AI" notice.
 
 ---
 
-# 11. `ai-studio` — generative media studio (image / audio / video)
+# 11. `ai-studio`: generative media studio
 
 **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
+**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
+**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.
+internal `_createGeneration` / `_finishGeneration` mutations. Image uses OpenAI
+Images, audio uses OpenAI TTS when `OPENAI_API_KEY` is set, and video is a
+labeled extension point. Without a key, the app returns a clearly labeled
+placeholder so the flow and gallery remain testable. Keys and 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
+1. **`waitlist`:** smallest template and current dogfood target (`Signup`,
+   counter, and `joinWaitlist`).
+2. **`local-service`:** booking template with `Service`, `Booking`, and live
+   availability.
+3. **`saas`:** rename and finish the refactored default.
+4. **`restaurant`**, **`shop`**, **`creator`:** each heavily reuses the
    `booking`/`signup` engines above, so they're mostly config + a couple of
    bespoke sections.
 
@@ -336,4 +334,4 @@ persist via `/api/files` for permanence. lib/studio.ts holds the placeholder gen
   creator (call booking).
 - `Product` grid + inventory → shop.
 - Marketing component kit + BaseConfig → all.
-Two real backend engines (signup, booking) + one (product) cover every archetype.
+The signup, booking, and product engines cover every archetype above.

package/templates/_root/AGENTS.md

@@ -1,35 +1,35 @@
-# AGENTS.md — working in a Pylon project
+# AGENTS.md: working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. You — the agent — are a first-class user of Pylon: one Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one process on one port, so you build, run, and ship a whole app without wiring services together or leaving the codebase. This is production infrastructure, not a sandbox — real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploy — so build like it ships. You declare entities, policies, and server functions in TypeScript; the binary does the rest. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt — read it before guessing an API name.
+Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one Rust process on one port. Treat this app as production infrastructure: it supports real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploys. Declare entities, policies, and server functions in TypeScript; the binary handles the runtime. Read the full API reference at https://docs.pylonsync.com/llms-full.txt 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.
+- `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 development 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.
+**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 them.
 
 ## 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>`.
+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. `pylon lint` flags wide-open development policies such as `allow*: "true"`; tighten them 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.
+- **Policies deny by default; server functions bypass them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full database access, so enforce trust with `ctx.auth` checks inside the handler.
 - **`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`.
+- **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` or `<Suspense>`. The HTTP head commits when the shell is ready. Status, headers, and cookies set from a suspended subtree are lost, and `redirect` or `notFound` thrown below a Suspense boundary are swallowed.
+- **`ctx.llm` and `ctx.connections` are available on mutations and actions, not queries.** An `action` has no direct `ctx.db`; use `ctx.runQuery` or `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
+## Use the CLI
 
 | Need | Command |
 |---|---|

package/templates/_root/README.md

@@ -25,10 +25,10 @@ bun install   # or pnpm install / yarn / npm install
 bun run dev
 ```
 
-- **api** on http://localhost:4321 — Pylon control plane
-- **web** on http://localhost:3000 — Next.js (if scaffolded)
+- **api:** http://localhost:4321, Pylon control plane
+- **web:** http://localhost:3000, Next.js (if scaffolded)
 - **expo** runs Metro on a separate port (if scaffolded)
-- **mobile** lives in `apps/mobile/` — open in Xcode or run `swift run`
+- **mobile** lives in `apps/mobile/`; open it in Xcode or run `swift run`
 
 ## What to do next
 

package/templates/agency/AGENTS.md

@@ -1,47 +1,47 @@
-# AGENTS.md — working in a Pylon project
+# AGENTS.md: working in a Pylon project
 
-Operating rules for a coding agent in this Pylon app. You — the agent — are a first-class user of Pylon: one Rust binary (`pylon`) serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one process on one port, so you build, run, and ship a whole app without wiring services together or leaving the codebase. This is production infrastructure, not a sandbox — real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploy — so build like it ships. You declare entities, policies, and server functions in TypeScript; the binary does the rest. The full API reference is the **llms-full.txt** at https://docs.pylonsync.com/llms-full.txt — read it before guessing an API name.
+Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one Rust process on one port. Treat this app as production infrastructure: it supports real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploys. Declare entities, policies, and server functions in TypeScript; the binary handles the runtime. Read the full API reference at https://docs.pylonsync.com/llms-full.txt 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.
+- `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.
+**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>`.
+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. `pylon lint` flags wide-open development policies such as `allow*: "true"`; tighten them 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.
+- **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 and conditional.** `export const revalidate = 60` makes a page CDN-cacheable (`public, s-maxage=60`) only when the render is auth-independent: it must not read `props.auth`, set a cookie, or run with strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. When any condition fails, the page is `no-cache`. Eligible renders also use the origin disk cache at `.pylon/.cache/ssr`: a cookie-less GET without a query string is served from disk for the TTL and rerendered when stale. The cache is namespaced per deploy, cleared by each build, disabled in `pylon dev`, and invalidated by the `revalidate` TTL or the next deploy.
+- **No-JS forms use `route.ts` and `<Form>`.** Add `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=...>`. It uses native POST → handler → redirect without JavaScript and no-reload enhancement with JavaScript. The handler's `db` is read+write under the mutation trust model, so gate it on `auth`. CSRF protection is automatic through the Origin gate and SameSite=Lax. Multipart uploads are not supported yet; use URL-encoded forms and `/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 inner `<Suspense>` boundaries.** Without it or a `loading.tsx`, the page is buffered until all suspended children resolve. With it, the shell and fallbacks flush immediately, then each boundary streams its content. Streaming commits the HTTP head before suspended subtrees finish, so the page is never CDN- or disk-cacheable; do not combine it with `export const revalidate`. Calls to `response.setStatus`, `setCookie`, `redirect`, or `notFound` only take effect during the synchronous shell render. A call from a suspended subtree is dropped and logged. An error from a deep `<Suspense>` child resolves through the nearest `error.tsx` at HTTP 200 rather than 5xx. 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`.
+- **`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 (one-shot) execution is `ctx.scheduler.runAfter/runAt/cancel`. Recurring work is a **cron**: `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })` (import `cron` from `@pylonsync/sdk`) — it fires the named function (make it `internal: true`) on the schedule; the function runs with anonymous auth — its own `ctx.db.*` is server-side (not policy-gated), so write directly; only `ctx.auth.elevate({ admin: true, reason: "..." })` (reason mandatory) to chain an `internal: true` function via `ctx.scheduler`.
+- **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; there is no `ctx.files`. One-shot work uses `ctx.scheduler.runAfter`, `runAt`, or `cancel`; there is no `defineWorkflow` or `defineJob`. Recurring work uses `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })`, imported from `@pylonsync/sdk`. Make the target function `internal: true`. It runs with anonymous auth, but its own `ctx.db.*` calls are server-side and bypass policies. Use `ctx.auth.elevate({ admin: true, reason: "..." })`, with a mandatory reason, only when chaining another internal function through `ctx.scheduler`.
 
 ## Testing
 
-`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/` — replace them with your own.
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/`; replace them with your own.
 
-**Tier 1 — pure logic (reach for this first).** Keep the decisions that matter — access/plan gating, pricing, credit math, validation, formatting — in pure functions in `lib/`, and test those exhaustively. No server, instant, and it's where the real bugs live. Keep your `query`/`mutation`/`action` handlers as thin wrappers around them, so the logic is testable without a running app.
+**Tier 1: pure logic (start here).** Keep access and plan gating, pricing, credit math, validation, and formatting in pure functions under `lib/`, and test them exhaustively. These tests need no server and run instantly. Keep `query`, `mutation`, and `action` handlers as thin wrappers so their decision logic remains testable without a running app.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -52,7 +52,7 @@ test("unknown slug → undefined", () => {
 });
 ```
 
-**Tier 2 — React components.** `@testing-library/react` + happy-dom are already wired (`tests/setup.ts`). Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, **mock the boundary**, then dynamic-`import` the component so the mock is in place first:
+**Tier 2: React components.** `@testing-library/react` and happy-dom are already wired through `tests/setup.ts`. Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, mock the boundary, then dynamically import the component so the mock is in place first:
 
 ```tsx
 import { test, expect, mock } from "bun:test";
@@ -70,7 +70,7 @@ test("renders orgs from the query", () => {
 });
 ```
 
-**Tier 3 — functions over HTTP (only when Tier 1 can't cover it).** A handler's full behavior (policies, `ctx.db`, auth) lives in the running app. Start `pylon dev` in another terminal and call the API; `resetDb()` from `@pylonsync/functions` clears the in-memory DB between cases (no-ops if the server's down, refuses production).
+**Tier 3: functions over HTTP.** Use this tier when pure logic tests cannot cover the behavior. A handler's policies, `ctx.db` calls, and auth run in the app. Start `pylon dev` in another terminal and call the API. `resetDb()` from `@pylonsync/functions` clears the in-memory database between cases; it does nothing when the server is down and refuses to run in production.
 
 ```ts
 import { afterEach, expect, test } from "bun:test";
@@ -90,9 +90,9 @@ test("createThing then read it back", async () => {
 });
 ```
 
-`pylon test:security` is a separate adversarial probe — it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+`pylon test:security` is a separate adversarial probe; it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
 
-## Use the CLI — don't guess
+## Use the CLI
 
 | Need | Command |
 |---|---|

package/templates/agency/CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md
 
-Agent guidance for this Pylon project lives in **AGENTS.md** — the cross-editor
-standard that Claude Code, Cursor, Codex, and others all read. It's imported
-below so Claude Code picks it up automatically:
+Agent guidance for this Pylon project lives in **AGENTS.md**, the cross-editor
+standard read by Claude Code, Cursor, Codex, and other agents. The import below
+makes it available to Claude Code:
 
 @AGENTS.md