@pylonsync/create-pylon 0.3.372 → 0.3.374

package/templates/local-service/app/(marketing)/layout.tsx

@@ -0,0 +1,119 @@
+import React from "react";
+import { Link, type PageAuth } from "@pylonsync/react";
+import { siteConfig } from "@/lib/site.config";
+
+// `(marketing)` is a ROUTE GROUP: the parens segment is stripped from every
+// URL (so `(marketing)/page.tsx` still serves `/`), and this layout wraps only
+// the pages inside the group — a slim nav and a footer, both driven by
+// lib/site.config.ts. /login and /dashboard sit outside the group and render
+// bare in the root shell. `auth.user_id` is resolved server-side from the
+// session cookie before any HTML is sent, so the owner sees "Dashboard" and
+// everyone else sees "Sign in" — no flash, no client fetch.
+interface LayoutProps {
+  children: React.ReactNode;
+  auth: PageAuth;
+}
+
+export default function MarketingLayout({ children, auth }: LayoutProps) {
+  // A guest session (minted by <EnsureGuest> for the live picker) has a
+  // `guest_…` user id — that's an anonymous visitor, NOT the signed-in owner,
+  // so it shouldn't flip the nav to "Dashboard".
+  const signedIn = Boolean(auth?.user_id && !auth.user_id.startsWith("guest_"));
+  const { brand } = siteConfig;
+
+  return (
+    <>
+      <header className="sticky top-0 z-30 border-b border-zinc-200/70 bg-white/85 backdrop-blur">
+        <div className="mx-auto flex h-14 max-w-5xl items-center justify-between px-6">
+          <Link href="/" className="flex items-center gap-2">
+            <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
+              {brand.letter}
+            </span>
+            <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
+              {brand.name}
+            </span>
+          </Link>
+          <nav className="flex items-center gap-2">
+            <a
+              href="/#services"
+              className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
+            >
+              Services
+            </a>
+            {signedIn ? (
+              <Link
+                href="/dashboard"
+                className="inline-flex items-center rounded-full bg-zinc-900 px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:bg-zinc-700"
+              >
+                Dashboard
+              </Link>
+            ) : (
+              <>
+                <Link
+                  href="/login"
+                  className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
+                >
+                  Sign in
+                </Link>
+                <a
+                  href="/#book"
+                  className="inline-flex items-center rounded-full bg-brand px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:opacity-90"
+                >
+                  {siteConfig.hero.ctaLabel}
+                </a>
+              </>
+            )}
+          </nav>
+        </div>
+      </header>
+
+      <main className="flex-1">{children}</main>
+
+      <SiteFooter />
+    </>
+  );
+}
+
+function SiteFooter() {
+  const { brand, location } = siteConfig;
+  return (
+    <footer className="border-t border-zinc-200/70 bg-white">
+      <div className="mx-auto max-w-5xl px-6 py-12">
+        <div className="flex flex-col items-start justify-between gap-6 sm:flex-row">
+          <div className="max-w-sm">
+            <Link href="/" className="inline-flex items-center gap-2">
+              <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
+                {brand.letter}
+              </span>
+              <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
+                {brand.name}
+              </span>
+            </Link>
+            <p className="mt-3 text-[13px] leading-relaxed text-zinc-500">
+              {brand.footerBlurb}
+            </p>
+          </div>
+          <div className="text-[13px] leading-relaxed text-zinc-500">
+            <div className="font-medium text-zinc-900">Visit</div>
+            <p className="mt-2 max-w-[14rem]">{location.address}</p>
+            <p className="mt-2">{location.phone}</p>
+            <a href={`mailto:${brand.email}`} className="mt-1 inline-block hover:text-zinc-900">
+              {brand.email}
+            </a>
+          </div>
+        </div>
+        <div className="mt-10 flex flex-col items-start justify-between gap-3 border-t border-zinc-200/70 pt-6 text-[12px] text-zinc-400 sm:flex-row sm:items-center">
+          <span>
+            © {new Date().getFullYear()} {brand.copyrightName}
+          </span>
+          <span>
+            Built with{" "}
+            <a href="https://pylonsync.com" className="font-medium text-zinc-600 hover:text-zinc-900">
+              Pylon
+            </a>
+          </span>
+        </div>
+      </div>
+    </footer>
+  );
+}

package/templates/local-service/app/(marketing)/not-found.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { Link, type NotFoundProps } from "@pylonsync/react";
+
+// `(marketing)/not-found.tsx` → rendered at HTTP 404 for any unmatched URL
+// (and when a page calls `response.notFound()`). It lives inside the
+// `(marketing)` group on purpose: a group segment adds no URL prefix, so this
+// is still the root 404 boundary, but it wraps in the marketing layout — a
+// missing URL gets the site nav + footer instead of a bare page. Hydrated, so
+// the link is a client nav.
+export default function NotFound(_props: NotFoundProps) {
+  return (
+    <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">
+      <h1 className="text-3xl font-semibold tracking-tight">404</h1>
+      <p className="mt-2 text-zinc-500">We couldn&apos;t find that page.</p>
+      <Link
+        href="/"
+        className="mt-6 inline-flex h-10 items-center rounded-full bg-zinc-900 px-5 text-sm font-medium text-white transition-colors hover:bg-zinc-700"
+      >
+        Back home
+      </Link>
+    </div>
+  );
+}

package/templates/local-service/app/{page.tsx → (marketing)/page.tsx}

@@ -21,7 +21,7 @@ export const metadata: Metadata = {
   },
 };
 
-// `app/page.tsx` → `/`. Server-rendered single-page site for an appointment
+// `app/(marketing)/page.tsx` → `/` (the group segment adds no URL prefix). Server-rendered single-page site for an appointment
 // business. Hero, services, reviews, location, and FAQ are static server HTML
 // (SEO + first paint); the booking section (#book) is a client island
 // (<BookingWidget>) with live slot availability. All copy comes from siteConfig.
@@ -69,7 +69,7 @@ export default function LandingPage() {
             <ImagePlaceholder
               shape="portrait"
               title="A photo of your shop"
-              hint="Swap for an <img> in app/page.tsx"
+              hint="Swap for an <img> in app/(marketing)/page.tsx"
             />
             <div className="absolute left-4 top-4">
               <LiveBadge>Availability updates live</LiveBadge>

package/templates/local-service/app/error.tsx

@@ -1,7 +1,9 @@
 import React from "react";
 import { type ErrorBoundaryProps } from "@pylonsync/react";
 
-// `app/error.tsx` → the error boundary for this segment. Hydrated + interactive:
+// `app/error.tsx` → the GLOBAL error boundary. Sitting at the app root
+// (outside the `(marketing)` group), it catches a throw from any section and
+// renders at HTTP 500 in the bare root shell. Hydrated + interactive:
 // `reset()` re-attempts the route. The thrown error reaches the client as
 // `{ message, digest }` only — the stack stays in the dev overlay / server logs.
 export default function Error({ error, reset }: ErrorBoundaryProps) {

package/templates/local-service/app/layout.tsx

@@ -1,30 +1,18 @@
 import React from "react";
-import { Link, type PageAuth } from "@pylonsync/react";
 import { siteConfig } from "@/lib/site.config";
 import { SectionScroller } from "@/components/section-scroller";
 
-// A layout wraps every page. This marketing layout renders a slim nav and a
-// footer, both driven by lib/site.config.ts. `auth.user_id` is resolved
-// server-side from the session cookie before any HTML is sent, so the owner
-// sees "Dashboard" and everyone else sees "Sign in" — no flash, no client fetch.
 interface LayoutProps {
   children: React.ReactNode;
-  url: string;
-  auth: PageAuth;
 }
 
-export default function RootLayout({ children, url, auth }: LayoutProps) {
-  // A guest session (minted by <EnsureGuest> for the live picker) has a
-  // `guest_…` user id — that's an anonymous visitor, NOT the signed-in owner,
-  // so it shouldn't flip the nav to "Dashboard".
-  const signedIn = Boolean(auth?.user_id && !auth.user_id.startsWith("guest_"));
-  const { brand, colors } = siteConfig;
-
-  // Auth + dashboard render bare (no marketing chrome). Match the path PREFIX.
-  const path = (url ?? "").split("?")[0];
-  const BARE_PREFIXES = ["/login", "/dashboard"];
-  const isBare = BARE_PREFIXES.some((p) => path === p || path.startsWith(p + "/"));
-
+// The root layout is only the document shell: <html>, <head>, <body>, and the
+// site-wide theme variables. Section chrome lives in route-group layouts —
+// `(marketing)/layout.tsx` adds the nav + footer for the marketing pages.
+// /login and /dashboard sit outside the group and render bare here: the auth
+// screen and the dashboard bring their own chrome.
+export default function RootLayout({ children }: LayoutProps) {
+  const { colors } = siteConfig;
   return (
     <html
       lang="en"
@@ -46,104 +34,8 @@ export default function RootLayout({ children, url, auth }: LayoutProps) {
       </head>
       <body className="flex min-h-screen flex-col bg-background text-foreground antialiased">
         <SectionScroller />
-        {isBare ? (
-          children
-        ) : (
-          <>
-            <header className="sticky top-0 z-30 border-b border-zinc-200/70 bg-white/85 backdrop-blur">
-              <div className="mx-auto flex h-14 max-w-5xl items-center justify-between px-6">
-                <Link href="/" className="flex items-center gap-2">
-                  <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
-                    {brand.letter}
-                  </span>
-                  <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
-                    {brand.name}
-                  </span>
-                </Link>
-                <nav className="flex items-center gap-2">
-                  <a
-                    href="/#services"
-                    className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
-                  >
-                    Services
-                  </a>
-                  {signedIn ? (
-                    <Link
-                      href="/dashboard"
-                      className="inline-flex items-center rounded-full bg-zinc-900 px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:bg-zinc-700"
-                    >
-                      Dashboard
-                    </Link>
-                  ) : (
-                    <>
-                      <Link
-                        href="/login"
-                        className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
-                      >
-                        Sign in
-                      </Link>
-                      <a
-                        href="/#book"
-                        className="inline-flex items-center rounded-full bg-brand px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:opacity-90"
-                      >
-                        {siteConfig.hero.ctaLabel}
-                      </a>
-                    </>
-                  )}
-                </nav>
-              </div>
-            </header>
-
-            <main className="flex-1">{children}</main>
-
-            <SiteFooter />
-          </>
-        )}
+        {children}
       </body>
     </html>
   );
 }
-
-function SiteFooter() {
-  const { brand, location } = siteConfig;
-  return (
-    <footer className="border-t border-zinc-200/70 bg-white">
-      <div className="mx-auto max-w-5xl px-6 py-12">
-        <div className="flex flex-col items-start justify-between gap-6 sm:flex-row">
-          <div className="max-w-sm">
-            <Link href="/" className="inline-flex items-center gap-2">
-              <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
-                {brand.letter}
-              </span>
-              <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
-                {brand.name}
-              </span>
-            </Link>
-            <p className="mt-3 text-[13px] leading-relaxed text-zinc-500">
-              {brand.footerBlurb}
-            </p>
-          </div>
-          <div className="text-[13px] leading-relaxed text-zinc-500">
-            <div className="font-medium text-zinc-900">Visit</div>
-            <p className="mt-2 max-w-[14rem]">{location.address}</p>
-            <p className="mt-2">{location.phone}</p>
-            <a href={`mailto:${brand.email}`} className="mt-1 inline-block hover:text-zinc-900">
-              {brand.email}
-            </a>
-          </div>
-        </div>
-        <div className="mt-10 flex flex-col items-start justify-between gap-3 border-t border-zinc-200/70 pt-6 text-[12px] text-zinc-400 sm:flex-row sm:items-center">
-          <span>
-            © {new Date().getFullYear()} {brand.copyrightName}
-          </span>
-          <span>
-            Built with{" "}
-            <a href="https://pylonsync.com" className="font-medium text-zinc-600 hover:text-zinc-900">
-              Pylon
-            </a>
-          </span>
-        </div>
-      </div>
-    </footer>
-  );
-}

package/templates/local-service/app/login/page.tsx

@@ -8,8 +8,9 @@ export const metadata: Metadata = {
   robots: "noindex",
 };
 
-// `app/login/page.tsx` → `/login`. The owner's sign-in. Rendered bare (the
-// layout suppresses the marketing nav/footer for /login). Already signed in?
+// `app/login/page.tsx` → `/login`. The owner's sign-in. Rendered bare —
+// /login sits outside the `(marketing)` route group, so no marketing nav or
+// footer. Already signed in?
 // Skip straight to the dashboard — `response.redirect` in the synchronous shell
 // render is a real 307 before any HTML is sent.
 export default function LoginPage({ auth, response }: PageProps) {

package/templates/local-service/components/marketing.tsx

@@ -100,7 +100,7 @@ export function initials(name: string) {
 //
 //   shape  — "landscape" | "portrait" | "square" | "circle"
 //   title  — what photo belongs here ("A photo of your shop")
-//   hint   — how to replace it ("Swap for an <img> in app/page.tsx")
+//   hint   — how to replace it ("Swap for an <img> in app/(marketing)/page.tsx")
 export function ImagePlaceholder({
   shape = "landscape",
   title,

package/templates/marketplace/AGENTS.md

@@ -6,7 +6,7 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 
 **Unified SSR app:**
 - `app.ts`: data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))`.
-- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. A `(group)` directory is stripped from the URL — `app/(marketing)/about/page.tsx` still serves `/about` — so a group's `layout.tsx` gives one section its own chrome (nav, footer) without changing any path; routes outside the group render without it. `app/layout.tsx` is the document shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
 - `app/globals.css`: Tailwind v4 entrypoint (auto-compiled and injected).
 - `functions/`: server functions, one per file, `default`-exported.
 - `.pylon/`: local dev state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
@@ -33,7 +33,9 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 - **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"`; `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
-- **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
+- **`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.stream.write(text)` reaches only the one client holding the HTTP response; `ctx.rooms.broadcast(room, topic, data)` reaches every subscriber of the room.** Broadcast is what makes agent output survive a closed tab or reach a second device. It 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/*`; 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/projects/AGENTS.md

@@ -6,7 +6,7 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 
 **Unified SSR app:**
 - `app.ts`: data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))`.
-- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. A `(group)` directory is stripped from the URL — `app/(marketing)/about/page.tsx` still serves `/about` — so a group's `layout.tsx` gives one section its own chrome (nav, footer) without changing any path; routes outside the group render without it. `app/layout.tsx` is the document shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
 - `app/globals.css`: Tailwind v4 entrypoint (auto-compiled and injected).
 - `functions/`: server functions, one per file, `default`-exported.
 - `.pylon/`: local dev state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
@@ -33,7 +33,9 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 - **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"`; `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
-- **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
+- **`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.stream.write(text)` reaches only the one client holding the HTTP response; `ctx.rooms.broadcast(room, topic, data)` reaches every subscriber of the room.** Broadcast is what makes agent output survive a closed tab or reach a second device. It 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/*`; 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/restaurant/AGENTS.md

@@ -6,7 +6,7 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 
 **Unified SSR app:**
 - `app.ts`: data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))`.
-- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. A `(group)` directory is stripped from the URL — `app/(marketing)/about/page.tsx` still serves `/about` — so a group's `layout.tsx` gives one section its own chrome (nav, footer) without changing any path; routes outside the group render without it. `app/layout.tsx` is the document shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
 - `app/globals.css`: Tailwind v4 entrypoint (auto-compiled and injected).
 - `functions/`: server functions, one per file, `default`-exported.
 - `.pylon/`: local dev state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
@@ -33,7 +33,9 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 - **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"`; `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
-- **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
+- **`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.stream.write(text)` reaches only the one client holding the HTTP response; `ctx.rooms.broadcast(room, topic, data)` reaches every subscriber of the room.** Broadcast is what makes agent output survive a closed tab or reach a second device. It 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/*`; 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/restaurant/app/(marketing)/layout.tsx

@@ -0,0 +1,119 @@
+import React from "react";
+import { Link, type PageAuth } from "@pylonsync/react";
+import { siteConfig } from "@/lib/site.config";
+
+// `(marketing)` is a ROUTE GROUP: the parens segment is stripped from every
+// URL (so `(marketing)/page.tsx` still serves `/`), and this layout wraps only
+// the pages inside the group — a slim nav and a footer, both driven by
+// lib/site.config.ts. /login and /dashboard sit outside the group and render
+// bare in the root shell. `auth.user_id` is resolved server-side from the
+// session cookie before any HTML is sent, so the owner sees "Dashboard" and
+// everyone else sees "Sign in" — no flash, no client fetch.
+interface LayoutProps {
+  children: React.ReactNode;
+  auth: PageAuth;
+}
+
+export default function MarketingLayout({ children, auth }: LayoutProps) {
+  // A guest session (minted by <EnsureGuest> for the live picker) has a
+  // `guest_…` user id — that's an anonymous visitor, NOT the signed-in owner,
+  // so it shouldn't flip the nav to "Dashboard".
+  const signedIn = Boolean(auth?.user_id && !auth.user_id.startsWith("guest_"));
+  const { brand } = siteConfig;
+
+  return (
+    <>
+      <header className="sticky top-0 z-30 border-b border-zinc-200/70 bg-white/85 backdrop-blur">
+        <div className="mx-auto flex h-14 max-w-5xl items-center justify-between px-6">
+          <Link href="/" className="flex items-center gap-2">
+            <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
+              {brand.letter}
+            </span>
+            <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
+              {brand.name}
+            </span>
+          </Link>
+          <nav className="flex items-center gap-2">
+            <a
+              href="/#menu"
+              className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
+            >
+              Services
+            </a>
+            {signedIn ? (
+              <Link
+                href="/dashboard"
+                className="inline-flex items-center rounded-full bg-zinc-900 px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:bg-zinc-700"
+              >
+                Dashboard
+              </Link>
+            ) : (
+              <>
+                <Link
+                  href="/login"
+                  className="hidden rounded-full px-3 py-1.5 text-[13px] font-medium text-zinc-600 transition-colors hover:text-zinc-900 sm:inline-flex"
+                >
+                  Sign in
+                </Link>
+                <a
+                  href="/#reserve"
+                  className="inline-flex items-center rounded-full bg-brand px-3.5 py-1.5 text-[13px] font-medium text-white transition-colors hover:opacity-90"
+                >
+                  {siteConfig.hero.ctaLabel}
+                </a>
+              </>
+            )}
+          </nav>
+        </div>
+      </header>
+
+      <main className="flex-1">{children}</main>
+
+      <SiteFooter />
+    </>
+  );
+}
+
+function SiteFooter() {
+  const { brand, location } = siteConfig;
+  return (
+    <footer className="border-t border-zinc-200/70 bg-white">
+      <div className="mx-auto max-w-5xl px-6 py-12">
+        <div className="flex flex-col items-start justify-between gap-6 sm:flex-row">
+          <div className="max-w-sm">
+            <Link href="/" className="inline-flex items-center gap-2">
+              <span className="flex size-6 items-center justify-center rounded-[7px] bg-zinc-900 text-[13px] font-bold text-white">
+                {brand.letter}
+              </span>
+              <span className="text-[15px] font-semibold tracking-tight text-zinc-900">
+                {brand.name}
+              </span>
+            </Link>
+            <p className="mt-3 text-[13px] leading-relaxed text-zinc-500">
+              {brand.footerBlurb}
+            </p>
+          </div>
+          <div className="text-[13px] leading-relaxed text-zinc-500">
+            <div className="font-medium text-zinc-900">Visit</div>
+            <p className="mt-2 max-w-[14rem]">{location.address}</p>
+            <p className="mt-2">{location.phone}</p>
+            <a href={`mailto:${brand.email}`} className="mt-1 inline-block hover:text-zinc-900">
+              {brand.email}
+            </a>
+          </div>
+        </div>
+        <div className="mt-10 flex flex-col items-start justify-between gap-3 border-t border-zinc-200/70 pt-6 text-[12px] text-zinc-400 sm:flex-row sm:items-center">
+          <span>
+            © {new Date().getFullYear()} {brand.copyrightName}
+          </span>
+          <span>
+            Built with{" "}
+            <a href="https://pylonsync.com" className="font-medium text-zinc-600 hover:text-zinc-900">
+              Pylon
+            </a>
+          </span>
+        </div>
+      </div>
+    </footer>
+  );
+}

package/templates/restaurant/app/(marketing)/not-found.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { Link, type NotFoundProps } from "@pylonsync/react";
+
+// `(marketing)/not-found.tsx` → rendered at HTTP 404 for any unmatched URL
+// (and when a page calls `response.notFound()`). It lives inside the
+// `(marketing)` group on purpose: a group segment adds no URL prefix, so this
+// is still the root 404 boundary, but it wraps in the marketing layout — a
+// missing URL gets the site nav + footer instead of a bare page. Hydrated, so
+// the link is a client nav.
+export default function NotFound(_props: NotFoundProps) {
+  return (
+    <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">
+      <h1 className="text-3xl font-semibold tracking-tight">404</h1>
+      <p className="mt-2 text-zinc-500">We couldn&apos;t find that page.</p>
+      <Link
+        href="/"
+        className="mt-6 inline-flex h-10 items-center rounded-full bg-zinc-900 px-5 text-sm font-medium text-white transition-colors hover:bg-zinc-700"
+      >
+        Back home
+      </Link>
+    </div>
+  );
+}

package/templates/restaurant/app/{page.tsx → (marketing)/page.tsx}

@@ -17,7 +17,7 @@ export const metadata: Metadata = {
   openGraph: { title: siteConfig.seo.title, description: siteConfig.seo.description, type: "website" },
 };
 
-// `app/page.tsx` → `/`. Server-rendered single-page restaurant site. Hero, menu,
+// `app/(marketing)/page.tsx` → `/` (the group segment adds no URL prefix). Server-rendered single-page restaurant site. Hero, menu,
 // reviews, location, and FAQ are static server HTML (SEO + first paint); the
 // reservation section (#reserve) is a client island with live table
 // availability. All copy comes from siteConfig. Doesn't read `auth`, so the
@@ -54,7 +54,7 @@ export default function LandingPage() {
             <ImagePlaceholder
               shape="portrait"
               title="A photo of your dining room"
-              hint="Swap for an <img> in app/page.tsx"
+              hint="Swap for an <img> in app/(marketing)/page.tsx"
             />
             <div className="absolute left-4 top-4">
               <LiveBadge>Tables update live</LiveBadge>

package/templates/restaurant/app/error.tsx

@@ -1,7 +1,9 @@
 import React from "react";
 import { type ErrorBoundaryProps } from "@pylonsync/react";
 
-// `app/error.tsx` → the error boundary for this segment. Hydrated + interactive:
+// `app/error.tsx` → the GLOBAL error boundary. Sitting at the app root
+// (outside the `(marketing)` group), it catches a throw from any section and
+// renders at HTTP 500 in the bare root shell. Hydrated + interactive:
 // `reset()` re-attempts the route. The thrown error reaches the client as
 // `{ message, digest }` only — the stack stays in the dev overlay / server logs.
 export default function Error({ error, reset }: ErrorBoundaryProps) {