@pylonsync/create-pylon 0.19.1 → 0.21.0

package/templates/saas/lib/tasks.ts

@@ -0,0 +1,101 @@
+// Task vocabulary and pure helpers. The server functions (createTask,
+// updateTask) validate with these, and the dashboard renders from the same
+// lists, so a status or priority can't exist in one place and not the other.
+// tests/tasks.test.ts covers them without a running server.
+
+export const TASK_STATUSES = ["todo", "in_progress", "in_review", "done"] as const;
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+
+export const STATUS_LABEL: Record<TaskStatus, string> = {
+  todo: "To do",
+  in_progress: "In progress",
+  in_review: "In review",
+  done: "Done",
+};
+
+export const TASK_PRIORITIES = ["urgent", "high", "medium", "low", "none"] as const;
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+
+export const PRIORITY_LABEL: Record<TaskPriority, string> = {
+  urgent: "Urgent",
+  high: "High",
+  medium: "Medium",
+  low: "Low",
+  none: "No priority",
+};
+
+export interface TaskRow {
+  id: string;
+  orgId: string;
+  projectId: string;
+  title: string;
+  status: string;
+  priority?: string | null;
+  assigneeId?: string | null;
+  assigneeName?: string | null;
+  dueDate?: string | null;
+  completedAt?: string | null;
+  createdAt: string;
+}
+
+export function isTaskStatus(value: unknown): value is TaskStatus {
+  return typeof value === "string" && (TASK_STATUSES as readonly string[]).includes(value);
+}
+
+export function isTaskPriority(value: unknown): value is TaskPriority {
+  return typeof value === "string" && (TASK_PRIORITIES as readonly string[]).includes(value);
+}
+
+/** Trimmed title, or null when it is empty or longer than 200 characters. */
+export function normalizeTaskTitle(raw: string): string | null {
+  const title = raw.trim().replace(/\s+/g, " ");
+  if (title.length < 1 || title.length > 200) return null;
+  return title;
+}
+
+/** `YYYY-MM-DD` that is a real calendar date, or null. */
+export function normalizeDueDate(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) return null;
+  const d = new Date(`${raw}T00:00:00Z`);
+  if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== raw) return null;
+  return raw;
+}
+
+/** Done / total counts and a 0–100 percentage for one project's tasks. */
+export function progressOf(tasks: Pick<TaskRow, "status">[]): {
+  done: number;
+  total: number;
+  percent: number;
+} {
+  const total = tasks.length;
+  const done = tasks.filter((t) => t.status === "done").length;
+  return { done, total, percent: total === 0 ? 0 : Math.round((done / total) * 100) };
+}
+
+const PRIORITY_RANK: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3, none: 4 };
+
+/**
+ * Board order inside a column: priority first, then the earliest due date,
+ * then the newest task. Undated tasks sort after dated ones.
+ */
+export function compareTasks(a: TaskRow, b: TaskRow): number {
+  const pa = PRIORITY_RANK[a.priority ?? "none"] ?? 4;
+  const pb = PRIORITY_RANK[b.priority ?? "none"] ?? 4;
+  if (pa !== pb) return pa - pb;
+  const da = a.dueDate ?? "9999-12-31";
+  const db = b.dueDate ?? "9999-12-31";
+  if (da !== db) return da < db ? -1 : 1;
+  return a.createdAt < b.createdAt ? 1 : -1;
+}
+
+/** Whole days from `today` to `due` (both `YYYY-MM-DD`). Negative when overdue. */
+export function daysUntil(due: string, today: string): number {
+  const ms = Date.parse(`${due}T00:00:00Z`) - Date.parse(`${today}T00:00:00Z`);
+  return Math.round(ms / 86_400_000);
+}
+
+/** `YYYY-MM-DD` for a Date, in UTC. */
+export function isoDay(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}

package/templates/saas/lib/use-live.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "react";
+import { db } from "@pylonsync/react";
+
+/**
+ * Rows of `entity` for one workspace, live. The server render and the first
+ * client paint use `initial` (resolved with `serverData` in the page), so the
+ * HTML and the hydrated tree match and nothing flashes empty. After mount the
+ * list switches to the synced replica, which updates on every write from any
+ * tab or teammate.
+ *
+ * The entity's read policy already limits the replica to the active
+ * workspace; the `orgId` filter drops rows from a previous workspace that
+ * can linger for a moment after switching.
+ */
+export function useLiveRows<T extends { orgId: string }>(
+  entity: string,
+  initial: T[],
+  orgId: string,
+): T[] {
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  const { data, loading } = db.useQuery<T>(entity);
+  if (!hydrated || loading) return initial;
+  return data.filter((row) => row.orgId === orgId);
+}

package/templates/saas/scripts/capture-screenshots.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Regenerates the product screenshots the landing page shows
+// (public/screenshots/*.png) from this app's own dashboard.
+//
+//   1. Start the app:            pylon dev
+//   2. Install Playwright once:  npm i -D playwright && npx playwright install chromium
+//   3. Capture:                  node scripts/capture-screenshots.mjs
+//
+// The script signs up a workspace owner and three teammates through the auth
+// API, invites the teammates, adds the sample projects (seedWorkspace), then
+// opens the dashboard in Chromium and saves each screen. Run it against a
+// fresh development database: it reuses the accounts on a second run, but the
+// data then reflects whatever you changed in between.
+//
+// Set BASE_URL to capture from another port.
+
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BASE = (process.env.BASE_URL ?? "http://localhost:4321").replace(/\/$/, "");
+const OUT = join(dirname(fileURLToPath(import.meta.url)), "..", "public", "screenshots");
+const PASSWORD = "sample-password-2941";
+const OWNER = { email: "dana@northwind.test", name: "Dana Reyes" };
+const TEAM = [
+  { email: "sam@northwind.test", name: "Sam Okafor" },
+  { email: "priya@northwind.test", name: "Priya Raman" },
+  { email: "leo@northwind.test", name: "Leo Park" },
+];
+const PENDING = ["maria@northwind.test", "jonas@northwind.test"];
+
+let chromium;
+try {
+  ({ chromium } = await import("playwright"));
+} catch {
+  try {
+    ({ chromium } = await import("playwright-core"));
+  } catch {
+    console.error("Playwright is not installed. Run: npm i -D playwright && npx playwright install chromium");
+    process.exit(1);
+  }
+}
+
+async function api(path, { token, body, method = "POST" } = {}) {
+  const res = await fetch(BASE + path, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const err = new Error(`${method} ${path} → ${res.status} ${data?.error?.code ?? ""} ${data?.error?.message ?? ""}`);
+    err.code = data?.error?.code;
+    throw err;
+  }
+  return data;
+}
+
+/** Register the account, or sign in when it already exists. Returns a token. */
+async function account({ email, name }) {
+  try {
+    const s = await api("/api/auth/password/register", { body: { email, password: PASSWORD, displayName: name } });
+    return s.token;
+  } catch (err) {
+    if (err.code !== "EMAIL_TAKEN" && err.code !== "USER_EXISTS") throw err;
+    const s = await api("/api/auth/password/login", { body: { email, password: PASSWORD } });
+    return s.token;
+  }
+}
+
+async function setUp() {
+  const owner = await account(OWNER);
+  const orgs = await api("/api/auth/orgs", { token: owner, method: "GET" });
+  const list = Array.isArray(orgs) ? orgs : orgs.orgs ?? [];
+  let org = list.find((o) => o.name === "Northwind");
+  if (!org) org = await api("/api/auth/orgs", { token: owner, body: { name: "Northwind" } });
+  await api("/api/auth/select-org", { token: owner, body: { orgId: org.id } });
+
+  const members = await api(`/api/auth/orgs/${org.id}/members`, { token: owner, method: "GET" });
+  const roster = Array.isArray(members) ? members : members.members ?? [];
+  for (const person of TEAM) {
+    const token = await account(person);
+    if (roster.some((m) => m.email === person.email)) continue;
+    const invite = await api(`/api/auth/orgs/${org.id}/invites`, {
+      token: owner,
+      body: { email: person.email, role: "member" },
+    });
+    await api(`/api/auth/invites/${encodeURIComponent(invite.token)}/accept`, { token, body: {} });
+  }
+  for (const email of PENDING) {
+    await api(`/api/auth/orgs/${org.id}/invites`, { token: owner, body: { email, role: "member" } }).catch(() => {});
+  }
+
+  await api("/api/fn/seedWorkspace", { token: owner, body: { orgId: org.id } });
+  await api("/api/fn/completeOnboarding", { token: owner, body: { orgId: org.id } });
+  await api("/api/fn/dismissSetup", { token: owner, body: { orgId: org.id } });
+  return org;
+}
+
+// Hide the development-only overlay badge that `pylon dev` adds.
+async function hideDevBadge(page) {
+  await page.evaluate(() => {
+    for (const el of document.querySelectorAll("body *")) {
+      if (el.children.length === 0 && el.textContent?.trim() === "pylon") {
+        let node = el;
+        while (node && getComputedStyle(node).position !== "fixed") node = node.parentElement;
+        if (node) node.style.display = "none";
+      }
+    }
+  });
+}
+
+async function shoot(page, path, file) {
+  await page.goto(BASE + path, { waitUntil: "load" });
+  await page.waitForTimeout(1500);
+  await hideDevBadge(page);
+  await page.screenshot({ path: join(OUT, file) });
+  console.log(`saved public/screenshots/${file}`);
+}
+
+const org = await setUp();
+await mkdir(OUT, { recursive: true });
+
+const browser = await chromium.launch();
+const context = await browser.newContext({ viewport: { width: 1440, height: 900 }, deviceScaleFactor: 2 });
+const page = await context.newPage();
+// Signing in from the page stores the session cookie in this browser
+// context. The active workspace belongs to the session, so select it here too.
+await page.goto(BASE + "/login");
+await page.evaluate(
+  async ({ email, password, orgId }) => {
+    const post = (path, body) =>
+      fetch(path, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        credentials: "include",
+        body: JSON.stringify(body),
+      });
+    await post("/api/auth/password/login", { email, password });
+    await post("/api/auth/select-org", { orgId });
+  },
+  { email: OWNER.email, password: PASSWORD, orgId: org.id },
+);
+
+await shoot(page, "/dashboard", "overview.png");
+await shoot(page, "/dashboard/projects", "projects.png");
+await shoot(page, "/dashboard/members", "members.png");
+await page.goto(BASE + "/dashboard/projects", { waitUntil: "load" });
+await page.getByRole("link", { name: /Website relaunch/ }).first().click();
+await page.waitForURL(/\/dashboard\/projects\/.+/);
+await shoot(page, new URL(page.url()).pathname, "board.png");
+
+await browser.close();

package/templates/saas/tests/names.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "bun:test";
+import { firstName, initials, nameFromEmail, personName } from "../lib/names";
+
+test("a name built from an email drops the +tag and digits", () => {
+  expect(nameFromEmail("dana+s13596@example.com")).toBe("Dana");
+  expect(nameFromEmail("dana.reyes@example.com")).toBe("Dana Reyes");
+  expect(nameFromEmail("sam_okafor-2@example.com")).toBe("Sam Okafor");
+  expect(nameFromEmail("1234@example.com")).toBe("");
+  expect(nameFromEmail(null)).toBe("");
+});
+
+test("the saved display name wins", () => {
+  expect(personName({ displayName: "Dana Reyes", email: "d@example.com" })).toBe("Dana Reyes");
+  expect(personName({ displayName: "  ", email: "leo.park@example.com" })).toBe("Leo Park");
+});
+
+test("a name that is an email address counts as no name", () => {
+  expect(personName({ name: "priya@example.com", email: "priya@example.com" })).toBe("Priya");
+});
+
+test("an email with nothing readable falls back to the email", () => {
+  expect(personName({ email: "42@example.com" })).toBe("42@example.com");
+});
+
+test("greetings use the first word; avatars use two initials", () => {
+  expect(firstName({ displayName: "Dana Reyes" })).toBe("Dana");
+  expect(initials("Dana Reyes")).toBe("DR");
+  expect(initials("Priya Anand Raman")).toBe("PR");
+  expect(initials("Leo")).toBe("L");
+  expect(initials("")).toBe("?");
+});
+
+test("names longer than the UI limit are cut", () => {
+  expect(personName({ displayName: "x".repeat(500) })).toHaveLength(60);
+});

package/templates/saas/tests/plans.test.ts

@@ -6,6 +6,7 @@ import {
   canCreateProject,
   planById,
   planFromSubscription,
+  planFromSubscriptions,
 } from "../lib/plans";
 
 // Tier 1 (pure logic) — the cap and the plan derivation that
@@ -33,3 +34,14 @@ test("annual pricing derives its total and saving from the catalog", () => {
   expect(annualSavingsPercent(pro)).toBeGreaterThan(0);
   expect(annualSavingsPercent(planById("free")!)).toBe(0);
 });
+
+test("a usable Pro row wins over an older canceled row", () => {
+  expect(
+    planFromSubscriptions([
+      { plan: "pro", status: "canceled" },
+      { plan: "pro", status: "trialing" },
+    ]),
+  ).toBe("pro");
+  expect(planFromSubscriptions([{ plan: "pro", status: "canceled" }])).toBe("free");
+  expect(planFromSubscriptions([])).toBe("free");
+});

package/templates/saas/tests/sample-workspace.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { FREE_PROJECT_LIMIT } from "../lib/plans";
+import { SAMPLE_PROJECTS, planSampleWorkspace } from "../lib/sample-workspace";
+import { isTaskPriority, isTaskStatus, normalizeTaskTitle } from "../lib/tasks";
+
+const NOW = new Date("2026-09-26T12:00:00Z");
+
+test("the samples leave a free workspace room for one project of its own", () => {
+  const active = SAMPLE_PROJECTS.filter((p) => p.status === "active").length;
+  expect(active).toBeLessThan(FREE_PROJECT_LIMIT);
+});
+
+test("every sample task passes the same validation as createTask", () => {
+  for (const p of SAMPLE_PROJECTS) {
+    for (const t of p.tasks) {
+      expect(normalizeTaskTitle(t.title)).toBe(t.title);
+      expect(isTaskStatus(t.status)).toBe(true);
+      expect(isTaskPriority(t.priority)).toBe(true);
+    }
+  }
+});
+
+test("due dates are relative to now, and done tasks get a completion time", () => {
+  const plan = planSampleWorkspace([], NOW);
+  const first = plan[0].tasks.find((t) => t.title === "Fix the mobile nav overlap on Safari")!;
+  expect(first.dueDate).toBe("2026-09-26");
+  const done = plan[0].tasks.find((t) => t.status === "done")!;
+  expect(done.completedAt).not.toBeNull();
+  expect(plan[0].tasks.filter((t) => t.status !== "done").every((t) => t.completedAt === null)).toBe(true);
+});
+
+test("tasks go only to the members passed in", () => {
+  const solo = planSampleWorkspace([{ userId: "u1", name: "Dana Reyes" }], NOW);
+  const assigned = solo.flatMap((p) => p.tasks).filter((t) => t.assigneeId);
+  expect(assigned.length).toBeGreaterThan(0);
+  expect(assigned.every((t) => t.assigneeId === "u1" && t.assigneeName === "Dana Reyes")).toBe(true);
+
+  const nobody = planSampleWorkspace([], NOW);
+  expect(nobody.flatMap((p) => p.tasks).every((t) => t.assigneeId === null)).toBe(true);
+});
+
+test("a team gets the work spread across people", () => {
+  const team = ["a", "b", "c", "d"].map((id) => ({ userId: id, name: id }));
+  const ids = new Set(planSampleWorkspace(team, NOW).flatMap((p) => p.tasks).map((t) => t.assigneeId));
+  expect(ids).toEqual(new Set(["a", "b", "c", "d", null]));
+});

package/templates/saas/tests/tasks.test.ts

@@ -0,0 +1,81 @@
+import { expect, test } from "bun:test";
+import {
+  compareTasks,
+  daysUntil,
+  isTaskPriority,
+  isTaskStatus,
+  normalizeDueDate,
+  normalizeTaskTitle,
+  progressOf,
+  type TaskRow,
+} from "../lib/tasks";
+
+// Tier 1 (pure logic): the validation createTask/updateTask run on the
+// server, and the ordering and progress math the dashboard renders.
+
+test("statuses and priorities are closed lists", () => {
+  expect(isTaskStatus("in_review")).toBe(true);
+  expect(isTaskStatus("blocked")).toBe(false);
+  expect(isTaskStatus(undefined)).toBe(false);
+  expect(isTaskPriority("urgent")).toBe(true);
+  expect(isTaskPriority("critical")).toBe(false);
+});
+
+test("titles are trimmed, collapsed, and bounded", () => {
+  expect(normalizeTaskTitle("  Ship   the  build ")).toBe("Ship the build");
+  expect(normalizeTaskTitle("   ")).toBeNull();
+  expect(normalizeTaskTitle("x".repeat(200))).toHaveLength(200);
+  expect(normalizeTaskTitle("x".repeat(201))).toBeNull();
+});
+
+test("due dates must be real calendar days", () => {
+  expect(normalizeDueDate("2026-02-28")).toBe("2026-02-28");
+  expect(normalizeDueDate("2026-02-30")).toBeNull();
+  expect(normalizeDueDate("26-2-3")).toBeNull();
+  expect(normalizeDueDate("")).toBeNull();
+  expect(normalizeDueDate(null)).toBeNull();
+});
+
+test("progress counts done tasks", () => {
+  expect(progressOf([])).toEqual({ done: 0, total: 0, percent: 0 });
+  expect(progressOf([{ status: "done" }, { status: "todo" }, { status: "done" }])).toEqual({
+    done: 2,
+    total: 3,
+    percent: 67,
+  });
+});
+
+test("daysUntil is negative when overdue", () => {
+  expect(daysUntil("2026-09-26", "2026-09-26")).toBe(0);
+  expect(daysUntil("2026-10-01", "2026-09-26")).toBe(5);
+  expect(daysUntil("2026-09-20", "2026-09-26")).toBe(-6);
+});
+
+test("board order: priority, then due date, then newest", () => {
+  const row = (id: string, priority: string, dueDate: string | null, createdAt: string): TaskRow => ({
+    id,
+    orgId: "o",
+    projectId: "p",
+    title: id,
+    status: "todo",
+    priority,
+    dueDate,
+    createdAt,
+  });
+  const sorted = [
+    row("low-soon", "low", "2026-09-27", "2026-09-01"),
+    row("urgent", "urgent", null, "2026-09-01"),
+    row("high-late", "high", "2026-10-09", "2026-09-01"),
+    row("high-soon", "high", "2026-09-28", "2026-09-01"),
+    row("high-undated-new", "high", null, "2026-09-03"),
+    row("high-undated-old", "high", null, "2026-09-02"),
+  ].sort(compareTasks);
+  expect(sorted.map((t) => t.id)).toEqual([
+    "urgent",
+    "high-soon",
+    "high-late",
+    "high-undated-new",
+    "high-undated-old",
+    "low-soon",
+  ]);
+});

package/templates/shop/AGENTS.md

@@ -62,7 +62,7 @@ this pass before the user has to ask.
 - **`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`, `ctx.rooms`, and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
-- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. Streaming does NOT extend the call deadline (`PYLON_FN_CALL_TIMEOUT`, 30s default) — set `timeout: <secs>` on the def for a long run.
+- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. The call timeout is an idle timeout (`PYLON_FN_CALL_TIMEOUT`, 30s default; Stack0 Cloud 300s): each stream event resets it, and the total run is capped at 10× the timeout. Set `timeout: <secs>` on the def when a step (a slow tool call) can be silent longer than that.
 - **`ctx.stream.write(text)` streams to the caller — and every fn stream is RESUMABLE**: the server buffers frames under a stream id (`streamFn`'s `onStreamId`), so a dropped connection or closed tab catches up via `resumeStream(id)`, including the final result after the handler finished. `ctx.rooms.broadcast(room, topic, data)` fans out to every CURRENTLY-CONNECTED subscriber (second device, second tab) but does not replay missed messages — use the stream id for anything that must survive a gap. Broadcast resolves `{ delivered: false }` when the room has no members — a no-op, not an error. Clients receive with `useRoomMessages(room, cb)` from `@pylonsync/react`; `useRoom` is the send side.
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; an upload is readable by its uploader only, so pass `visibility: "public"` to `uploadFile` or `<FileUpload>` for files every visitor sees; 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`.

package/templates/shop/README.md

@@ -22,8 +22,10 @@ out in one tab, then watch it change to "Sold out" in another.
 
 ## How the realtime works
 
-- `Product` is a public-read entity holding live stock; `app/shop-client.tsx`
-  reads it with `db.useQuery`, so every card's stock count is live.
+- `Product` is a public-read entity holding live stock;
+  `app/(marketing)/shop-client.tsx` reads it with `db.useQuery`, so every
+  card's stock count is live. The hero's shelf count reads the same totals
+  through `lib/shelf-store.ts`.
 - `functions/checkout.ts` is a public **action**. It calls
   `functions/reserveCart.ts` (an internal **mutation**) to re-check stock under a
   per-product advisory lock and HOLD it before the order is recorded — so two
@@ -57,21 +59,28 @@ Checkout is a single public `checkout` action that holds stock, then:
   (all cart lines priced inline from your catalog — no Stripe Products to set
   up) and redirects the shopper to it. The signed `stripeWebhook` action (at
   `/api/webhooks/stripeWebhook`) marks the order **paid** on success and
-  **returns held stock** if a checkout is abandoned. The webhook signature is
-  verified with `@pylonsync/stripe`'s constant-time verifier before any event is
-  trusted.
+  **returns held stock** if a checkout is abandoned. Stripe collects a US
+  shipping address and charges the shipping terms from `lib/site.config.ts`
+  (flat rate, free over a threshold), the same numbers the cart shows. The
+  webhook signature is verified with `@pylonsync/stripe`'s constant-time
+  verifier before any event is trusted.
 - **Without Stripe keys** → the order is held as **reserved** for you to follow
-  up on. The store still works end-to-end, so you can demo live inventory with
-  zero setup.
+  up on, and the shopper lands on `/success?order=reserved`. The store still
+  works end-to-end, so you can demo live inventory with zero setup.
 
 See `.env.example` for the two env vars and the Stripe dashboard / `stripe
 listen` setup.
 
 ## Rebrand it
 
-Brand, colors, products and starting stock, value props, reviews, and policies
-live in **`lib/site.config.ts`**. Editing that file updates the store, and a
-fresh database seeds products from it.
+Brand, colors, hero and studio copy, products and starting stock, shipping
+terms, reviews, and policies live in **`lib/site.config.ts`**. Editing that
+file updates the store, and a fresh database seeds products from it.
+
+Photos live in `public/images/`. Product photos are 4:5 portrait JPEGs
+(1200x1500 works well); the hero is a wide landscape photo with open space on
+the left for the headline. `tests/shop.test.ts` fails if the config points at
+an image that is not in `public/`.
 
 ## Layout
 
@@ -85,9 +94,12 @@ functions/stripeWebhook.ts public webhook: verify signature, settle the order
 functions/{markGroupPaid,releaseGroup}.ts  internal: settle/restore on webhook
 functions/ordersForOwner.ts  owner-only query: orders + customer PII
 functions/{fulfill,cancel}Order.ts, restockProduct.ts  owner-only mutations
-app/page.tsx               the storefront (server-rendered)
-app/shop-client.tsx        client island: live product grid + cart + checkout
-app/success/page.tsx       Stripe post-payment landing
+app/(marketing)/layout.tsx       announcement bar, nav, footer
+app/(marketing)/page.tsx         the storefront (server-rendered)
+app/(marketing)/shop-client.tsx  client island: live product grid + cart + checkout
+app/(marketing)/success/page.tsx order confirmation (Stripe or reserved)
+lib/cart-store.ts, lib/shelf-store.ts  state shared between client islands
+public/images/             hero and product photos
 app/dashboard/             owner dashboard (auth-gated, live)
 ```