@pylonsync/create-pylon 0.3.372 → 0.3.374

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.372",
+  "version": "0.3.374",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"

package/templates/_root/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 development state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
@@ -25,7 +25,9 @@ Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from o
 - **Policies deny by default; server functions bypass them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full database access, so enforce trust with `ctx.auth` checks inside the handler.
 - **`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` or `<Suspense>`. The HTTP head commits when the shell is ready. Status, headers, and cookies set from a suspended subtree are lost, and `redirect` or `notFound` thrown below a Suspense boundary are swallowed.
-- **`ctx.llm` and `ctx.connections` are available on mutations and actions, not queries.** An `action` has no direct `ctx.db`; use `ctx.runQuery` or `ctx.runMutation`.
+- **`ctx.llm`, `ctx.rooms`, and `ctx.connections` are available on mutations and actions, not queries.** An `action` has no direct `ctx.db`; use `ctx.runQuery` or `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`.
 - **There is no `ctx.files` or `defineWorkflow`/`defineJob`.** Files go through `<FileUpload>` + `/api/files/*`; deferred execution is `ctx.scheduler.runAfter/runAt/cancel`.
 

package/templates/agency/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/agency/app/(marketing)/layout.tsx

@@ -0,0 +1,136 @@
+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 up top and a footer below,
+// both driven by lib/site.config.ts. Routes outside the group (/login,
+// /dashboard) render bare in the root shell. `auth.user_id` is resolved
+// server-side from the session cookie before any HTML is sent, so the nav
+// shows "Dashboard" once the owner is signed in and "Sign in" otherwise —
+// 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 counter) 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-1 sm:gap-2">
+            <a href="/work" 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">
+              Work
+            </a>
+            <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="/#contact"
+                  className="inline-flex items-center rounded-full bg-brand px-3.5 py-1.5 text-[13px] font-medium text-white transition-opacity hover:opacity-90"
+                >
+                  {siteConfig.hero.ctaLabel}
+                </a>
+              </>
+            )}
+          </nav>
+        </div>
+      </header>
+
+      <main className="flex-1">{children}</main>
+
+      <SiteFooter />
+    </>
+  );
+}
+
+function SiteFooter() {
+  const { brand } = 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="flex items-center gap-4">
+            {brand.socials.map((s) => (
+              <a
+                key={s.label}
+                href={s.href}
+                aria-label={s.label}
+                className="text-zinc-400 transition-colors hover:text-zinc-900"
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+                  <path d={s.path} />
+                </svg>
+              </a>
+            ))}
+            <a
+              href={`mailto:${brand.email}`}
+              aria-label="Email"
+              className="text-zinc-400 transition-colors hover:text-zinc-900"
+            >
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                <rect x="3" y="5" width="18" height="14" rx="2" />
+                <path d="m3 7 9 6 9-6" />
+              </svg>
+            </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/{creator/app → agency/app/(marketing)}/not-found.tsx

@@ -1,8 +1,12 @@
 import React from "react";
 import { Link, type NotFoundProps } from "@pylonsync/react";
 
-// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when a
-// page calls `response.notFound()`). Hydrated, so the link is a client nav.
+// `(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">

package/templates/agency/app/error.tsx

@@ -1,9 +1,12 @@
 import React from "react";
 import { type ErrorBoundaryProps } from "@pylonsync/react";
 
-// `app/error.tsx` → the error boundary for this segment. 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.
+// `app/error.tsx` → the GLOBAL error boundary. Sitting at the app root
+// (outside the `(marketing)` group), it catches a throw from any section —
+// marketing, auth, or dashboard — 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) {
   return (
     <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">

package/templates/agency/app/layout.tsx

@@ -1,32 +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 up top
-// and a footer below, 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
-// nav shows "Dashboard" once the owner is signed in and "Sign in" otherwise —
-// 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 counter) 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;
-
-  // The auth screens and the dashboard bring their own chrome, so they render
-  // bare (no marketing nav/footer). Match on the path PREFIX, not a substring.
-  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 every marketing page.
+// Routes outside the group (/login, /dashboard) 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"
@@ -53,120 +39,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-1 sm:gap-2">
-                  <a href="/work" 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">
-                    Work
-                  </a>
-                  <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="/#contact"
-                        className="inline-flex items-center rounded-full bg-brand px-3.5 py-1.5 text-[13px] font-medium text-white transition-opacity hover:opacity-90"
-                      >
-                        {siteConfig.hero.ctaLabel}
-                      </a>
-                    </>
-                  )}
-                </nav>
-              </div>
-            </header>
-
-            <main className="flex-1">{children}</main>
-
-            <SiteFooter />
-          </>
-        )}
+        {children}
       </body>
     </html>
   );
 }
-
-function SiteFooter() {
-  const { brand } = 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="flex items-center gap-4">
-            {brand.socials.map((s) => (
-              <a
-                key={s.label}
-                href={s.href}
-                aria-label={s.label}
-                className="text-zinc-400 transition-colors hover:text-zinc-900"
-              >
-                <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
-                  <path d={s.path} />
-                </svg>
-              </a>
-            ))}
-            <a
-              href={`mailto:${brand.email}`}
-              aria-label="Email"
-              className="text-zinc-400 transition-colors hover:text-zinc-900"
-            >
-              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-                <rect x="3" y="5" width="18" height="14" rx="2" />
-                <path d="m3 7 9 6 9-6" />
-              </svg>
-            </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/agency/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. It sits outside the
+// `(marketing)` route group, so it renders bare — no marketing nav/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/ai-chat/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,28 @@ 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.
+
+Streaming agent turn — tokens to the caller, and to every device watching:
+
+```ts
+export default action({
+  args: { chatId: v.string(), messages: v.array(v.any()) },
+  timeout: 120, // streaming does not extend the deadline
+  async handler(ctx, { chatId, messages }) {
+    const res = await ctx.llm.stream({ messages }, (e) => {
+      if (e.type === "text_delta") {
+        ctx.stream.write(e.text);
+        void ctx.rooms.broadcast(`chat-${chatId}`, "agent.delta", { text: e.text });
+      }
+    });
+    return res.stop_reason; // "tool_use" → run the tools and call again
+  },
+});
+```
+
 - **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/ai-chat/app/(chat)/layout.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { Link, type PageAuth } from "@pylonsync/react";
+import { siteConfig } from "@/lib/site.config";
+
+// `(chat)` is a ROUTE GROUP: the parens segment is stripped from every URL
+// (so `(chat)/page.tsx` still serves `/`), and this layout wraps only the
+// pages inside the group. /login sits outside it and renders bare in the
+// root shell.
+//
+// App shell: a slim top bar over a full-height chat. `auth.user_id` is resolved
+// server-side from the session cookie before any HTML is sent, so the bar shows
+// the account / "Sign in" with no flash. The chat page fills the rest of the
+// viewport (h-[calc(100vh-3.5rem)] in chat-client.tsx — keep the header at h-14).
+interface LayoutProps {
+  children: React.ReactNode;
+  auth: PageAuth;
+}
+
+export default function ChatLayout({ children, auth }: LayoutProps) {
+  const signedIn = Boolean(auth?.user_id);
+  const { brand } = siteConfig;
+
+  return (
+    <>
+      <header className="flex h-14 items-center justify-between border-b border-zinc-200 bg-white px-4">
+        <Link href="/" className="flex items-center gap-2">
+          <span className="flex size-6 items-center justify-center rounded-[7px] bg-brand text-[13px] font-bold text-white">
+            {brand.letter}
+          </span>
+          <span className="text-[15px] font-semibold tracking-tight text-zinc-900">{brand.name}</span>
+        </Link>
+        {signedIn ? (
+          <span className="text-[13px] text-zinc-400">Signed in</span>
+        ) : (
+          <Link
+            href="/login"
+            className="rounded-full border border-zinc-300 px-3.5 py-1.5 text-[13px] font-medium text-zinc-700 transition-colors hover:bg-zinc-50"
+          >
+            Sign in
+          </Link>
+        )}
+      </header>
+      {children}
+    </>
+  );
+}

package/templates/ai-chat/app/{not-found.tsx → (chat)/not-found.tsx}

@@ -1,8 +1,11 @@
 import React from "react";
 import { Link, type NotFoundProps } from "@pylonsync/react";
 
-// `app/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and when a
-// page calls `response.notFound()`). Hydrated, so the link is a client nav.
+// `(chat)/not-found.tsx` → rendered at HTTP 404 for any unmatched URL (and
+// when a page calls `response.notFound()`). It lives inside the `(chat)` group
+// on purpose: a group segment adds no URL prefix, so this is still the root
+// 404 boundary, but it wraps in the app-shell layout — a missing URL gets the
+// top bar 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">

package/templates/ai-chat/app/error.tsx

@@ -1,9 +1,12 @@
 import React from "react";
 import { type ErrorBoundaryProps } from "@pylonsync/react";
 
-// `app/error.tsx` → the error boundary for this segment. 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.
+// `app/error.tsx` → the GLOBAL error boundary. Sitting at the app root
+// (outside the `(chat)` group), it catches a throw from any section — the chat
+// or /login — 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) {
   return (
     <div className="mx-auto flex min-h-[60vh] max-w-3xl flex-col items-center justify-center px-6 text-center">

package/templates/ai-chat/app/layout.tsx

@@ -1,24 +1,15 @@
 import React from "react";
-import { Link, type PageAuth } from "@pylonsync/react";
 import { siteConfig } from "@/lib/site.config";
 
-// App shell: a slim top bar over a full-height chat. `auth.user_id` is resolved
-// server-side from the session cookie before any HTML is sent, so the bar shows
-// the account / "Sign in" with no flash. The chat page fills the rest of the
-// viewport (h-[calc(100vh-3.5rem)] in chat-client.tsx — keep the header at h-14).
+// The root layout is only the document shell: <html>, <head>, <body>, and the
+// theme variables. The app shell (top bar) lives in the `(chat)` route-group
+// layout, so /login — outside the group — renders bare with its own chrome.
 interface LayoutProps {
   children: React.ReactNode;
-  url: string;
-  auth: PageAuth;
 }
 
-export default function RootLayout({ children, url, auth }: LayoutProps) {
-  const signedIn = Boolean(auth?.user_id);
-  const { brand, colors } = siteConfig;
-
-  // The auth screen brings its own chrome → render it bare.
-  const path = (url ?? "").split("?")[0];
-  const isBare = path === "/login" || path.startsWith("/login/");
+export default function RootLayout({ children }: LayoutProps) {
+  const { colors } = siteConfig;
 
   return (
     <html
@@ -40,31 +31,7 @@ export default function RootLayout({ children, url, auth }: LayoutProps) {
             no layout shift; change the family in app.ts. */}
       </head>
       <body className="bg-background text-foreground antialiased">
-        {isBare ? (
-          children
-        ) : (
-          <>
-            <header className="flex h-14 items-center justify-between border-b border-zinc-200 bg-white px-4">
-              <Link href="/" className="flex items-center gap-2">
-                <span className="flex size-6 items-center justify-center rounded-[7px] bg-brand text-[13px] font-bold text-white">
-                  {brand.letter}
-                </span>
-                <span className="text-[15px] font-semibold tracking-tight text-zinc-900">{brand.name}</span>
-              </Link>
-              {signedIn ? (
-                <span className="text-[13px] text-zinc-400">Signed in</span>
-              ) : (
-                <Link
-                  href="/login"
-                  className="rounded-full border border-zinc-300 px-3.5 py-1.5 text-[13px] font-medium text-zinc-700 transition-colors hover:bg-zinc-50"
-                >
-                  Sign in
-                </Link>
-              )}
-            </header>
-            {children}
-          </>
-        )}
+        {children}
       </body>
     </html>
   );

package/templates/ai-chat/app/login/page.tsx

@@ -9,7 +9,8 @@ export const metadata: Metadata = {
 };
 
 // `app/login/page.tsx` → `/login`. Sign-in is required to use the chat (chats
-// are tied to your account). Rendered bare. Already signed in? Skip back to the
+// are tied to your account). It sits outside the `(chat)` route group, so it
+// renders bare — no app top bar. Already signed in? Skip back to the
 // chat — `response.redirect` in the synchronous shell render is a real 307
 // before any HTML is sent.
 export default function LoginPage({ auth, response }: PageProps) {