@pylonsync/create-pylon 0.19.1 → 0.20.0

package/templates/agency/functions/seedStudioBackoffice.ts

@@ -2,17 +2,25 @@ import { mutation } from "@pylonsync/functions";
 import { emailMatchesOwner } from "../lib/owner";
 import { siteConfig } from "../lib/site.config";
 import { lineItemsTotal, slugify, type ProjectRow } from "../lib/agency";
+import { DEMO_INQUIRIES, daysAgoDate, demoDataEnabled } from "../lib/demo";
 
-// seedStudioBackoffice — owner-only, idempotent. Fills the dashboard's CRM +
-// billing with the demo clients/invoices from config so it isn't an empty shell
-// on first sign-in. Private data (PII + money) is only ever seeded for the
-// signed-in owner — never by an anonymous visitor — which is why this is
-// owner-gated, unlike the public seedProjects.
+// seedStudioBackoffice — owner-only, development-only, idempotent. Fills the
+// dashboard's pipeline, CRM, and billing with demo leads (lib/demo.ts) and the
+// demo clients/invoices from config, so the tabs are not empty on first
+// sign-in.
+//
+// It writes nothing unless demo data is on (lib/demo.ts: PYLON_DEMO_DATA, else
+// a `pylon dev` process), so `pylon start`, Docker, and Pylon Cloud deploys do
+// not get demo rows. Each table is seeded only while it is empty, so deleting
+// every lead in development seeds them again on the next load. Private data
+// (PII + money) is only ever seeded for the signed-in owner, never by an
+// anonymous visitor, which is why this is owner-gated, unlike the public
+// seedProjects.
 //
 // Invoices link to clients by name and to projects by slug; we resolve those to
-// ids here. Projects may already be seeded (the public site calls seedProjects);
-// if a project isn't present yet, the invoice still carries its title and just
-// doesn't deep-link.
+// ids here. Projects may already be seeded (the public site calls
+// seedProjects); if a project isn't present yet, the invoice still carries its
+// title and just doesn't deep-link.
 export default mutation<Record<string, never>, { seeded: boolean }>({
   auth: "user",
   async handler(ctx) {
@@ -21,9 +29,29 @@ export default mutation<Record<string, never>, { seeded: boolean }>({
       throw ctx.error("POLICY_DENIED", "Only the owner can seed the back-office.");
     }
 
+    if (!demoDataEnabled(ctx.env)) return { seeded: false };
+
     await ctx.db.advisoryLock("agency_seed_backoffice");
+    const nowMs = Date.now();
+
+    const existingInquiries = await ctx.db.unsafe.list("Inquiry");
+    if (existingInquiries.length === 0) {
+      for (const q of DEMO_INQUIRIES) {
+        await ctx.db.unsafe.insert("Inquiry", {
+          name: q.name,
+          email: q.email,
+          company: q.company,
+          projectType: q.projectType,
+          budget: q.budget,
+          message: q.message,
+          status: q.status,
+          createdAt: new Date(nowMs - q.hoursAgo * 3_600_000).toISOString(),
+        });
+      }
+    }
+
     const existingClients = await ctx.db.unsafe.list("Client");
-    if (existingClients.length > 0) return { seeded: false };
+    if (existingClients.length > 0) return { seeded: existingInquiries.length === 0 };
 
     const now = new Date().toISOString();
 
@@ -62,8 +90,11 @@ export default mutation<Record<string, never>, { seeded: boolean }>({
         lineItems: JSON.stringify(inv.lineItems),
         amountCents: lineItemsTotal(inv.lineItems),
         status: inv.status ?? "draft",
-        issuedAt: inv.issuedAt ?? null,
-        dueAt: inv.dueAt ?? null,
+        issuedAt: inv.issuedDaysAgo !== undefined ? daysAgoDate(inv.issuedDaysAgo, nowMs) : null,
+        dueAt:
+          inv.issuedDaysAgo !== undefined
+            ? daysAgoDate(inv.issuedDaysAgo - (inv.termsDays ?? 30), nowMs)
+            : null,
         notes: null,
         createdAt: now,
       });

package/templates/agency/lib/agency.ts

@@ -187,3 +187,25 @@ export function viewFromRow(r: ProjectRow): ProjectView {
     liveUrl: r.liveUrl,
   };
 }
+
+// The booking window the site names next to the open-slot count. An empty
+// label means the quarter a new project could start in: the quarter of the
+// date three weeks from today. It is never a past quarter, and in the last
+// three weeks of a quarter it names the next one. The owner can set a fixed
+// label ("January", "after the holidays") from the dashboard.
+const LEAD_DAYS = 21;
+export function quarterLabel(nowMs: number): string {
+  const d = new Date(nowMs);
+  return `Q${Math.floor(d.getMonth() / 3) + 1} ${d.getFullYear()}`;
+}
+
+export function bookingWindow(label: string | null | undefined, nowMs: number): string {
+  const fixed = (label ?? "").trim();
+  return fixed || quarterLabel(nowMs + LEAD_DAYS * 86_400_000);
+}
+
+// The work grid is two columns. With an odd number of case studies the first
+// one spans both columns, so the last row never holds a single card.
+export function isWideCard(index: number, count: number): boolean {
+  return count > 1 && count % 2 === 1 && index === 0;
+}

package/templates/agency/lib/demo.ts

@@ -0,0 +1,118 @@
+// Demo back-office data for local development.
+//
+// The owner's first dashboard load in `pylon dev` fills an empty studio with
+// fictional leads, clients, and invoices (functions/seedStudioBackoffice.ts),
+// so the pipeline, CRM, and billing tabs have rows. A deploy does not seed:
+// `demoDataEnabled` is true only when PYLON_DEMO_DATA is on, or when it is
+// unset and the process runs under `pylon dev`. Set PYLON_DEMO_DATA=0 to turn
+// it off in development too.
+//
+// The public portfolio (functions/seedProjects.ts) is different: it copies the
+// case studies from lib/site.config.ts, which is the studio's own content, so it
+// runs in every environment.
+
+const ON = new Set(["1", "true", "yes", "on"]);
+const OFF = new Set(["0", "false", "no", "off"]);
+
+/**
+ * True when demo rows may be written. An explicit PYLON_DEMO_DATA wins.
+ * Otherwise it needs both PYLON_DEV_MODE on and PYLON_DEV_WATCH_DIR set. Only
+ * `pylon dev` sets PYLON_DEV_WATCH_DIR; `pylon start` and the Docker image do
+ * not, and the image turns PYLON_DEV_MODE on by default, so dev mode alone is
+ * not proof of a local machine.
+ */
+export function demoDataEnabled(env: Record<string, string | undefined>): boolean {
+  const explicit = env.PYLON_DEMO_DATA?.trim().toLowerCase();
+  if (explicit && ON.has(explicit)) return true;
+  if (explicit && OFF.has(explicit)) return false;
+  const dev = env.PYLON_DEV_MODE?.trim().toLowerCase();
+  const devMode = dev === "1" || dev === "true";
+  return devMode && Boolean(env.PYLON_DEV_WATCH_DIR?.trim());
+}
+
+/** Local "YYYY-MM-DD" for `daysAgo` days before `nowMs` (negative = ahead). */
+export function daysAgoDate(daysAgo: number, nowMs: number): string {
+  const d = new Date(nowMs);
+  d.setDate(d.getDate() - daysAgo);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+export interface DemoInquiry {
+  name: string;
+  email: string;
+  company: string;
+  projectType: string;
+  budget: string;
+  message: string;
+  status: "new" | "booked" | "declined";
+  /** Hours before the seed runs. */
+  hoursAgo: number;
+}
+
+// Fictional leads. Project types and budgets use the contact form's options.
+export const DEMO_INQUIRIES: DemoInquiry[] = [
+  {
+    name: "Priya Raman",
+    email: "priya@fernhillvet.example",
+    company: "Fernhill Veterinary",
+    projectType: "New product (0→1)",
+    budget: "$50–100k",
+    message:
+      "We run six clinics and want an app for booking visits and refilling prescriptions. We have an API from our practice software. Hoping to launch in spring.",
+    status: "new",
+    hoursAgo: 3,
+  },
+  {
+    name: "Marcus Iyer",
+    email: "marcus@northwind.example",
+    company: "Northwind Logistics",
+    projectType: "Existing product",
+    budget: "$100k+",
+    message:
+      "Our dispatch team works out of spreadsheets. We need a web app for load planning with live driver locations. Two engineers in-house can take it over after launch.",
+    status: "new",
+    hoursAgo: 20,
+  },
+  {
+    name: "Lena Fischer",
+    email: "lena@beaconproperty.example",
+    company: "Beacon Property",
+    projectType: "Existing product",
+    budget: "$25–50k",
+    message:
+      "Three product teams, three sets of buttons. We want one component library in Figma and React, and help rolling it out.",
+    status: "new",
+    hoursAgo: 46,
+  },
+  {
+    name: "Ben Osei",
+    email: "ben@quarry.example",
+    company: "Quarry Design Co",
+    projectType: "Rebrand",
+    budget: "$25–50k",
+    message: "Looking for a partner to build our new marketing site in a headless CMS. Designs are about 70% done.",
+    status: "booked",
+    hoursAgo: 120,
+  },
+  {
+    name: "Tom Alvarez",
+    email: "tom@riverbed.example",
+    company: "Riverbed Coffee",
+    projectType: "New product (0→1)",
+    budget: "Let's talk",
+    message: "A loyalty app for our four cafes. Punch card, order ahead, and push offers.",
+    status: "declined",
+    hoursAgo: 200,
+  },
+  {
+    name: "Simone Clarke",
+    email: "simone@atlasfitness.example",
+    company: "Atlas Fitness",
+    projectType: "New product (0→1)",
+    budget: "$50–100k",
+    message:
+      "Members book classes through a third-party tool that charges per booking. We want our own booking and billing, with a coach view for check-ins.",
+    status: "new",
+    hoursAgo: 70,
+  },
+];

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

@@ -68,8 +68,10 @@ export type InvoiceSeed = {
   // Line items drive the total — `amountCents` is computed from them on seed.
   lineItems: { description: string; quantity: number; unitCents: number }[];
   status?: "draft" | "sent" | "paid" | "overdue";
-  issuedAt?: string; // "2026-04-01"
-  dueAt?: string;
+  // Days before the seed runs, so demo invoices stay current: an invoice
+  // issued 12 days ago with 30-day terms is always "due in 18 days".
+  issuedDaysAgo?: number;
+  termsDays?: number;
 };
 
 // The studio's billing identity — the "from" block + terms on every invoice and
@@ -89,7 +91,8 @@ export type AgencyConfig = BaseConfig & {
   };
   // Seeds the public Capacity row on first visit; after that it lives in the DB
   // and the owner manages it from the dashboard. `openSlots` is the number the
-  // hero shows live; `label` is the booking window it refers to.
+  // hero shows live; `label` is the booking window it refers to ("" = the
+  // next bookable quarter).
   capacity: { label: string; openSlots: number };
   services: { headline: string; items: Service[] };
   work: { headline: string; items: CaseStudy[] };
@@ -151,7 +154,10 @@ export const siteConfig: AgencyConfig = {
     secondaryCtaLabel: "See our work",
   },
 
-  capacity: { label: "Q3 2026", openSlots: 3 },
+  // `label` empty = the quarter a new project could start in, worked out from
+  // today's date (lib/agency.ts → bookingWindow). Set a fixed label only for a window with a
+  // real end date.
+  capacity: { label: "", openSlots: 3 },
 
   services: {
     headline: "What we do",
@@ -283,8 +289,8 @@ export const siteConfig: AgencyConfig = {
           { description: "Product design & iOS build — Ledger (12-week engagement)", quantity: 1, unitCents: 4800000 },
         ],
         status: "paid",
-        issuedAt: "2026-01-15",
-        dueAt: "2026-02-14",
+        issuedDaysAgo: 240,
+        termsDays: 30,
       },
       {
         number: "INV-002",
@@ -295,19 +301,19 @@ export const siteConfig: AgencyConfig = {
           { description: "Discovery & scoping sprint", quantity: 1, unitCents: 700000 },
         ],
         status: "paid",
-        issuedAt: "2026-03-01",
-        dueAt: "2026-03-31",
+        issuedDaysAgo: 150,
+        termsDays: 30,
       },
       {
         number: "INV-003",
         client: "Tom Reyes",
         projectSlug: "atlas-health",
         lineItems: [
-          { description: "Maintenance retainer — June", quantity: 1, unitCents: 850000 },
+          { description: "Monthly maintenance retainer", quantity: 1, unitCents: 850000 },
         ],
         status: "sent",
-        issuedAt: "2026-06-01",
-        dueAt: "2026-07-01",
+        issuedDaysAgo: 12,
+        termsDays: 30,
       },
       {
         number: "INV-004",
@@ -318,8 +324,8 @@ export const siteConfig: AgencyConfig = {
           { description: "Marketing site design & build", quantity: 1, unitCents: 1000000 },
         ],
         status: "overdue",
-        issuedAt: "2026-04-10",
-        dueAt: "2026-05-10",
+        issuedDaysAgo: 64,
+        termsDays: 30,
       },
     ],
   },

package/templates/agency/tests/agency.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { bookingWindow, isWideCard, quarterLabel } from "../lib/agency";
+import { DEMO_INQUIRIES, daysAgoDate, demoDataEnabled } from "../lib/demo";
+import { siteConfig } from "../lib/site.config";
+
+describe("booking window", () => {
+  test("an empty label means the quarter a project could start in", () => {
+    expect(quarterLabel(new Date(2026, 8, 26).getTime())).toBe("Q3 2026");
+    expect(quarterLabel(new Date(2026, 9, 1).getTime())).toBe("Q4 2026");
+    expect(bookingWindow("", new Date(2027, 0, 5).getTime())).toBe("Q1 2027");
+    expect(bookingWindow("  ", new Date(2027, 0, 5).getTime())).toBe("Q1 2027");
+    // Three weeks from the end of a quarter, the window moves to the next one.
+    expect(bookingWindow("", new Date(2026, 8, 5).getTime())).toBe("Q3 2026");
+    expect(bookingWindow("", new Date(2026, 8, 26).getTime())).toBe("Q4 2026");
+    expect(bookingWindow("", new Date(2026, 11, 20).getTime())).toBe("Q1 2027");
+  });
+  test("a fixed label wins", () => {
+    expect(bookingWindow("January", Date.now())).toBe("January");
+  });
+  test("the shipped config does not pin a quarter", () => {
+    expect(siteConfig.capacity.label).toBe("");
+  });
+});
+
+describe("work grid", () => {
+  test("an odd count widens the first card so no card sits alone on the last row", () => {
+    expect([0, 1, 2].map((i) => isWideCard(i, 3))).toEqual([true, false, false]);
+    expect([0, 1, 2, 3].map((i) => isWideCard(i, 4))).toEqual([false, false, false, false]);
+    expect(isWideCard(0, 1)).toBe(false);
+  });
+  test("the shipped homepage has three selected case studies, so the rule applies", () => {
+    expect(siteConfig.work.items.filter((w) => w.selected).length % 2).toBe(1);
+  });
+});
+
+describe("demo data", () => {
+  test("only under `pylon dev` unless PYLON_DEMO_DATA says otherwise", () => {
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "1", PYLON_DEV_WATCH_DIR: "/src/app" })).toBe(true);
+    // The Docker base image turns dev mode on by default; without `pylon dev` it must not seed.
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "true" })).toBe(false);
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "false" })).toBe(false);
+    expect(demoDataEnabled({})).toBe(false);
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "1", PYLON_DEV_WATCH_DIR: "/src/app", PYLON_DEMO_DATA: "0" })).toBe(false);
+  });
+  test("demo leads use the contact form's own options", () => {
+    for (const q of DEMO_INQUIRIES) {
+      expect(siteConfig.contact.projectTypes).toContain(q.projectType);
+      expect(siteConfig.contact.budgets).toContain(q.budget);
+    }
+  });
+  test("demo invoice dates are relative to today", () => {
+    const now = new Date(2026, 8, 26).getTime();
+    expect(daysAgoDate(12, now)).toBe("2026-09-14");
+    expect(daysAgoDate(-18, now)).toBe("2026-10-14");
+    for (const inv of siteConfig.backoffice.invoices) expect(inv.issuedDaysAgo).toBeGreaterThan(0);
+  });
+});

package/templates/ai-chat/.env.example

@@ -1,33 +1,19 @@
 # Copy to `.env` and fill in. `pylon dev` loads `.env` automatically.
 #
-# The app boots with no config — you can sign in and create chats — but the
-# assistant can't reply until you point it at an LLM provider. Streaming runs
-# through the built-in POST /api/ai/stream endpoint, so your API key stays on
-# the server and never reaches the browser.
+# The app runs with no config: visitors can chat as guests and messages are
+# saved. Replies need a model provider key. The key stays on the server.
 
-# ── AI provider (required for the assistant to reply) ────────────────────────
-#   PYLON_AI_PROVIDER   "anthropic" | "openai" | "custom"
-#   PYLON_AI_API_KEY    your provider key (sk-… / sk-ant-…)
-#   PYLON_AI_MODEL      the default model used when none is selected
-# PYLON_AI_PROVIDER=anthropic
-# PYLON_AI_API_KEY=sk-ant-...
-# PYLON_AI_MODEL=claude-sonnet-4-6
+# Model provider (required for replies)
+#   PYLON_LLM_PROVIDER   "anthropic" | "openai"
+#   ANTHROPIC_API_KEY    or OPENAI_API_KEY
+# PYLON_LLM_PROVIDER=anthropic
+# ANTHROPIC_API_KEY=sk-ant-...
 
-# ── Model switching ──────────────────────────────────────────────────────────
-# The chat's model picker (lib/site.config.ts → chat.models) sends a `model` per
-# request. For security, client-chosen models must be allow-listed here
-# (comma-separated) — otherwise the override is refused and the chat shows a
-# notice. List exactly the model ids you expose in the picker:
-# PYLON_AI_MODELS_ALLOWED=claude-sonnet-4-6,claude-opus-4-8,claude-haiku-4-5
+# OpenAI-compatible gateway (optional), such as OpenRouter:
+#   PYLON_LLM_PROVIDER=openai
+#   PYLON_LLM_BASE_URL=https://openrouter.ai/api
+#   OPENAI_API_KEY=<gateway key>
+# Then list the gateway's model ids in lib/site.config.ts (chat.models).
 
-# ── Multiple PROVIDERS in one picker (optional) ──────────────────────────────
-# /api/ai/stream talks to ONE provider. To offer Anthropic + OpenAI + others in
-# the same picker, route through an OpenAI-compatible gateway like OpenRouter:
-#   PYLON_AI_PROVIDER=custom
-#   PYLON_AI_BASE_URL=https://openrouter.ai/api/v1
-#   PYLON_AI_API_KEY=<openrouter key>
-# then set chat.models (config) + PYLON_AI_MODELS_ALLOWED to that gateway's slugs
-# (e.g. anthropic/claude-sonnet-4, openai/gpt-4o, google/gemini-2.5-pro).
-
-# ── Site URL (optional) ──────────────────────────────────────────────────────
+# Site URL (optional)
 # SITE_URL=https://yourchat.com

package/templates/ai-chat/README.md

@@ -1,11 +1,9 @@
 # __APP_NAME__
 
-A streaming AI chat app built with [Pylon](https://pylonsync.com). One server
-handles token streaming, conversation history, and cross-tab sync.
-
-Tokens stream from the built-in `POST /api/ai/stream` endpoint, so your provider
-API key never reaches the browser. Conversations are sync-backed and
-owner-scoped; a chat sent in one tab appears in the other.
+Lumen, a streaming AI assistant built with [Pylon](https://pylonsync.com).
+Visitors chat right away in a guest session. Signing in moves their chats to
+the account. Conversations sync live across tabs and devices, and the provider
+key stays on the server.
 
 ## Develop
 
@@ -13,80 +11,75 @@ owner-scoped; a chat sent in one tab appears in the other.
 __RUN_DEV__
 ```
 
-Open http://localhost:4321. You can create chats immediately. Configure an LLM
-provider to receive replies, then open a second tab to see conversations and
-messages sync.
-
-## Configure the model
+Open http://localhost:4321. With no provider key, the app shows the setup
+steps, seeds three example conversations (labeled as examples and read-only),
+and still stores the messages you send.
 
-The assistant replies after you configure a provider. Without one, the app
-still boots and displays a configuration notice:
+## Add a model provider
 
 ```bash
 # .env
-PYLON_AI_PROVIDER=anthropic        # or "openai" / "custom"
-PYLON_AI_API_KEY=sk-ant-...
-PYLON_AI_MODEL=claude-sonnet-4-6   # default when none is picked
+PYLON_LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-`/api/ai/stream` is auth-gated (it uses your signed-in session) and rate-limited
-per user, so a drive-by caller can't burn your budget.
-
-### Switching models / providers
-
-The composer has a **model picker** — its options live in `lib/site.config.ts`
-(`chat.models`, each with a provider label), and the chosen id is sent per
-request. Client-chosen models must be allow-listed server-side:
+Restart `pylon dev`. For OpenAI, set `PYLON_LLM_PROVIDER=openai` and
+`OPENAI_API_KEY`, then replace the ids in `chat.models` in
+`lib/site.config.ts`. For an OpenAI-compatible gateway such as OpenRouter,
+also set `PYLON_LLM_BASE_URL` (for example `https://openrouter.ai/api`) and use
+the gateway's model ids.
 
-```bash
-PYLON_AI_MODELS_ALLOWED=claude-sonnet-4-6,claude-opus-4-8,gpt-4o
-```
-
-`/api/ai/stream` talks to **one** provider. To offer models from **multiple
-providers** in one picker, route through an OpenAI-compatible gateway like
-[OpenRouter](https://openrouter.ai):
-
-```bash
-PYLON_AI_PROVIDER=custom
-PYLON_AI_BASE_URL=https://openrouter.ai/api/v1
-PYLON_AI_API_KEY=<openrouter key>
-```
-
-then set `chat.models` + `PYLON_AI_MODELS_ALLOWED` to the gateway's slugs
-(`anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`, …).
+The model list in `lib/site.config.ts` is the allowlist. `app.ts` passes it to
+`llm({ allowedModels })`, and `respond` refuses any other id.
 
 ## How it works
 
-- **Streaming.** `app/chat-client.tsx` POSTs the conversation to
-  `/api/ai/stream` and reads the SSE response (`data: {choices:[{delta:…}]}` …
-  `data: [DONE]`), appending tokens to the live assistant bubble.
-- **Realtime history.** `Conversation` + `Message` are owner-scoped entities
-  read with `db.useQuery` — private to each user and synced across their tabs.
-  Messages are written with optimistic `db.insert` (userId is stamped from the
-  session via `field.owner()`), so no custom write functions are needed.
-- **Sign-in required.** Chats are tied to your account, so the home page
-  redirects unauthenticated visitors to `/login`. Once signed in, your history
-  follows you across tabs and devices.
+- **Replies.** `functions/respond.ts` is a streaming action. It calls
+  `ctx.llm.stream` and writes each token to `ctx.stream`. The client reads it
+  with `streamFn("respond", …)`.
+- **Other tabs.** `_beginTurn` stores the call's resumable stream id on the
+  assistant message. Another tab (or this one after a reload) attaches with
+  `resumeStream(streamId)` and shows the same tokens. The final text is written
+  to the message row, which syncs everywhere.
+- **Stop and regenerate.** Stop stores the text shown so far with status
+  `stopped`. Regenerate removes the last reply and writes a new one.
+- **Guests.** `<EnsureGuest>` creates a guest session on first visit. Every
+  function the chat calls accepts guests (`auth: "guest"`).
+- **Sign-in keeps history.** Before signing in, the guest gets a one-time code
+  from `prepareGuestClaim`. After sign-in, `claimGuestHistory` uses it to move
+  the guest's conversations to the account.
+- **Limits.** `repliesPerHour` in `lib/site.config.ts` caps replies per rolling
+  hour, lower for guests than for accounts.
 
 ## Privacy
 
-`Conversation` and `Message` policies are owner-scoped (`auth.userId ==
-data.userId`) — you can only ever read or write your own. `User.passwordHash` is
-`serverOnly`. The provider key lives only on the server.
+`Conversation` and `Message` rows are readable only by their owner. Clients can
+rename their own conversations; every other write goes through a server
+function that checks ownership. `GuestClaim` is never readable by clients, and
+only a hash of each claim code is stored. `User.passwordHash` is `serverOnly`.
 
 ## Rebrand it
 
-The name, colors, system prompt, empty-state copy, and starter prompts live in
-**`lib/site.config.ts`**.
+The name, colors, system prompt, suggestions, models, and limits live in
+`lib/site.config.ts`. Replace or delete the examples in `lib/examples.ts`.
 
 ## Layout
 
 ```
-app.ts                 Conversation + Message (owner-scoped) + User
-lib/site.config.ts     brand + system prompt + suggestions (edit this)
-app/page.tsx           renders the chat island
-app/chat-client.tsx    sidebar + thread + streaming via /api/ai/stream
-app/login/             optional sign-in (carries history across devices)
+app.ts                     entities, policies, llm() allowlist, fonts
+lib/site.config.ts         brand, prompt, suggestions, models, limits
+lib/chat.ts                history, titles, day groups, error copy (tested)
+lib/markdown.ts            Markdown parser for replies (tested)
+functions/respond.ts       streams a reply with ctx.llm.stream
+app/(chat)/chat-client.tsx the only file that talks to Pylon on the client
+components/chat/           sidebar, thread, composer, setup card
+app/login/                 optional sign-in
+```
+
+## Test
+
+```bash
+pylon test
 ```
 
 ## Deploy

package/templates/ai-chat/app/(chat)/c/[id]/page.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { type Metadata, type PageProps } from "@pylonsync/react";
+import { ChatApp } from "../../chat-client";
+import { siteConfig } from "@/lib/site.config";
+import { brandIcon } from "@/lib/brand-icon";
+
+export const metadata: Metadata = {
+  title: siteConfig.seo.title,
+  robots: "noindex",
+  icons: { icon: brandIcon },
+};
+
+// `/c/:id`: one conversation. The id is only a starting point; the client
+// loads the conversation through the owner-scoped live query, so another
+// visitor's id shows nothing.
+export default function ConversationPage({ auth, params }: PageProps<{ id: string }>) {
+  const signedIn = Boolean(auth.user_id) && !auth.is_guest && !auth.user_id?.startsWith("guest_");
+  return <ChatApp initialConversationId={params.id} signedInUserId={signedIn ? auth.user_id : null} />;
+}