@dashai/cli 0.20.0 → 0.21.0

package/dist/bin.js

@@ -2068,13 +2068,27 @@ import { AuthProvider, HostRouteSync } from '@dashai/sdk/auth/client';
 import { PlatformProvider, PLATFORM_PREPAINT_SCRIPT } from '@dashai/sdk/platform';
 import { ThemeProvider } from '@/components/theme-provider';
 import { PlatformThemeSync } from '@/components/platform-theme-sync';
+import { getSession } from '@/lib/session';
 
 export const metadata = {
   title: ${JSON.stringify(opts.name)},
   description: ${JSON.stringify(`Dashwise module: ${opts.slug}`)},
 };
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+// force-dynamic: the layout reads the session at render (below), which needs
+// DASHWISE_API_URL/KEY. \`next build\` prerenders with NO Dashwise env, so the
+// SDK would throw "missing apiBaseUrl" \u2192 BUILD_FAILED on first publish.
+// Required today; becomes optional once the SDK reads cookies before config.
+export const dynamic = 'force-dynamic';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  // Fetch the session ONCE, on the server, and hand it to <AuthProvider> as
+  // \`initialSession\`. Without it the provider fetches /api/auth/session from
+  // the browser after hydration: a second server invocation (and two more
+  // backend calls) on every page load before useSession() knows anything.
+  // \`getSession\` is React-\`cache\`d, so pages calling it in the same request
+  // reuse this result instead of asking the backend again.
+  const session = await getSession();
   return (
     // \`data-dw-surface="embedded"\` is the SERVER default: this module normally
     // renders inside the Dashwise app shell, where the header/nav/theme toggle
@@ -2100,10 +2114,12 @@ export default function RootLayout({ children }: { children: React.ReactNode })
                 Bridges the SDK to next-themes so the SDK stays theming-library
                 agnostic. Inert when standalone \u2014 your own toggle wins there. */}
             <PlatformThemeSync />
-            {/* sessionEndpoint points at the same-origin /api/auth/session
-                route so the host-scoped session cookie is actually sent \u2014
-                a cross-origin fetch to the API would drop it (D8). */}
-            <AuthProvider sessionEndpoint="/api/auth/session">
+            {/* initialSession: server-fetched above, so the provider skips
+                its mount-time fetch. sessionEndpoint stays for refresh():
+                it points at the same-origin /api/auth/session route so the
+                host-scoped session cookie is actually sent \u2014 a cross-origin
+                fetch to the API would drop it (D8). */}
+            <AuthProvider sessionEndpoint="/api/auth/session" initialSession={session}>
               {/* Mirrors in-module navigation to the Dashwise host's address
                   bar when embedded; inert when standalone. */}
               <HostRouteSync />
@@ -2139,58 +2155,86 @@ function appPageCustomTsx(opts) {
 // \`ModuleShell\` below encodes all of that. Anything that should appear only
 // when the module is opened on its own subdomain goes in \`.dw-standalone-only\`.
 // See CLAUDE.md \u2192 "Embedded-first UI" for the full contract.
-import { getServerSession } from '@dashai/sdk/auth/server';
+import { db } from '@dashai/generated';
+import { hasPermissionInSession } from '@dashai/sdk/auth/server';
 import { redirect } from 'next/navigation';
-import { PlusIcon } from 'lucide-react';
-import { Button } from '@/components/ui/button';
 import { ModuleShell } from '@/components/module-shell';
+import { NewItemForm } from '@/components/new-item-form';
 import { EmptyState } from '@/components/states';
+import { getSession } from '@/lib/session';
 
-// force-dynamic: this page calls getServerSession() at render, which
-// reads DASHWISE_API_URL/KEY. \`next build\` statically PRERENDERS pages by
+// force-dynamic: this page reads the session at render, which needs
+// DASHWISE_API_URL/KEY. \`next build\` statically PRERENDERS pages by
 // default and runs with NO Dashwise env, so the SDK would throw
 // "missing apiBaseUrl" and the platform's first publish would fail with
 // an opaque BUILD_FAILED. Opting into dynamic rendering skips prerender.
+// Required today; becomes optional once the SDK reads cookies before config.
 export const dynamic = 'force-dynamic';
 
 export default async function Home() {
-  const session = await getServerSession();
+  // \`getSession()\` is the per-request cached getServerSession(): the layout
+  // already started it, so awaiting it here costs no extra backend call.
+  const session = await getSession();
   if (!session) {
     redirect('/api/auth/sign-in?return_to=/');
   }
 
-  // Replace this with your real first screen: list what the user came to see,
-  // and render EmptyState only while there is genuinely nothing yet. Keep the
-  // loading state (ListSkeleton) and error state (ErrorState) \u2014 they're in
-  // components/states.tsx and they are what makes a module feel finished.
+  // The middleware only checks that a session cookie EXISTS, and the layout
+  // checks no permission \u2014 neither is the guard. What the user may see and
+  // do is a PERMISSION check: here, before any data is read, and again
+  // inside every Server Action (app/actions.ts), because hiding a button is
+  // not authorization. \`items:read\` / \`items:create\` are the per-table
+  // permissions the platform synthesizes when module.json has no \`rbac\`.
+  const canRead = hasPermissionInSession(session, 'items:read');
+  const canCreate = hasPermissionInSession(session, 'items:create');
+
+  // Read only what the user may see. With two or more independent reads,
+  // start them together after the check: \`await Promise.all([a(), b()])\`,
+  // never one await after another.
+  //
+  // \`db.items.list()\` with no \`limit\` returns ONE page of 100 rows and drops
+  // \`total\`. Pass a \`limit\`, use \`listPage()\` when you need the count, or
+  // paginate \u2014 never "read everything and filter in JS".
+  const items = canRead ? await db.items.list({ limit: 50 }) : [];
+
+  // Replace this with your real first screen. Keep the three states: the
+  // loading state is app/loading.tsx (ListSkeleton), errors land in
+  // app/error.tsx, and EmptyState covers "genuinely nothing yet".
   return (
-    <ModuleShell
-      title="${escapeHtml(opts.name)}"
-      primaryAction={
-        <Button>
-          <PlusIcon aria-hidden="true" />
-          Add item
-        </Button>
-      }
-    >
-      <EmptyState
-        title="Nothing here yet"
-        description="This is your module's home. Build the first screen in app/page.tsx \u2014 declare your tables with \`dashwise table create\`, then read them with the typed \`db\` client from @dashai/generated."
-        action={
-          <Button>
-            <PlusIcon aria-hidden="true" />
-            Add item
-          </Button>
-        }
-      />
+    <ModuleShell title="${escapeHtml(opts.name)}">
+      {canCreate ? <NewItemForm /> : null}
+      {!canRead ? (
+        <EmptyState
+          title="You can't see items yet"
+          description="Your role in this module doesn't include viewing items. Ask a workspace admin for access."
+        />
+      ) : items.length === 0 ? (
+        <EmptyState
+          title="Nothing here yet"
+          description="This is your module's home. Build the first screen in app/page.tsx \u2014 declare your tables with \`dashwise table create\`, then read them with the typed \`db\` client from @dashai/generated."
+        />
+      ) : (
+        <ul className="divide-y divide-border rounded-lg border border-border">
+          {items.map((item) => (
+            <li
+              key={item.id}
+              className="flex items-center justify-between gap-4 px-4 py-3 text-sm"
+            >
+              <span className="min-w-0 truncate">{item.title}</span>
+              {item.done ? (
+                <span className="shrink-0 text-muted-foreground">Done</span>
+              ) : null}
+            </li>
+          ))}
+        </ul>
+      )}
     </ModuleShell>
   );
 }
 `;
 }
 function appDashboardPageTsx() {
-  return `import { getServerSession } from '@dashai/sdk/auth/server';
-import { redirect } from 'next/navigation';
+  return `import { redirect } from 'next/navigation';
 import { LogOut, ShieldCheck } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { ModuleShell } from '@/components/module-shell';
@@ -2201,12 +2245,14 @@ import {
   CardHeader,
   CardTitle,
 } from '@/components/ui/card';
+import { getSession } from '@/lib/session';
 
 /**
  * An ADDITIONAL example route \u2014 your real home is app/page.tsx (\`/\`).
  * This \`/dashboard\` page shows a second auth-gated Server Component: keep
- * it, rename it, or delete it. The middleware ensures the user has a session
- * cookie before this page renders; \`getServerSession()\` validates the cookie
+ * it, rename it, or delete it. The middleware only ensures a session cookie
+ * EXISTS before this page renders; \`getSession()\` (lib/session.ts, a
+ * per-request cached \`getServerSession()\`) validates the cookie
  * against the backend's \`/api/auth/sessions/me\` endpoint, returning the
  * decoded \`Session\` (or \`null\` if stale).
  *
@@ -2215,13 +2261,15 @@ import {
  * Dashwise app the user menu already offers sign-out, so rendering our own
  * would duplicate the app's chrome. See CLAUDE.md \u2192 "Embedded-first UI".
  */
-// force-dynamic: same reason as app/page.tsx \u2014 this route calls
-// getServerSession() at render, which needs DASHWISE_API_URL/KEY. Static
-// prerender during \`next build\` runs with no env \u2192 BUILD_FAILED. Opt out.
+// force-dynamic: same reason as app/page.tsx \u2014 this route reads the session
+// (getSession() \u2192 getServerSession()) at render, which needs
+// DASHWISE_API_URL/KEY. Static prerender during \`next build\` runs with no
+// env \u2192 BUILD_FAILED. Opt out.
+// Required today; becomes optional once the SDK reads cookies before config.
 export const dynamic = 'force-dynamic';
 
 export default async function Dashboard() {
-  const session = await getServerSession();
+  const session = await getSession();
   if (!session) {
     redirect('/api/auth/sign-in?return_to=/');
   }
@@ -2602,26 +2650,44 @@ export async function POST(request: Request) {
 `;
 }
 function appApiItemsRouteTs() {
-  return `// Example data-plane route \u2014 lists + creates rows in the seeded
-// \`items\` table via the generated typed SDK. Delete this (and the
-// \`items\` table in module.json) once you add your own tables.
+  return `// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+//  EXAMPLE ROUTE \u2014 DELETE OR RENAME IT.
+//  It exists to show a guarded JSON route over the seeded \`items\` table.
+//  Delete this file (and the \`items\` table in module.json) once you add
+//  your own tables; your UI's writes belong in Server Actions
+//  (app/actions.ts in the full scaffold), not here.
+// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+//
+// Every route handler checks a PERMISSION. The middleware only checks that a
+// session cookie exists, and \`db\` talks to the Data Hub with the module's own
+// dwk_ key \u2014 so an unguarded route hands the module's full data access to
+// anyone who can reach the URL. \`withPermission\` answers 401 with no session
+// and 403 without the permission. \`items:read\` / \`items:create\` are the
+// per-table permissions the platform synthesizes when module.json has no
+// \`rbac\` block. Per-user rows also need an ownership check in the handler.
+//
+// A module scaffolded with \`--simple\` has no sign-in routes, so this answers
+// 401 until you add sign-in \u2014 that is the intended default.
 //
 // \`db\` comes from @dashai/generated, regenerated on every module.json
 // save by \`dashwise dev\`. Run it (or \`dashwise module generate\`) first.
 import { NextResponse } from 'next/server';
+import { withPermission } from '@dashai/sdk/auth/middleware';
 import { db } from '@dashai/generated';
 
-export async function GET() {
+export const GET = withPermission('items:read')(async () => {
   // \`db.<table>.list()\` resolves to the rows array itself \u2014 the typed
   // client unwraps the \`{ rows, total, ... }\` page envelope (see the
   // generated \`client/tables.d.ts\`: \`list(): Promise<ItemsRow[]>\`).
   // Don't reach for \`.rows\` here: it's \`undefined\` on an array, and
   // \`NextResponse.json(undefined)\` throws "Value is not JSON serializable".
+  // Without a \`limit\` it returns ONE page of 100; use \`listPage()\` for
+  // the total, or paginate.
   const rows = await db.items.list({ limit: 50 });
   return NextResponse.json(rows);
-}
+});
 
-export async function POST(request: Request) {
+export const POST = withPermission('items:create')(async (request) => {
   const body = (await request.json().catch(() => null)) as
     | { title?: unknown; done?: unknown }
     | null;
@@ -2635,7 +2701,7 @@ export async function POST(request: Request) {
   const done = typeof body?.done === 'boolean' ? body.done : false;
   const row = await db.items.create({ title, done });
   return NextResponse.json(row, { status: 201 });
-}
+});
 `;
 }
 function appApiAuthSessionTs() {
@@ -3471,6 +3537,151 @@ export default function Error({
 }
 `;
 }
+function libSessionTs() {
+  return `import { cache } from 'react';
+import { getServerSession } from '@dashai/sdk/auth/server';
+
+/**
+ * The current session (or \`null\`), fetched at most ONCE per request.
+ *
+ * \`getServerSession()\` is uncached and costs two backend round trips
+ * (session + RBAC). The root layout reads it to hydrate <AuthProvider>, and
+ * pages read it for their guard; React \`cache()\` makes the second caller
+ * reuse the first one's result within the same server render.
+ *
+ * Use this in layouts, pages and Server Components. Server Actions and route
+ * handlers run in their own request: guard those with
+ * \`requirePermission()\` / \`withPermission()\` instead.
+ */
+export const getSession = cache(() => getServerSession());
+`;
+}
+function appLoadingTsx() {
+  return `// Root loading state. Next.js shows this IMMEDIATELY on navigation while the
+// next page renders on the server (session + data reads), so the user gets
+// feedback within 100 ms instead of a frozen screen. Shaped like the content
+// that is coming: match \`rows\` and the row height to your real list, or it
+// visibly jumps on load. Add a loading.tsx per route segment when a screen's
+// shape differs from a list.
+import { ListSkeleton } from '@/components/states';
+
+export default function Loading() {
+  return (
+    <div className="mx-auto w-full max-w-6xl p-4 md:p-6">
+      <ListSkeleton />
+    </div>
+  );
+}
+`;
+}
+function appActionsTs() {
+  return `'use server';
+
+// Server Actions \u2014 the canonical WRITE path for this module.
+//
+// Every action follows the same four steps, in this order:
+//   1. Check a PERMISSION. The middleware only checks that a session cookie
+//      exists; it says nothing about what the user may do. A Server Action is
+//      a public POST endpoint \u2014 anyone with a cookie can call it directly,
+//      whatever your UI shows or hides.
+//   2. Validate the input (FormData is untrusted).
+//   3. Write through the generated \`db\` client (the module's server-side
+//      dwk_ key \u2014 never send that key to the browser).
+//   4. Revalidate ONE narrow path (or tag) \u2014 the screen that shows the data.
+//      Never call router.refresh() after it: revalidatePath already sends
+//      the fresh render back with the action's response, and a refresh
+//      re-renders everything a second time.
+//
+// Per-user data (rows that belong to one person) also needs an OWNERSHIP
+// check: store \`session.user.id\` on create, and on update/delete compare it
+// before writing. The dwk_ key is the module's ceiling, not a per-user rule.
+import { revalidatePath } from 'next/cache';
+import { requirePermission } from '@dashai/sdk/auth/server';
+import { db } from '@dashai/generated';
+
+export type CreateItemState = { error: string } | null;
+
+export async function createItem(
+  _prev: CreateItemState,
+  formData: FormData,
+): Promise<CreateItemState> {
+  // 1. Throws a DashwiseError (401 no session / 403 denied) \u2192 app/error.tsx.
+  //    The page only renders the form for users who hold the permission, so
+  //    reaching this throw means someone called the action directly.
+  await requirePermission('items:create');
+
+  // 2. Validate.
+  const raw = formData.get('title');
+  const title = typeof raw === 'string' ? raw.trim() : '';
+  if (!title) {
+    return { error: 'Give the item a title.' };
+  }
+
+  // 3. Write.
+  await db.items.create({ title, done: false });
+
+  // 4. One narrow revalidate: only the home page lists items.
+  revalidatePath('/');
+  return null;
+}
+`;
+}
+function componentsNewItemFormTsx() {
+  return `"use client";
+
+// The client half of the canonical write path (see app/actions.ts).
+//
+// Feedback within 100 ms: the submit button reads \`useFormStatus()\` and
+// switches to a pending state the moment the form is submitted, while the
+// Server Action runs. For lists where the new row should appear instantly,
+// layer \`useOptimistic\` on top \u2014 it is DISPLAY-ONLY: the server still checks
+// the permission and is the source of truth when the action returns.
+import { useActionState } from "react";
+import { useFormStatus } from "react-dom";
+import { PlusIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { createItem, type CreateItemState } from "@/app/actions";
+
+export function NewItemForm() {
+  const [state, formAction] = useActionState<CreateItemState, FormData>(
+    createItem,
+    null,
+  );
+  return (
+    <form action={formAction} className="flex flex-wrap items-start gap-2">
+      <label htmlFor="new-item-title" className="sr-only">
+        Title
+      </label>
+      <input
+        id="new-item-title"
+        name="title"
+        required
+        maxLength={200}
+        autoComplete="off"
+        placeholder="New item"
+        className="h-9 min-w-0 flex-1 rounded-md border border-input bg-background px-3 text-sm outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
+      />
+      <SubmitButton />
+      {state?.error ? (
+        <p role="alert" className="w-full text-sm text-destructive">
+          {state.error}
+        </p>
+      ) : null}
+    </form>
+  );
+}
+
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return (
+    <Button type="submit" disabled={pending}>
+      <PlusIcon aria-hidden="true" />
+      {pending ? "Adding\u2026" : "Add item"}
+    </Button>
+  );
+}
+`;
+}
 function seedMjs() {
   return `/**
  * seed.mjs \u2014 OPTIONAL seed/maintenance script template.
@@ -3801,16 +4012,31 @@ Import from there:
 \`\`\`ts
 import { db, qb } from '@dashai/generated';
 
-// Simple CRUD
-const rows = await db.<table>.list();
+// Simple CRUD. list() with no \`limit\` returns ONE page of 100 rows and
+// drops \`total\` \u2014 pass a \`limit\`, use listPage() for the total, or paginate.
+const rows = await db.<table>.list({ limit: 50 });
+const page = await db.<table>.listPage({ limit: 50, offset: 0 }); // { rows, total, ... }
 await db.<table>.create({ /* fields */ });
 
 // Query builder \u2014 a per-table getter (NOT a \`.from()\` call); \`.where()\`
 // takes a single clause object (field \u2192 value or field \u2192 operator), and
 // \`.execute()\` runs it. Chain \`.orderBy()\` / \`.limit()\` / \`.count()\` etc.
 const open = await qb.<table>.where({ status: { equal: 'open' } }).execute();
+
+// Aggregate ON THE SERVER \u2014 one call, not one count() per option.
+const openCount = await qb.<table>.where({ status: { equal: 'open' } }).count();
+const byStatus = await qb.<table>
+  .groupBy(['status'])
+  .agg({ total: { count: '*' } })
+  .execute(); // byStatus.rows = [{ status: 'open', total: 7 }, ...]
 \`\`\`
 
+Children of a linked parent: \`link_row\` fields take no value filters in a
+bare \`where\`, so join through the link and filter the joined side \u2014
+\`qb.comments.joinTask().where({ 'task.id': taskId }).execute()\` \u2014 which runs
+in SQL. Never read the whole child table and filter it in JS: \`list()\` stops
+at 100 rows, so that pattern is slow AND silently wrong past the first page.
+
 The data plane authenticates via the per-module scoped \`dwk_\` API key
 cached in \`~/.config/dashwise/auth.json#modules[${opts.slug}]\` after
 \`dashwise init\` provisions the dev install. \`dashwise dev\` injects it
@@ -3850,10 +4076,67 @@ follows the returned \`redirect_url\` \u2014 the same code runs in dev and in
 production, with no installation id or dev-session id in the request.
 
 In Server Components: \`await getServerSession()\` (from
-\`@dashai/sdk/auth/server\`).
+\`@dashai/sdk/auth/server\`)${isCustom ? ` \u2014 or the per-request cached
+\`getSession()\` from \`lib/session.ts\`, which the root layout already uses` : ""}.
 In Client Components: \`useSession()\` (from
-\`@dashai/sdk/auth/client\`), wrapped in \`<AuthProvider>\` (already
-in \`app/layout.tsx\`).
+\`@dashai/sdk/auth/client\`), wrapped in \`<AuthProvider>\`${isCustom ? ` (already
+in \`app/layout.tsx\`, hydrated server-side through \`initialSession\`)` : ""}.
+
+## Authorization \u2014 every action and route checks a permission
+
+Signing in is wired; **authorization is not automatic.** The middleware only
+checks that a session cookie EXISTS \u2014 it never checks what the user may do.
+And \`db\` / \`qb\` run with the module's \`dwk_\` key, which can touch every
+table the module owns. So:
+
+- **Every Server Action** starts with \`await requirePermission('<table>:<op>')\`
+  (from \`@dashai/sdk/auth/server\`; throws 401/403). A Server Action is a
+  public POST endpoint \u2014 hiding the button does not protect it.
+- **Every route handler** is wrapped: \`export const GET =
+  withPermission('<table>:read')(async (req) => \u2026)\` (from
+  \`@dashai/sdk/auth/middleware\`; answers 401/403).
+- **Per-user data needs an ownership check.** Store \`session.user.id\` on the
+  row and compare it before every update/delete. A permission says the user
+  may edit *items*, not *this* item.
+- **Optimistic UI is display-only.** \`useOptimistic\` changes what the user
+  sees; the server action still checks the permission and its result wins.
+- Shape the UI with \`hasPermissionInSession(session, key)\` (server) or
+  \`useHasPermission(key)\` (client) so nobody sees a button that then 403s.
+
+With no \`rbac\` block in \`module.json\` the platform synthesizes
+\`<table>:create|read|update|delete\` permissions plus admin/editor/viewer
+roles.${isCustom ? ` \`app/actions.ts\` and \`app/api/items/route.ts\` show both guards.` : ""}
+
+## Responsiveness \u2014 rules, not polish
+
+A module runs behind the platform proxy, so every server round trip is
+expensive. These are the defaults; break one only with a reason in the code.
+
+- **Feedback within 100 ms.** Every click that writes shows a pending state
+  immediately: \`useFormStatus()\` in the submit button, or \`useOptimistic\`
+  for lists${isCustom ? ` (\`components/new-item-form.tsx\` shows the pattern)` : ""}.
+  Navigation shows \`loading.tsx\`${isCustom ? ` (\`app/loading.tsx\` renders \`ListSkeleton\`)` : ""}.
+- **One narrow revalidate per write.** After a write, call ONE
+  \`revalidatePath('/the/screen')\` or \`revalidateTag(tag)\` \u2014 the screen
+  that shows the data, not \`'/'\` with \`'layout'\`. **Never call
+  \`router.refresh()\` after it**: the action's response already carries the
+  fresh render, and a refresh renders everything a second time.
+- **Parallel reads.** Independent awaits go in \`Promise.all([...])\`, never
+  one after another. Start reads that don't need the session in parallel
+  with the session lookup, but check the permission before rendering or
+  returning any data. Never rely on the middleware or the layout as the
+  guard: the middleware only checks that a cookie exists and the layout
+  checks no permission.
+- **No writes during a GET render.** Pages and layouts only read. Writes go
+  in Server Actions or POST routes; "touch lastSeen on render" style writes
+  make every view slow and break caching.
+- **\`prefetch={false}\`** on \`<Link>\`s in long row or card lists \u2014 Next
+  otherwise prefetches every visible row's page.
+- **Aggregate on the server.** \`qb.<table>.groupBy([...]).agg({...})\` or
+  \`.count()\` \u2014 never N \`count()\` calls in a loop, and never "list
+  everything and count in JS".
+- **\`list()\` returns one page of 100** and hides \`total\`. Pass a \`limit\`,
+  use \`listPage()\` when you need the total, or paginate.
 ${isCustom ? `
 ## Design & home
 
@@ -3886,8 +4169,10 @@ reads the session or data at render (calls \`getServerSession()\` or a
 \`dwk_\`-authenticated data call). Without it, \`next build\` statically
 prerenders the page with NO Dashwise env vars, the SDK throws
 \`missing apiBaseUrl\`, and the platform's first publish fails with an
-opaque \`BUILD_FAILED\`. The scaffolded \`app/page.tsx\` + \`app/dashboard/page.tsx\`
-already have it \u2014 any new session-gated page you add needs it too.
+opaque \`BUILD_FAILED\`. The scaffolded \`app/layout.tsx\`, \`app/page.tsx\` and
+\`app/dashboard/page.tsx\` already have it \u2014 any new session-gated page you add
+needs it too. Required today; becomes optional once the SDK reads cookies
+before config.
 
 A passing local \`npm run build\` is NOT proof: your \`.env.local\` supplies
 the env the platform build won't have, so it masks the failure. \`GET\` route
@@ -3949,8 +4234,12 @@ what tables it owns.
 
 | Method | Path | Auth | Purpose |
 |---|---|---|---|
-| GET | \`/api/items\` | dwk_ (server-side) | list \`items\` rows via \`db.items.list()\` |
-| POST | \`/api/items\` | dwk_ (server-side) | create an \`items\` row via \`db.items.create()\` |
+| GET | \`/api/items\` | session + \`items:read\` (\`withPermission\`); data via dwk_ server-side | EXAMPLE \u2014 delete or rename. List \`items\` rows via \`db.items.list({ limit: 50 })\` |
+| POST | \`/api/items\` | session + \`items:create\` (\`withPermission\`); data via dwk_ server-side | EXAMPLE \u2014 delete or rename. Create an \`items\` row via \`db.items.create()\` |
+
+Every route and Server Action checks a permission; the middleware only checks
+that a session cookie exists. List each Server Action here too, with its
+permission (custom scaffold: \`createItem\` in \`app/actions.ts\`, \`items:create\`).
 
 ## Business rules
 
@@ -4211,8 +4500,8 @@ async function moduleInitCommand(slugArg, options) {
     ["spec.md", specMd(scaffoldOpts)],
     ["agent-log.md", agentLogMd(scaffoldOpts)],
     // Example data-plane route (both flavors) — exercises the generated
-    // SDK against the seeded `items` table. Ships for simple + custom
-    // since both produce `@dashai/generated`.
+    // SDK against the seeded `items` table, guarded by withPermission.
+    // Ships for simple + custom since both produce `@dashai/generated`.
     ["app/api/items/route.ts", appApiItemsRouteTs()],
     // C12/D5 (Wave 2) — commented-out seed-script template. Pairs with
     // `dashwise run -- node seed.mjs`; carries the publish-packs-
@@ -4228,6 +4517,9 @@ async function moduleInitCommand(slugArg, options) {
       ["app/globals.css", globalsCss()],
       ["lib/utils.ts", libUtilsTs()],
       ["lib/request-origin.ts", libRequestOriginTs()],
+      // Per-request cached getServerSession(): the layout (initialSession)
+      // and the pages share one session fetch instead of two.
+      ["lib/session.ts", libSessionTs()],
       ["components/theme-provider.tsx", componentsThemeProviderTsx()],
       // Embedded-first defaults: follow the Dashwise app's theme, and ship the
       // page frame + the empty/loading/error states that a module needs to
@@ -4244,6 +4536,14 @@ async function moduleInitCommand(slugArg, options) {
       // reset() retry, semantic tokens (which resolve now that
       // globals.css maps them in @theme).
       ["app/error.tsx", appErrorTsx()],
+      // Root loading state: renders ListSkeleton instantly on navigation
+      // while the next page's server render is in flight.
+      ["app/loading.tsx", appLoadingTsx()],
+      // The canonical write path: a permission-guarded Server Action with
+      // one narrow revalidatePath, and its form with a useFormStatus
+      // pending state.
+      ["app/actions.ts", appActionsTs()],
+      ["components/new-item-form.tsx", componentsNewItemFormTsx()],
       ["app/dashboard/page.tsx", appDashboardPageTsx()],
       ["app/sign-in-error/page.tsx", appSignInErrorPageTsx()],
       ["app/api/auth/sign-in/route.ts", appApiAuthSignInTs()],
@@ -14417,7 +14717,7 @@ fieldCmd.command("set-type <table-slug> <field-slug> <new-type>").description(
   }
 );
 function getVersion() {
-  return "0.20.0";
+  return "0.21.0";
 }
 function parseIntOption(value) {
   const n = Number.parseInt(value, 10);