@pylonsync/create-pylon 0.9.1 → 0.10.0

package/templates/consumer/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/creator/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/crm/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/directory/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/expo/mobile/apps/expo/.env.example

@@ -13,7 +13,16 @@ EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=
 EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=
 EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=
 
-# Shown in Settings and required by both stores.
-EXPO_PUBLIC_PRIVACY_URL=https://example.com/privacy
-EXPO_PUBLIC_TERMS_URL=https://example.com/terms
-EXPO_PUBLIC_SUPPORT_EMAIL=support@example.com
+# The privacy policy, terms, and help pages are served by the backend in
+# apps/api, so they default to EXPO_PUBLIC_PYLON_BASE_URL + /privacy, /terms,
+# and /support. Both stores require a reachable privacy policy URL.
+#
+# Set these only if the marketing site lives somewhere else, e.g. your own
+# domain. EXPO_PUBLIC_SITE_URL moves all three at once.
+# EXPO_PUBLIC_SITE_URL=https://yourapp.com
+# EXPO_PUBLIC_PRIVACY_URL=
+# EXPO_PUBLIC_TERMS_URL=
+# EXPO_PUBLIC_SUPPORT_URL=
+
+# Optional. Adds a "Contact support" row in Settings.
+EXPO_PUBLIC_SUPPORT_EMAIL=

package/templates/expo/mobile/apps/expo/README.md

@@ -15,9 +15,16 @@ src/session.tsx            boot + state machine
 src/purchases.ts           RevenueCat wrapper, safe in Expo Go
 src/entitlements.ts        usePro() from the synced RcEntitlement rows
 src/analytics.ts           funnel events; wire to your SDK in one place
+src/links.ts               privacy / terms / support URLs, served by apps/api
 STORE.md                   the submission checklist
 ```
 
+The public website (landing page, `/privacy`, `/terms`, `/support`) is served
+by the backend in `apps/api`, on the same host as the API. The links in
+Settings and under the paywall point there with no configuration, which is
+what makes the store requirement satisfiable from a fresh scaffold. Edit its
+copy in `apps/api/lib/site.ts`.
+
 ## Run
 
 ```bash
@@ -49,6 +56,8 @@ also carry Notes-specific copy or logic:
 - `app/(tabs)/settings.tsx`: the delete-account confirmation.
 - `app/(tabs)/index.tsx`: the list, `FREE_LIMIT`, and the sign-in nudge.
 - `app.config.ts`: `name`, `slug`, `scheme`, and the icons in `assets/`.
+- `apps/api/lib/site.ts`: the website copy, store links, and the company
+  details the privacy policy and terms need.
 - `apps/api/functions/deleteMyData.ts`: delete every entity that stores
   user data, or account deletion leaves rows behind.
 - `apps/api/functions/createNote.ts`: the free-tier cap.

package/templates/expo/mobile/apps/expo/STORE.md

@@ -3,7 +3,7 @@
 The order below is the shortest path that App Review and Google Play accept
 on the first try. Each step is one command or one dashboard page.
 
-## 1. Backend live
+## 1. Backend and website live
 
 ```bash
 cd apps/api && pylon deploy
@@ -52,8 +52,12 @@ Test the purchase on TestFlight with a sandbox Apple ID before submitting.
 
 Both stores require, and reviewers check:
 
-- Privacy policy URL and terms URL (`EXPO_PUBLIC_PRIVACY_URL`, `EXPO_PUBLIC_TERMS_URL`).
-  The app shows them in Settings and under the paywall.
+- Privacy policy URL and terms URL. The backend serves them at
+  `<your-backend>/privacy` and `<your-backend>/terms`, and the app links to
+  them from Settings and under the paywall with no configuration. Fill in
+  `apps/api/lib/site.ts` first: the text ships as a draft and a banner stays
+  on the page until you do.
+- A support URL for App Store Connect: `<your-backend>/support`.
 - Account deletion inside the app (Settings → Delete account). Present.
 - Sign in with Apple when any other third-party sign-in is offered. Present.
 - Subscription terms next to the purchase button (price, period, renewal). Present.
@@ -87,8 +91,8 @@ Without it `eas submit` asks for the app interactively.
   RevenueCat, and the iOS and Android public keys are in `apps/expo/.env`.
 - Sign-in: `PYLON_APPLE_NATIVE_CLIENT_IDS` (the bundle id) and
   `PYLON_GOOGLE_NATIVE_CLIENT_IDS` are set on the backend.
-- Legal: `EXPO_PUBLIC_PRIVACY_URL`, `EXPO_PUBLIC_TERMS_URL`, and
-  `EXPO_PUBLIC_SUPPORT_EMAIL` point at real pages and a monitored inbox.
+- Legal: `apps/api/lib/site.ts` is filled in, the draft banner is gone from
+  `/privacy` and `/terms`, and a lawyer has read both.
 - Deletion: `apps/api/functions/deleteMyData.ts` removes every entity that
   stores user data. Test it with a throwaway account.
 - Copy: the "Replace the demo" list in `README.md` is done.

package/templates/expo/mobile/apps/expo/app/(tabs)/settings.tsx

@@ -4,6 +4,7 @@ import { useRouter } from "expo-router";
 import Constants from "expo-constants";
 import { deleteAccount } from "@pylonsync/react-native";
 import { track } from "@/analytics";
+import { PRIVACY_URL, SUPPORT_EMAIL, SUPPORT_URL, TERMS_URL } from "@/links";
 import { usePro } from "@/entitlements";
 import { resetFlags } from "@/flags";
 import { manageSubscriptionUrl, restore } from "@/purchases";
@@ -27,9 +28,8 @@ export default function Settings() {
   const { pro } = usePro();
   const [busy, setBusy] = useState<string | null>(null);
 
-  const privacy = process.env.EXPO_PUBLIC_PRIVACY_URL;
-  const terms = process.env.EXPO_PUBLIC_TERMS_URL;
-  const support = process.env.EXPO_PUBLIC_SUPPORT_EMAIL;
+  // These resolve to the site the backend serves (apps/api), so the rows
+  // always render and always lead somewhere real. See src/links.ts.
   const version = Constants.expoConfig?.version ?? "dev";
 
   async function restorePurchases() {
@@ -99,9 +99,12 @@ export default function Settings() {
         <Spacer />
 
         <Caption>About</Caption>
-        {privacy ? <Row label="Privacy policy" onPress={() => void Linking.openURL(privacy)} /> : null}
-        {terms ? <Row label="Terms of service" onPress={() => void Linking.openURL(terms)} /> : null}
-        {support ? <Row label="Contact support" onPress={() => void Linking.openURL(`mailto:${support}`)} /> : null}
+        <Row label="Help" onPress={() => void Linking.openURL(SUPPORT_URL)} />
+        <Row label="Privacy policy" onPress={() => void Linking.openURL(PRIVACY_URL)} />
+        <Row label="Terms of service" onPress={() => void Linking.openURL(TERMS_URL)} />
+        {SUPPORT_EMAIL ? (
+          <Row label="Contact support" onPress={() => void Linking.openURL(`mailto:${SUPPORT_EMAIL}`)} />
+        ) : null}
         <Row label="Version" value={version} />
         <Spacer />
 

package/templates/expo/mobile/apps/expo/app/paywall.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useState } from "react";
 import { Alert, Linking, Pressable, Text, View } from "react-native";
 import { useLocalSearchParams, useRouter } from "expo-router";
 import { track } from "@/analytics";
+import { PRIVACY_URL, TERMS_URL } from "@/links";
 import { usePro } from "@/entitlements";
 import { available, offers, purchase, restore, type Offer } from "@/purchases";
 import { radius, space, useTheme } from "@/theme";
@@ -45,8 +46,7 @@ export default function Paywall() {
     if (pro) router.back();
   }, [pro, router]);
 
-  const privacy = process.env.EXPO_PUBLIC_PRIVACY_URL;
-  const terms = process.env.EXPO_PUBLIC_TERMS_URL;
+
 
   async function buy() {
     const offer = list?.find((o) => o.id === selected);
@@ -160,17 +160,13 @@ export default function Paywall() {
       <Button title="Restore purchases" variant="ghost" loading={busy === "restore"} onPress={() => void restorePurchases()} />
       <Text style={{ color: t.muted, fontSize: 11, textAlign: "center", lineHeight: 16, marginTop: space.sm }}>
         Renews automatically until cancelled. Manage in your store account settings.{" "}
-        {terms ? (
-          <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(terms)}>
-            Terms
-          </Text>
-        ) : null}
-        {terms && privacy ? " · " : ""}
-        {privacy ? (
-          <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(privacy)}>
-            Privacy
-          </Text>
-        ) : null}
+        <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(TERMS_URL)}>
+          Terms
+        </Text>
+        {" · "}
+        <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(PRIVACY_URL)}>
+          Privacy
+        </Text>
       </Text>
     </Screen>
   );

package/templates/expo/mobile/apps/expo/src/links.ts

@@ -0,0 +1,29 @@
+/**
+ * Where the app sends people for legal text and help.
+ *
+ * The backend in `apps/api` serves a website as well as the API, so these
+ * pages already exist on whatever host `EXPO_PUBLIC_PYLON_BASE_URL` points
+ * at. That is what makes the App Store and Play Store requirements
+ * satisfiable straight from a scaffold: both stores refuse a submission
+ * without a reachable privacy policy URL.
+ *
+ * Set the EXPO_PUBLIC_* values only if you host the marketing site somewhere
+ * else, on your own domain for example.
+ */
+import { PYLON_BASE_URL } from "./pylon";
+
+const siteOrigin = (
+  process.env.EXPO_PUBLIC_SITE_URL || PYLON_BASE_URL
+).replace(/\/+$/, "");
+
+export const PRIVACY_URL =
+  process.env.EXPO_PUBLIC_PRIVACY_URL || `${siteOrigin}/privacy`;
+
+export const TERMS_URL =
+  process.env.EXPO_PUBLIC_TERMS_URL || `${siteOrigin}/terms`;
+
+export const SUPPORT_URL =
+  process.env.EXPO_PUBLIC_SUPPORT_URL || `${siteOrigin}/support`;
+
+/** Optional. Settings shows a "Contact support" row when it is set. */
+export const SUPPORT_EMAIL = process.env.EXPO_PUBLIC_SUPPORT_EMAIL;

package/templates/helpdesk/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/inventory/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/invoices/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/local-service/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/marketplace/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/projects/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/restaurant/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/saas/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.

package/templates/saas/app/dashboard/layout.tsx

@@ -36,8 +36,15 @@ export default function DashboardLayout({
   if (!auth.tenant_id) {
     return <>{children}</>;
   }
-  const me = use(serverData.get<{ email?: string }>("User", auth.user_id));
-  const org = use(serverData.get<{ name?: string }>("Org", auth.tenant_id));
+  // Every read is started before the first use(): calling them one at a time
+  // makes each wait for the last, since use() suspends on the first pending
+  // thenable. Never Promise.all them — a new pending promise each render means
+  // the page never returns (React error #482).
+  const mePromise = serverData.get<{ email?: string }>("User", auth.user_id);
+  const orgPromise = serverData.get<{ name?: string }>("Org", auth.tenant_id);
+
+  const me = use(mePromise);
+  const org = use(orgPromise);
   // Longest matching NAV href wins so /dashboard/projects highlights
   // Projects, not Overview.
   const path = (url ?? "").split("?")[0];

package/templates/saas/app/dashboard/page.tsx

@@ -27,13 +27,35 @@ export default function DashboardPage({ auth, response, serverData }: PageProps)
   if (!auth.tenant_id) {
     return <ProvisionWorkspace />;
   }
-  const me = use(serverData.get<{ email?: string }>("User", auth.user_id!));
-  const org = use(
-    serverData.get<{ name?: string; onboardedAt?: string | null; setupDismissedAt?: string | null }>(
-      "Org",
-      auth.tenant_id,
-    ),
-  );
+  // Every read is STARTED here, before the first use(). Each serverData call
+  // returns a thenable the handle caches by key, and use() suspends on the
+  // first one still pending — so reading them one at a time makes each wait
+  // for the last. Six reads that way is six round trips; issued together it
+  // is one, and the replayed render finds each already cached.
+  //
+  // Do NOT reach for Promise.all. It builds a new, pending, uncached promise
+  // on every render, so use() suspends, re-renders, builds another, and the
+  // page never returns — React reports it as an async Client Component
+  // (minified error #482).
+  //
+  // The onboarding redirect below only needs `org`, so on that path the other
+  // reads are issued and thrown away. A redirect is the rare case; paying one
+  // round trip on every normal load to save four on a rare one is the wrong
+  // way round.
+  const mePromise = serverData.get<{ email?: string }>("User", auth.user_id!);
+  const orgPromise = serverData.get<{
+    name?: string;
+    onboardedAt?: string | null;
+    setupDismissedAt?: string | null;
+  }>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const membersPromise = serverData.list<OrgMemberRow>("OrgMember");
+  const subsPromise = serverData.list<Subscription>("StripeSubscription");
+  const invitesPromise =
+    serverData.list<{ orgId: string; acceptedAt?: string | null }>("OrgInvite");
+
+  const me = use(mePromise);
+  const org = use(orgPromise);
   // A workspace created outside the wizard (or one that abandoned it) gets
   // sent through it once. Owners/admins only; a member who lands here just
   // sees the dashboard.
@@ -43,21 +65,22 @@ export default function DashboardPage({ auth, response, serverData }: PageProps)
     response.redirect("/onboarding");
     return null;
   }
-  const projects = use(serverData.list<Project>("Project"));
-  const members = use(serverData.list<OrgMemberRow>("OrgMember"));
+  const projects = use(projectsPromise);
   // The OrgMember read policy returns this user's memberships across every org,
   // so scope the count to the active workspace.
-  const memberCount = members.filter((m) => m.orgId === auth.tenant_id).length;
+  const memberCount = use(membersPromise).filter(
+    (m) => m.orgId === auth.tenant_id,
+  ).length;
   // Active-plan badge from the workspace's Stripe subscription (Free until one
   // exists). Scoped to the active tenant by the plugin's read policy.
-  const subs = use(serverData.list<Subscription>("StripeSubscription"));
-  const active = subs.find((s) =>
+  const active = use(subsPromise).find((s) =>
     ["active", "trialing", "past_due"].includes(s.status),
   );
   const plan = active ? active.plan : "free";
   // Getting-started checklist, derived from real rows so it ticks itself off.
-  const invites = use(serverData.list<{ orgId: string; acceptedAt?: string | null }>("OrgInvite"));
-  const pendingInvites = invites.filter((i) => i.orgId === auth.tenant_id && !i.acceptedAt).length;
+  const pendingInvites = use(invitesPromise).filter(
+    (i) => i.orgId === auth.tenant_id && !i.acceptedAt,
+  ).length;
   const setup: SetupState | null = org?.setupDismissedAt
     ? null
     : {

package/templates/saas/app/dashboard/settings/page.tsx

@@ -21,10 +21,17 @@ export default function SettingsPage({ auth, response, serverData }: PageProps)
     response.redirect("/dashboard");
     return null;
   }
-  const org = use(serverData.get<OrgInfo>("Org", auth.tenant_id));
-  const me = use(serverData.get<AccountInfo>("User", auth.user_id!));
-  const members = use(serverData.list<OrgMemberRow>("OrgMember"));
-  const memberCount = members.filter(
+  // Every read is started before the first use(): calling them one at a time
+  // makes each wait for the last, since use() suspends on the first pending
+  // thenable. Never Promise.all them — a new pending promise each render means
+  // the page never returns (React error #482).
+  const orgPromise = serverData.get<OrgInfo>("Org", auth.tenant_id);
+  const mePromise = serverData.get<AccountInfo>("User", auth.user_id!);
+  const membersPromise = serverData.list<OrgMemberRow>("OrgMember");
+
+  const org = use(orgPromise);
+  const me = use(mePromise);
+  const memberCount = use(membersPromise).filter(
     (m) => m.orgId === auth.tenant_id,
   ).length;
   return (

package/templates/shop/AGENTS.md

@@ -48,6 +48,17 @@ this pass before the user has to ask.
 - **`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 `pathname` / `searchParams` page props (`pathname` is the PATH only — the query is already parsed into `searchParams`, so never try to read a query parameter back out of it; the older `url` prop is the same value and is deprecated).
 - **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.
+- **Never wrap `serverData` calls in `Promise.all`.** Each method returns a thenable the handle CACHES by key — on the client it is already fulfilled, so `use()` returns synchronously. `Promise.all` builds a new, pending, uncached promise on every render, so `use()` suspends, re-renders, builds another, and the page never returns; React reports it as an async Client Component (minified error #482) and the error boundary shows a broken page. To read several things in parallel, START every call before the first `use()`, then `use()` each handle — the reads overlap and the replayed render finds each one cached:
+
+  ```tsx
+  const orgPromise = serverData.get<Org>("Org", auth.tenant_id);
+  const projectsPromise = serverData.list<Project>("Project");
+  const org = use(orgPromise);
+  const projects = use(projectsPromise);
+  ```
+
+  Reading them one at a time (`use(serverData.a()); use(serverData.b());`) is correct but serial: each read waits for the one above it.
+
 - **`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`.