@pylonsync/create-pylon 0.9.1 → 0.10.0

package/templates/backend/mobile/apps/api/app/(site)/support/page.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+import { Link, type Metadata } from "@pylonsync/react";
+import { site } from "@/lib/site";
+
+export const metadata: Metadata = {
+  title: `Support — ${site.name}`,
+  description: `Get help with ${site.name}.`,
+};
+
+/**
+ * App Store Connect asks for a support URL, and Play requires a contact
+ * address on the listing. This page is both. The answers repeat what the app
+ * does so a reviewer can check a claim without installing anything.
+ */
+export default function SupportPage() {
+  return (
+    <div className="mx-auto max-w-3xl px-6 py-16 sm:py-20">
+      <h1 className="text-3xl font-semibold tracking-[-0.02em]">Support</h1>
+      <p className="mt-4 text-[15px] leading-relaxed text-ink-muted">
+        {site.supportEmail ? (
+          <>
+            Email{" "}
+            <a
+              href={`mailto:${site.supportEmail}`}
+              className="text-brand underline underline-offset-2"
+            >
+              {site.supportEmail}
+            </a>{" "}
+            and tell us what happened, what you expected, and which device you
+            are on. That is usually enough to sort it out in one reply.
+          </>
+        ) : (
+          <>Add a support address in lib/site.ts and it will appear here.</>
+        )}
+      </p>
+
+      <h2 className="mt-12 text-xl font-semibold tracking-[-0.015em]">
+        Common questions
+      </h2>
+      <dl className="mt-6 divide-y divide-line border-y border-line">
+        {site.faq.map((item) => (
+          <div key={item.q} className="py-5">
+            <dt className="text-[15px] font-medium">{item.q}</dt>
+            <dd className="mt-2 text-[14px] leading-relaxed text-ink-muted">
+              {item.a}
+            </dd>
+          </div>
+        ))}
+        <div className="py-5">
+          <dt className="text-[15px] font-medium">
+            How do I delete my account?
+          </dt>
+          <dd className="mt-2 text-[14px] leading-relaxed text-ink-muted">
+            In the app, open Settings and choose Delete account. It removes the
+            account and its notes straight away. Cancel a subscription
+            separately in the App Store or Play Store.
+          </dd>
+        </div>
+        <div className="py-5">
+          <dt className="text-[15px] font-medium">
+            My notes are not showing on my other device.
+          </dt>
+          <dd className="mt-2 text-[14px] leading-relaxed text-ink-muted">
+            Check that both devices are signed in to the same account. Notes
+            written before you signed in move to the account the first time you
+            sign in on that device.
+          </dd>
+        </div>
+      </dl>
+
+      <p className="mt-10 text-[14px] text-ink-muted">
+        See also our <Link href="/privacy" className="text-brand underline underline-offset-2">privacy policy</Link>{" "}
+        and{" "}
+        <Link href="/terms" className="text-brand underline underline-offset-2">terms</Link>.
+      </p>
+    </div>
+  );
+}

package/templates/backend/mobile/apps/api/app/(site)/terms/page.tsx

@@ -0,0 +1,144 @@
+import React from "react";
+import { type Metadata } from "@pylonsync/react";
+import { Company, LegalPage } from "@/components/legal";
+import { site } from "@/lib/site";
+
+export const metadata: Metadata = {
+  title: `Terms of Service — ${site.name}`,
+  description: `The agreement between you and ${site.name}.`,
+};
+
+/**
+ * The terms the app links to from the paywall and from Settings. Apple
+ * requires subscription terms to be visible next to the purchase, and this
+ * page is where the detail lives. Keep the billing section true to what your
+ * products actually do.
+ */
+export default function TermsPage() {
+  return (
+    <LegalPage title="Terms of Service">
+      <p>
+        These terms are the agreement between you and <Company /> for the use
+        of {site.name}. Using the app means you accept them.
+      </p>
+
+      <h2>Who may use it</h2>
+      <p>
+        You need to be at least 13 years old. If you use {site.name} for an
+        organization, you confirm you may accept these terms for it.
+      </p>
+
+      <h2>Your account</h2>
+      <p>
+        You are responsible for what happens under your account, so keep
+        access to your email and devices secure. Tell us if you think someone
+        else has your account.
+      </p>
+
+      <h2>Free and paid</h2>
+      <p>
+        The free tier holds up to {site.pricing.freeLimit} notes. A
+        subscription lifts that limit and includes what we add later. We may
+        change what each tier includes, and we will not reduce what you have
+        already paid for during a period you have paid.
+      </p>
+
+      <h2>Billing</h2>
+      <ul>
+        <li>
+          Apple and Google sell and bill the subscription, not us. The price
+          you see in the app is the price they charge in your country.
+        </li>
+        <li>
+          A subscription renews automatically until you cancel it. Cancel at
+          least 24 hours before the period ends, in your App Store or Play
+          Store account settings.
+        </li>
+        <li>
+          Refunds follow the store&apos;s policy. We cannot issue a refund for
+          a purchase we did not process, so ask Apple or Google.
+        </li>
+        <li>
+          Deleting the app does not cancel a subscription. Cancel it in the
+          store.
+        </li>
+      </ul>
+
+      <h2>Your content</h2>
+      <p>
+        Your notes are yours. You give us only the permission we need to run
+        the service, which is to store your content, back it up, and send it to
+        the devices you sign in on. We claim no ownership of it and we do not
+        use it to train anything.
+      </p>
+      <p>
+        You are responsible for what you put in the app, and for having the
+        right to put it there.
+      </p>
+
+      <h2>Acceptable use</h2>
+      <p>Do not use {site.name} to:</p>
+      <ul>
+        <li>break the law, or store material that is illegal to hold;</li>
+        <li>
+          attack the service, work around its limits, or get at other
+          people&apos;s data;
+        </li>
+        <li>resell it as your own product.</li>
+      </ul>
+
+      <h2>Availability</h2>
+      <p>
+        We work to keep {site.name} running, but we do not promise it will be
+        available without interruption. We may change or stop features. If we
+        shut the service down, we will give reasonable notice and a way to
+        export your notes.
+      </p>
+
+      <h2>Ending it</h2>
+      <p>
+        You can stop at any time by deleting your account in Settings. We may
+        suspend or close an account that breaks these terms or puts the service
+        or other people at risk.
+      </p>
+
+      <h2>Disclaimer and liability</h2>
+      <p>
+        {site.name} is provided as it is, without warranties beyond those the
+        law requires. To the extent the law allows, <Company /> is not liable
+        for indirect or consequential loss, and our total liability is limited
+        to what you paid us in the 12 months before the claim.
+      </p>
+      <p>
+        Nothing here removes rights you have as a consumer that cannot be
+        removed by agreement.
+      </p>
+
+      <h2>Changes</h2>
+      <p>
+        We may update these terms. The date at the top shows the current
+        version, and we will tell you in the app about a significant change.
+        Continuing to use {site.name} after that means you accept the new
+        terms.
+      </p>
+
+      <h2>Governing law</h2>
+      <p>
+        These terms are governed by the laws of{" "}
+        {site.governingLaw || "[your jurisdiction]"}, without regard to
+        conflict of law rules.
+      </p>
+
+      <h2>Contact</h2>
+      <p>
+        <Company />
+        {site.address ? <>, {site.address}</> : null}
+        {site.supportEmail ? (
+          <>
+            . Email <a href={`mailto:${site.supportEmail}`}>{site.supportEmail}</a>.
+          </>
+        ) : null}
+      </p>
+    </LegalPage>
+  );
+}

package/templates/backend/mobile/apps/api/app/error.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { type ErrorBoundaryProps } from "@pylonsync/react";
+
+// The error boundary sits at the root, outside the route group, so it still
+// renders if a layout itself throws. It is hydrated, so `reset()` works.
+export default function ErrorBoundary({ error, reset }: ErrorBoundaryProps) {
+  return (
+    <div className="mx-auto max-w-3xl px-6 py-24 text-center">
+      <h1 className="text-3xl font-semibold tracking-[-0.02em]">
+        Something went wrong
+      </h1>
+      <p className="mt-3 text-[15px] text-ink-muted">{error.message}</p>
+      {error.digest ? (
+        <p className="mt-1 text-[12px] text-ink-muted">
+          Reference: <code className="font-mono">{error.digest}</code>
+        </p>
+      ) : null}
+      <button
+        type="button"
+        onClick={reset}
+        className="mt-8 rounded-xl bg-ink px-5 py-3 text-[14px] font-medium text-surface transition-opacity hover:opacity-90"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}

package/templates/backend/mobile/apps/api/app/globals.css

@@ -0,0 +1,87 @@
+@import "tailwindcss";
+
+/* Tailwind v4 scans these globs for class names. Add a line if you put
+   markup somewhere else. */
+@source "../app/**/*.{tsx,ts,jsx,js}";
+@source "../components/**/*.{tsx,ts,jsx,js}";
+@source "../lib/**/*.{tsx,ts,jsx,js}";
+
+/* The whole site re-themes from these. `--brand` is the accent on buttons
+   and links; the ink/surface pair carries everything else. */
+:root {
+  --brand: #4f46e5;
+  --brand-ink: #ffffff;
+  --brand-soft: #eef2ff;
+  --ink: #18181b;
+  --ink-muted: #52525b;
+  --surface: #ffffff;
+  --surface-soft: #fafafa;
+  --line: #e4e4e7;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --brand: #818cf8;
+    --brand-ink: #1e1b4b;
+    --brand-soft: #1e1b4b;
+    --ink: #fafafa;
+    --ink-muted: #a1a1aa;
+    --surface: #09090b;
+    --surface-soft: #131316;
+    --line: #27272a;
+  }
+}
+
+@theme inline {
+  --color-brand: var(--brand);
+  --color-brand-ink: var(--brand-ink);
+  --color-brand-soft: var(--brand-soft);
+  --color-ink: var(--ink);
+  --color-ink-muted: var(--ink-muted);
+  --color-surface: var(--surface);
+  --color-surface-soft: var(--surface-soft);
+  --color-line: var(--line);
+  --font-sans:
+    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+/* Long-form legal copy. The legal pages are plain prose, so style the
+   elements once here instead of putting a class on every paragraph. */
+.prose-legal > * + * {
+  margin-top: 1rem;
+}
+.prose-legal h2 {
+  margin-top: 2.5rem;
+  font-size: 1.125rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  color: var(--ink);
+}
+.prose-legal p,
+.prose-legal li {
+  color: var(--ink-muted);
+  line-height: 1.7;
+}
+.prose-legal ul {
+  margin-left: 1.125rem;
+  list-style: disc;
+}
+.prose-legal li + li {
+  margin-top: 0.375rem;
+}
+.prose-legal a {
+  color: var(--brand);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}

package/templates/backend/mobile/apps/api/app/layout.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+
+interface LayoutProps {
+  children: React.ReactNode;
+}
+
+/**
+ * The document shell. Chrome lives in the section layout
+ * (`app/(site)/layout.tsx`), which is what wraps the pages with the header
+ * and footer. Tailwind's compiled stylesheet is injected into <head> by the
+ * runtime.
+ *
+ * No <title> here on purpose: each page exports its own `metadata`, and a
+ * title in the layout would render first and win.
+ */
+export default function RootLayout({ children }: LayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="color-scheme" content="light dark" />
+      </head>
+      <body className="min-h-screen bg-surface text-ink">{children}</body>
+    </html>
+  );
+}

package/templates/backend/mobile/apps/api/app/robots.ts

@@ -0,0 +1,13 @@
+import type { Robots } from "@pylonsync/react";
+import { site } from "@/lib/site";
+
+// app/robots.ts → served at /robots.txt.
+const SITE = site.url || process.env.SITE_URL || "http://localhost:4321";
+
+export default function robots(): Robots {
+  return {
+    // The API is not for crawlers; the marketing and legal pages are.
+    rules: { userAgent: "*", allow: "/", disallow: ["/api/"] },
+    sitemap: `${SITE}/sitemap.xml`,
+  };
+}

package/templates/backend/mobile/apps/api/app/sitemap.ts

@@ -0,0 +1,16 @@
+import type { Sitemap } from "@pylonsync/react";
+import { site } from "@/lib/site";
+
+// app/sitemap.ts → served at /sitemap.xml. This is a server-only route
+// module, never bundled for the browser, so reading process.env here is
+// safe (page components cannot).
+const SITE = site.url || process.env.SITE_URL || "http://localhost:4321";
+
+export default function sitemap(): Sitemap {
+  return [
+    { url: `${SITE}/`, changeFrequency: "weekly", priority: 1 },
+    { url: `${SITE}/support`, changeFrequency: "monthly", priority: 0.5 },
+    { url: `${SITE}/privacy`, changeFrequency: "yearly", priority: 0.3 },
+    { url: `${SITE}/terms`, changeFrequency: "yearly", priority: 0.3 },
+  ];
+}

package/templates/backend/mobile/apps/api/app.ts

@@ -1,6 +1,7 @@
 import {
   auth,
   buildManifest,
+  discoverAppRoutes,
   discoverFunctions,
   entity,
   field,
@@ -73,8 +74,11 @@ const manifest = buildManifest({
   // register each twice.
   actions: fns.actions,
   policies: [userPolicy, notePolicy, ...purchases.manifest.policies],
-  // API only: the Expo app is the frontend.
-  routes: [],
+  // The public website: landing page, support, privacy policy, and terms,
+  // under `app/`. One Pylon server answers the Expo app's API calls AND
+  // serves these pages, so the legal URLs both stores demand are live on the
+  // same host as soon as you deploy. Content lives in `lib/site.ts`.
+  routes: await discoverAppRoutes(),
   // Email/password + magic codes are on by default. Native sign-in needs
   // the app's ids on the server: PYLON_APPLE_NATIVE_CLIENT_IDS (the iOS
   // bundle id) and PYLON_GOOGLE_NATIVE_CLIENT_IDS (the iOS + Android OAuth

package/templates/backend/mobile/apps/api/components/legal.tsx

@@ -0,0 +1,64 @@
+import React from "react";
+import { site } from "@/lib/site";
+
+/**
+ * The frame both legal pages share: title, effective date, and the notice
+ * that this text is a starting point rather than reviewed legal advice.
+ *
+ * The notice is shown until `lib/site.ts` has your company details, on the
+ * same principle as the banner in the site layout: unfinished legal text
+ * should say so.
+ */
+export function LegalPage({
+  title,
+  children,
+}: {
+  title: string;
+  children: React.ReactNode;
+}) {
+  const unfinished = !site.company || !site.supportEmail || !site.address;
+  return (
+    <article className="mx-auto max-w-3xl px-6 py-16 sm:py-20">
+      <h1 className="text-3xl font-semibold tracking-[-0.02em]">{title}</h1>
+      <p className="mt-3 text-[13px] text-ink-muted">
+        Effective {formatDate(site.legalEffective)}
+        {site.company ? ` · ${site.company}` : ""}
+      </p>
+      {unfinished ? (
+        <p className="mt-8 rounded-xl border border-amber-300 bg-amber-50 px-4 py-3 text-[13px] leading-relaxed text-amber-900">
+          Draft. This text describes what the app in this template actually
+          does, which makes it a useful starting point, but it has not been
+          reviewed by a lawyer and it does not know your business. Fill in
+          <code className="mx-1 font-mono">lib/site.ts</code>, read every
+          section, and have counsel check it before you submit to a store.
+        </p>
+      ) : null}
+      <div className="prose-legal mt-10">{children}</div>
+      <p className="mt-12 border-t border-line pt-6 text-[13px] text-ink-muted">
+        Questions about this page?{" "}
+        {site.supportEmail ? (
+          <a href={`mailto:${site.supportEmail}`}>{site.supportEmail}</a>
+        ) : (
+          "Add a support address in lib/site.ts."
+        )}
+      </p>
+    </article>
+  );
+}
+
+/** The legal entity, or a visible placeholder while the config is blank. */
+export function Company() {
+  return <>{site.company || "[your company]"}</>;
+}
+
+function formatDate(iso: string): string {
+  // Build from the parts. `new Date("2026-01-01")` parses as UTC midnight and
+  // renders as the day before in any negative-UTC timezone.
+  const [y, m, d] = iso.split("-").map(Number);
+  if (!y || !m || !d) return iso;
+  return new Date(y, m - 1, d).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+}

package/templates/backend/mobile/apps/api/lib/site.ts

@@ -0,0 +1,94 @@
+/**
+ * Everything the marketing and legal pages read. This is the one file to
+ * edit when you rename the app, add store links, or fill in your company
+ * details.
+ *
+ * It is a plain module, not env vars, on purpose: SSR pages are bundled for
+ * hydration and the bundler rewrites `process.env.*`, so page code cannot
+ * read arbitrary env at render time. Server-only route modules
+ * (app/sitemap.ts, app/robots.ts) can, and do.
+ */
+
+export const site = {
+  /** Shown in the header, the page titles, and the legal pages. */
+  name: "__APP_NAME__",
+  /** The hero headline. One sentence, what the app does for the person. */
+  tagline: "Your notes, on every device, the moment you write them",
+  /** The line under the headline, and the meta description. */
+  description:
+    "__APP_NAME__ keeps your notes in sync across your phone, tablet, and anything else you sign in on. It works offline and catches up when you are back.",
+
+  /**
+   * The public URL of this site once deployed, with no trailing slash.
+   * `pylon deploy` prints the host. Used for canonical links and the
+   * sitemap, and by the mobile app when it opens the legal pages.
+   */
+  url: "",
+
+  /** The legal entity that publishes the app. Appears on both legal pages. */
+  company: "",
+  /** Where support email and legal notices go. */
+  supportEmail: "",
+  /** Postal address. Apple asks for one on the privacy policy. */
+  address: "",
+  /** The law that governs the terms, e.g. "the State of Texas, USA". */
+  governingLaw: "",
+  /** Date the current legal text took effect, as YYYY-MM-DD. */
+  legalEffective: "2026-01-01",
+
+  /** Store links. Empty renders a "coming soon" state instead of a dead link. */
+  appStoreUrl: "",
+  playStoreUrl: "",
+
+  /** The three or four things worth saying on the landing page. */
+  features: [
+    {
+      title: "Write now, sync later",
+      body: "Notes save on your device first, so the app never waits on a network. They reach your other devices as soon as there is one.",
+    },
+    {
+      title: "Start without an account",
+      body: "Open the app and use it. Sign in when you want your notes on a second device, and everything you already wrote comes with you.",
+    },
+    {
+      title: "Yours to delete",
+      body: "Delete your account in Settings and your notes go with it. No support ticket, no waiting.",
+    },
+  ],
+
+  /** Free tier and subscription, kept honest with what the app enforces. */
+  pricing: {
+    freeLimit: 10,
+    proBlurb: "Unlimited notes and everything shipped next.",
+  },
+
+  faq: [
+    {
+      q: "Do I need an account?",
+      a: "No. The app works straight away. Signing in keeps your notes if you switch phones.",
+    },
+    {
+      q: "How do I cancel a subscription?",
+      a: "Subscriptions are billed by Apple or Google, so cancel from your App Store or Play Store account. Access lasts until the end of the period you paid for.",
+    },
+    {
+      q: "What happens to my notes if I delete my account?",
+      a: "They are deleted with it. Settings has the button, and it takes effect immediately.",
+    },
+  ],
+} as const;
+
+/**
+ * Config the site cannot honestly render without. The header shows a notice
+ * while any of these are blank, so an unfinished site cannot quietly go live
+ * with placeholder legal text.
+ */
+export function missingSiteConfig(): string[] {
+  const missing: string[] = [];
+  if (!site.url) missing.push("url");
+  if (!site.company) missing.push("company");
+  if (!site.supportEmail) missing.push("supportEmail");
+  if (!site.address) missing.push("address");
+  if (!site.governingLaw) missing.push("governingLaw");
+  return missing;
+}

package/templates/backend/mobile/apps/api/package.json

@@ -13,11 +13,18 @@
   "dependencies": {
     "@pylonsync/sdk": "^__PYLON_VERSION__",
     "@pylonsync/functions": "^__PYLON_VERSION__",
-    "@pylonsync/revenuecat": "^__PYLON_VERSION__"
+    "@pylonsync/react": "^__PYLON_VERSION__",
+    "@pylonsync/revenuecat": "^__PYLON_VERSION__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "@tailwindcss/cli": "^4.3.0"
   },
   "devDependencies": {
     "@pylonsync/cli": "^__PYLON_VERSION__",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "typescript": "^5.6.0"
   }
 }

package/templates/backend/mobile/apps/api/tsconfig.json

@@ -3,11 +3,15 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "noEmit": true,
-    "types": ["node"]
+    "lib": ["ES2022", "DOM"],
+    "types": ["react", "react-dom", "node"],
+    "baseUrl": ".",
+    "paths": { "@/*": ["./*"] }
   },
-  "include": ["app.ts", "functions", "lib"]
+  "include": ["app.ts", "app/**/*", "components/**/*", "functions/**/*", "lib/**/*"]
 }

package/templates/barebones/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/chat/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`.