@stjoseph/prumo 0.0.1 → 0.0.2

package/.prumo-templates/mobile/routing.md

@@ -7,6 +7,9 @@ router render the authenticated group or redirect to login.
 
 Express protection with an authenticated layout group. Do not check for a session inside a screen.
 
+**In that layout, render nothing while the session is pending.** Redirect to sign in only once it has arrived
+empty or failed to load.
+
 When a deep link targets a protected route without a session, keep the intended destination **in memory**
 and navigate to it after a successful login. Do not persist it.
 
@@ -27,6 +30,13 @@ moment) while the alternative flash reads as a defect and can show somebody else
 
 Checking inside each screen fails differently: the screen written tomorrow does not check.
 
+**A pending session is not a missing one.** The natural check, redirect when there is no session data, works
+at a cold start only because the splash holds rendering until the session arrives, so the layout never sees
+it pending. Signing out empties the query cache, and the next sign-in mounts the layout with the session still
+on its way: the check reads no data, and sends the person who just signed in straight back to sign in. Nothing
+in normal use shows it until somebody signs out. Waiting while pending must not become a way in either, so a
+session that failed to load redirects just like an empty one.
+
 A dropped deep-link destination is the most common reason a notification link "does not work": the person
 taps a specific order, signs in, and lands on the home screen with the order to find by hand. Keeping the
 destination in memory rather than on disk matters because `orders/123` describes intent: it says the order
@@ -51,6 +61,15 @@ Protection:
 ❌  app/orders.tsx               → if (!session) router.replace('/login')
 ```
 
+Deciding in the layout:
+
+```
+✅  if (session.isPending) return null
+    if (session.data === null || session.data === undefined) return <Redirect href="/sign-in" />
+❌  if (!session.data) return <Redirect href="/sign-in" />
+    // bounces the next sign-in back once the cache has been cleared
+```
+
 Navigation:
 
 ```
@@ -65,6 +84,10 @@ before it renders.
 
 **Compiler.** Typed routes reject a misspelled path and a missing or wrongly typed param.
 
+**Tests.** Render the router with an empty cache and three session answers: one that arrives late expects
+the protected screen, an empty one and a failed one expect sign in. Rendering with a session already cached
+passes with the defect in place.
+
 **Review only.** That the splash is released only after the session resolves, and that a deep-link
 destination is not written to storage.
 

package/.prumo-templates/monorepo/tasks.md

@@ -2,10 +2,14 @@
 
 ## Rule
 
-Give the root `package.json` three scripts (`lint`, `typecheck` and `test`), each running through
-`pnpm -r`.
+Give the root `package.json` a `dev` script that starts every app with `pnpm -r --parallel dev`, and one script
+per app, named after it, that starts only that app with `pnpm --filter <app> dev`. Give it `lint`, `typecheck`
+and `test` as well, each running through `pnpm -r`.
 
-**Do not add a `dev` script at the root.** Start development with `pnpm --filter <app> dev`.
+**Every app answers to `dev`.** When a framework names its development command differently, keep its name and
+alias it: `"dev": "pnpm start:dev"` in the API, `"dev": "pnpm start"` in mobile.
+
+**Give every app its own port.** The API holds 3000, so the site runs on 3200.
 
 Keep compiler options in `tsconfig.base.json` at the workspace root. Extend it by relative path from each
 app and package, overriding only what differs.
@@ -21,9 +25,17 @@ its own `biome.jsonc` with `"extends": "//"`, holding only what differs.
 What does not exist is caching, and caching pays once a build hurts, which a freshly generated workspace
 does not.
 
-The missing `dev` script is deliberate. `pnpm dev` in a workspace with four apps would start four
-processes, one of them interactive, when whoever typed it expected the app they are working on. **Its
-absence is what teaches that `dev` is per app**; if it existed, nobody would learn.
+`pnpm dev` is safe because the one-app command is just as short. Without `pnpm web` beside it, typing
+`pnpm dev` while expecting the app you work on would start four processes; with it, starting everything is a
+choice rather than an accident. The root scripts call `dev` and nothing else, which is why every app answers to
+that name: the root never needs to know how each framework spells its development command.
+
+**Mobile gives up its terminal under `pnpm dev`.** Metro starts and serves, so an open simulator connects, but
+the QR code, the `exp://` URL and the keyboard shortcuts appear only when Expo owns the terminal. When you need
+them, run `pnpm mobile` in a terminal of its own.
+
+Ports are fixed per app because `pnpm dev` starts them together, and a collision there fails only when two apps
+run at once: `next dev` defaults to 3000, which the API already holds.
 
 The other three belong at the root because that is what the pre-push hook calls. Leaving them out would
 mean each person assembling their own `--filter`, and several versions of one command.
@@ -52,8 +64,10 @@ The workspace root, and every `tsconfig.json` beneath it.
 Starting work:
 
 ```
-✅  pnpm --filter web dev
-❌  pnpm dev                    // four apps, one of them interactive
+✅  pnpm web                    // the app you are working on
+✅  pnpm dev                    // every app; mobile without its QR code
+✅  pnpm mobile                 // mobile with its QR code and shortcuts
+❌  "dev" missing from an app   // pnpm dev silently skips it
 ```
 
 Extending the base:
@@ -67,8 +81,9 @@ Extending the base:
 
 **The hook.** Pre-push runs the root `typecheck`, so a type error in any package stops the push.
 
-**Review only.** That a new app extends the base rather than copying it, and that a root `dev` script has
-not appeared.
+**Review only.** That a new app extends the base rather than copying it, answers to `dev`, runs on a port no
+other app uses, and has a root script named after it. A missing `dev` fails nothing: `pnpm -r` skips a package
+without the script, so the app simply does not start.
 
 **The reversal condition, stated so it is measurable rather than a feeling:** without caching,
 `pnpm -r typecheck` runs `tsc` in every package from scratch every time. Turborepo belongs on the table the

package/.prumo-templates/web/routing.md

@@ -14,6 +14,12 @@ types the router derives from the file name.
 Let TanStack Query own the cache. Use a route loader only to call `ensureQueryData`, and read the data in
 the component through the Query hook. Never pass loader data down as props.
 
+**After signing in or signing up, `await` a `refetchQueries` of the session before navigating.** Never
+`invalidateQueries` for it.
+
+**On signing out, `clear()` the whole query cache**, whether or not the sign-out request succeeded, then navigate
+to sign in.
+
 ## Rationale
 
 The generated route tree is committed because application code imports it, so without it `tsc` fails on a
@@ -36,6 +42,21 @@ The loader prefetches rather than fetches because two caches holding the same da
 screen not update* becomes unanswerable. Data handed down as props sits in no cache, so invalidating
 after a mutation never reaches it.
 
+**The session is the one query where invalidating fails silently.** The authenticated layout reads it
+with `ensureQueryData`, which fetches only when the cache is empty, and a visitor without a session leaves
+`null` there, which is not empty. `invalidateQueries` only marks it stale and refetches what a component
+observes, and nothing observes the session. So the sign-in succeeds, the server holds a session, and the
+layout reads the cached `null` and sends the visitor back to sign in. `refetchQueries` includes queries
+nobody observes and resolves once the new value is cached. Following the loader rule above and the
+invalidation rule in `data.md` to the letter is exactly how this defect is written.
+
+**Signing out needs more than the session.** A query about *me* is keyed by what it means, not by who asked:
+`['profile', 'me']` holds whoever was signed in. Refetching only the session lets the next person on the same tab
+sign in and read the previous person's profile, because the loader's `ensureQueryData` finds it cached. Clearing
+the cache is the only choice that stays correct when somebody adds the next query without thinking about signing
+out; listing the user's queries one by one fails the day one is forgotten. It clears even when the request fails,
+because a server session left alive is a smaller harm than a previous user's data left readable.
+
 ## Applies to
 
 Every file under `routes/`.
@@ -66,6 +87,26 @@ Loading data:
     // component: props.orders
 ```
 
+After the session changes:
+
+```
+✅  await queryClient.refetchQueries({ queryKey: sessionQuery(auth).queryKey })
+    await navigate({ to: redirect ?? '/' })
+❌  await queryClient.invalidateQueries({ queryKey: sessionQuery(auth).queryKey })
+    // the layout still reads the cached null
+```
+
+Signing out:
+
+```
+✅  await auth.signOut()
+    queryClient.clear()
+    await navigate({ to: '/sign-in' })
+❌  await auth.signOut()
+    await queryClient.refetchQueries({ queryKey: sessionQuery(auth).queryKey })
+    // the next person signs in and reads the previous profile
+```
+
 ## Enforcement
 
 **Structural.** A route inside the authenticated layout cannot skip the redirect, because the layout runs
@@ -74,8 +115,14 @@ first.
 **Compiler.** `validateSearch` makes the search params' types reflect what survived validation, so a
 component cannot read a field the schema does not produce.
 
-**Review only.** That the loader prefetches rather than returning data the component consumes, and that a
-route needing a session was not placed outside the layout.
+**Tests.** A test that renders the app at a protected route, signs in, and expects the protected page. It
+must start from the protected route: starting on the sign-in page never caches the `null`, and passes with
+the defect in place. A second test signs one person out, signs another in on the same app, and expects the
+second person's data rather than the first's.
+
+**Review only.** That the loader prefetches rather than returning data the component consumes, that a
+route needing a session was not placed outside the layout, that every form signing in refetches the session,
+and that signing out clears the cache.
 
 **A tie worth knowing:** the query key is shared between the loader and the component. If they differ, the
 prefetch fills one cache entry and the component reads another, paying for the request twice and gaining

package/README.md

@@ -4,7 +4,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@stjoseph/prumo"><img src="https://img.shields.io/npm/v/%40stjoseph%2Fprumo?color=1e3a5f&label=npm" alt="npm"></a>
-  <a href="https://github.com/stjosephworks/prumo/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/%40stjoseph%2Fprumo?color=1e3a5f" alt="MIT"></a>
+  <a href="https://github.com/stjosephworks/prumo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/stjosephworks/prumo?color=1e3a5f" alt="MIT"></a>
 </p>
 
 Prumo is a set of choices a team has already made, packaged so that starting a new TypeScript
@@ -36,9 +36,14 @@ Node 22.17 or later, pnpm, and Docker for anything with an API.
 ## Running it
 
 ```sh
-pnpm dlx @stjoseph/prumo new my-app
+npx @stjoseph/prumo new my-app        # npm
+pnpm dlx @stjoseph/prumo new my-app   # pnpm
 ```
 
+Either runner starts it, and the generated project installs with pnpm, which it needs anyway. The
+published package is [`@stjoseph/prumo`](https://www.npmjs.com/package/@stjoseph/prumo), and the
+command it installs is `prumo`.
+
 It asks what to build, writes the project into `my-app/`, runs `git init`, and installs. Nothing is
 committed, so the first commit is yours and the diff shows everything Prumo wrote.
 
@@ -47,7 +52,7 @@ terminal a missing answer is an error rather than a default, so nothing importan
 silence:
 
 ```sh
-pnpm dlx @stjoseph/prumo new my-app --types api,web --single-tenant
+npx @stjoseph/prumo new my-app --types api,web --single-tenant
 ```
 
 | Flag | What it answers |

package/dist/assets.js

@@ -0,0 +1,16 @@
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+// Decided by where the CLI runs from, never by what exists on disk: after a build, `cli/templates` is a stale copy
+// sitting right beside the source, and probing for it first made the source CLI generate from yesterday's templates.
+export function assetsFor(here) {
+    const root = basename(here) === 'dist' ? join(here, '..') : join(here, '..', '..');
+    return { templates: join(root, 'templates'), knowledge: join(root, '.prumo-templates') };
+}
+export function requireAssets(assets) {
+    for (const path of Object.values(assets)) {
+        if (!existsSync(path)) {
+            throw new Error(`Cannot find ${path}`);
+        }
+    }
+    return assets;
+}

package/dist/cli.js

@@ -1,21 +1,14 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import * as prompt from '@clack/prompts';
 import { terminalAsker } from "./asker.js";
+import { assetsFor, requireAssets } from "./assets.js";
 import { generate } from "./generate.js";
 import { validateProjectName } from "./names.js";
 import { resolveAnswers } from "./questions.js";
 const USAGE = `Usage: prumo new [name] [--types api,web,mobile,site] [--alone | --monorepo]
                   [--multi-tenant | --single-tenant] [--skip-install]`;
-function firstExisting(...candidates) {
-    const found = candidates.find((candidate) => existsSync(candidate));
-    if (found === undefined) {
-        throw new Error(`Cannot find ${candidates.join(' or ')}`);
-    }
-    return found;
-}
 async function main() {
     const { values, positionals } = parseArgs({
         allowPositionals: true,
@@ -48,8 +41,7 @@ async function main() {
     }
     const here = import.meta.dirname;
     await generate({
-        templates: firstExisting(join(here, '../templates'), join(here, '../../templates')),
-        knowledge: firstExisting(join(here, '../.prumo-templates'), join(here, '../../.prumo-templates')),
+        ...requireAssets(assetsFor(here)),
         target: resolve(answers.name),
         answers,
         install: !values['skip-install'],

package/dist/compose.js

@@ -203,6 +203,8 @@ export async function composeWorkspace({ templates, target, types, mobileScheme
             return text.replace('# MOBILE_APP_SCHEME=app\n', `MOBILE_APP_SCHEME=${mobileScheme}\n`);
         });
     }
+    // One command for everything and one per app. Each app answers to `dev`, so the root never needs to know how.
+    await rewriteText(join(target, 'package.json'), (text) => types.reduce((pkg, type) => setJsonc(pkg, ['scripts', type], `pnpm --filter ${type} dev`), setJsonc(text, ['scripts', 'dev'], 'pnpm -r --parallel dev')));
     const manifests = await Promise.all(apps.map(async (app) => readJsonc(await readFile(join(app, 'package.json'), 'utf8'))));
     const catalogs = collectCatalog(manifests);
     if (clients.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",
@@ -23,6 +23,7 @@
   "license": "MIT",
   "author": "Leonardo Freitas",
   "type": "module",
+  "packageManager": "pnpm@12.3.4",
   "bin": {
     "prumo": "dist/cli.js"
   },

package/templates/api/README.md

@@ -11,7 +11,7 @@ pnpm install
 cp .env.example .env        # then replace BETTER_AUTH_SECRET with 32 or more random characters
 docker compose up -d --wait
 pnpm db:migrate
-pnpm start:dev
+pnpm dev
 ```
 
 The API listens on `http://localhost:3000`. Outside production, its documentation is at `/api/docs`.

package/templates/api/package.json

@@ -6,6 +6,7 @@
     "build": "nest build",
     "start": "nest start",
     "start:dev": "nest start --watch",
+    "dev": "pnpm start:dev",
     "start:prod": "node dist/main",
     "lint": "biome check",
     "typecheck": "tsc --noEmit",

package/templates/mobile/README.md

@@ -10,7 +10,7 @@ to open the app.
 ```sh
 pnpm install
 cp .env.example .env        # EXPO_PUBLIC_API_URL points at the API
-pnpm start
+pnpm dev
 ```
 
 On an Android emulator `localhost` is the emulator itself; point `EXPO_PUBLIC_API_URL` at your machine's address.

package/templates/mobile/package.json

@@ -5,6 +5,7 @@
   "main": "expo-router/entry",
   "scripts": {
     "start": "expo start",
+    "dev": "pnpm start",
     "ios": "expo start --ios",
     "android": "expo start --android",
     "bundle": "expo export --platform ios --platform android",

package/templates/mobile/src/app/(app)/_layout.tsx

@@ -9,6 +9,12 @@ export default function AuthenticatedLayout() {
   const session = useQuery(sessionQuery(auth))
   const pathname = usePathname()
 
+  // Pending is not signed out: after the cache is cleared, the session takes a request to arrive, and redirecting on
+  // that would send whoever just signed in straight back to sign in. A failed request still redirects.
+  if (session.isPending) {
+    return null
+  }
+
   if (session.data === null || session.data === undefined) {
     rememberIntendedRoute(pathname)
     return <Redirect href="/sign-in" />

package/templates/mobile/src/app/(app)/index.tsx

@@ -1,18 +1,22 @@
 import { useQuery } from '@tanstack/react-query'
+import { useRouter } from 'expo-router'
 import { Text } from 'react-native'
 import { SafeAreaView } from 'react-native-safe-area-context'
 import { profileQuery } from '@/api-contract'
+import { SignOutButton } from '@/features/auth/sign-out-button'
 import { useClients } from '@/features/clients/clients-context'
 import { ProfileForm } from '@/features/profile/profile-form'
 
 export default function ProfileScreen() {
-  const { api } = useClients()
+  const { api, auth } = useClients()
+  const router = useRouter()
   const profile = useQuery(profileQuery(api))
 
   return (
     <SafeAreaView className="flex-1 justify-center gap-6 p-6">
       <Text className="text-2xl font-semibold text-neutral-900">Your profile</Text>
       {profile.data === undefined ? null : <ProfileForm api={api} profile={profile.data} />}
+      <SignOutButton auth={auth} onSignedOut={() => router.replace('/sign-in')} />
     </SafeAreaView>
   )
 }

package/templates/mobile/src/features/auth/authenticated-layout.spec.tsx

@@ -0,0 +1,69 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createAuthClient } from 'better-auth/react'
+import { renderRouter, screen } from 'expo-router/testing-library'
+import type { ReactNode } from 'react'
+import { Text } from 'react-native'
+import { createClient } from '@/api-contract'
+import AuthenticatedLayout from '@/app/(app)/_layout'
+import type { AuthClient } from '@/features/auth/auth-client'
+import { ClientsProvider } from '@/features/clients/clients-context'
+import { API_URL, fakeTransport, json } from '../../../test/fake-transport'
+
+const user = { id: 'user-1', email: 'ana@example.com', name: 'Ana' }
+
+async function renderAt(getSession: () => Response | Promise<Response>) {
+  const transport = fakeTransport({ 'GET /api/auth/get-session': getSession })
+  // jest-expo leaves the app manifest empty, and the Expo plugin needs it to build an origin; the layout depends only on
+  // what getSession returns, which the plugin does not change.
+  const auth = createAuthClient({
+    baseURL: API_URL,
+    basePath: '/api/auth',
+    fetchOptions: { customFetchImpl: transport },
+  }) as unknown as AuthClient
+  const clients = { auth, api: createClient({ baseUrl: API_URL, fetch: transport }) }
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  function Providers({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ClientsProvider clients={clients}>{children}</ClientsProvider>
+      </QueryClientProvider>
+    )
+  }
+
+  await renderRouter(
+    {
+      '(app)/_layout': AuthenticatedLayout,
+      '(app)/index': () => <Text>Your profile</Text>,
+      'sign-in': () => <Text>Sign in</Text>,
+    },
+    { initialUrl: '/', wrapper: Providers },
+  )
+}
+
+describe('AuthenticatedLayout', () => {
+  // An empty cache is what signing out leaves behind, and the session then takes a request to arrive.
+  it('waits for a session still on its way instead of sending a signed-in visitor to sign in', async () => {
+    await renderAt(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      return json(200, { session: { id: 'session-1', userId: user.id }, user })
+    })
+
+    expect(await screen.findByText('Your profile')).toBeOnTheScreen()
+    expect(screen.queryByText('Sign in')).toBeNull()
+  })
+
+  it('sends a visitor without a session to sign in', async () => {
+    await renderAt(() => json(200, null))
+
+    expect(await screen.findByText('Sign in')).toBeOnTheScreen()
+  })
+
+  // Waiting on a pending session must not become a way in: a session that cannot be read is not a session.
+  it('sends a visitor to sign in when the session cannot be read', async () => {
+    await renderAt(() => json(500, { message: 'Internal server error' }))
+
+    expect(await screen.findByText('Sign in')).toBeOnTheScreen()
+    expect(screen.queryByText('Your profile')).toBeNull()
+  })
+})

package/templates/mobile/src/features/auth/sign-out-button.spec.tsx

@@ -0,0 +1,55 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { render, screen, userEvent, waitFor } from '@testing-library/react-native'
+import { createAuthClient } from 'better-auth/react'
+import { clearUserData } from '@/features/storage/storage'
+import { API_URL, fakeTransport, json } from '../../../test/fake-transport'
+import { SignOutButton } from './sign-out-button'
+
+// MMKV needs its native module, which Jest does not have. What clearUserData removes is the persister's own key.
+jest.mock('@/features/storage/storage', () => ({ clearUserData: jest.fn() }))
+
+async function signOutWith(signOut: () => Response | Promise<Response>) {
+  const queryClient = new QueryClient()
+  const onSignedOut = jest.fn()
+  // jest-expo leaves the app manifest empty, and the Expo plugin needs it to build an origin; the button depends only on
+  // signOut resolving or failing, which the plugin does not change.
+  const auth = createAuthClient({
+    baseURL: API_URL,
+    basePath: '/api/auth',
+    fetchOptions: { customFetchImpl: fakeTransport({ 'POST /api/auth/sign-out': signOut }) },
+  })
+
+  queryClient.setQueryData(['session'], { session: { id: 'session-1' }, user: { id: 'user-1' } })
+  queryClient.setQueryData(['profile', 'me'], { id: 'profile-1', displayName: 'Ana' })
+
+  await render(
+    <QueryClientProvider client={queryClient}>
+      <SignOutButton auth={auth} onSignedOut={onSignedOut} />
+    </QueryClientProvider>,
+  )
+
+  await userEvent.setup().press(screen.getByRole('button', { name: 'Sign out' }))
+  await waitFor(() => expect(onSignedOut).toHaveBeenCalled())
+
+  return queryClient
+}
+
+describe('SignOutButton', () => {
+  beforeEach(() => jest.mocked(clearUserData).mockClear())
+
+  it('leaves nothing of the user behind for the next person on the device', async () => {
+    const queryClient = await signOutWith(() => json(200, { success: true }))
+
+    expect(queryClient.getQueryCache().getAll()).toHaveLength(0)
+    expect(clearUserData).toHaveBeenCalledTimes(1)
+  })
+
+  it('still clears the device when the sign-out request never arrives', async () => {
+    const queryClient = await signOutWith(() => {
+      throw new TypeError('Network request failed')
+    })
+
+    expect(queryClient.getQueryCache().getAll()).toHaveLength(0)
+    expect(clearUserData).toHaveBeenCalledTimes(1)
+  })
+})

package/templates/mobile/src/features/auth/sign-out-button.tsx

@@ -0,0 +1,33 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { Button } from '@/components/ui/button'
+import { clearUserData } from '@/features/storage/storage'
+import type { AuthClient } from './auth-client'
+
+export type SignOutAuth = Pick<AuthClient, 'signOut'>
+
+export function SignOutButton({
+  auth,
+  onSignedOut,
+}: {
+  auth: SignOutAuth
+  onSignedOut: () => void
+}) {
+  const queryClient = useQueryClient()
+
+  async function signOut() {
+    try {
+      await auth.signOut()
+    } catch {
+      // A failed request leaves nothing on the device to act on: the Expo plugin deletes the stored cookie before it
+      // sends. The server's session outlives it until it expires, and signing out locally is still what was asked.
+    }
+
+    // What the plugin cannot know is the rest of this user's data: the query cache and every user-scoped key, or the
+    // next person on this device reads them.
+    queryClient.clear()
+    clearUserData()
+    onSignedOut()
+  }
+
+  return <Button label="Sign out" variant="outline" onPress={signOut} />
+}

package/templates/site/README.md

@@ -11,7 +11,7 @@ pnpm install
 pnpm dev
 ```
 
-The site runs on `http://localhost:3000`. It calls no API yet; when a page needs data, it fetches it on the server.
+The site runs on `http://localhost:3200`, leaving 3000 to the API. It calls no API yet; when a page needs data, it fetches it on the server.
 
 ## Everyday commands
 

package/templates/site/package.json

@@ -4,9 +4,9 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --port 3200",
     "build": "next build",
-    "start": "next start",
+    "start": "next start --port 3200",
     "lint": "biome check",
     "typecheck": "next typegen && tsc --noEmit",
     "test": "vitest run",

package/templates/web/README.md

@@ -14,6 +14,10 @@ pnpm dev
 
 The app runs on `http://localhost:5173`, which is the origin the API trusts by default (`WEB_ORIGIN`).
 
+Open it and you are sent to sign in, because everything but the sign-in and sign-up pages needs a session. Follow
+**Sign up** to create an account; you land on your profile, which you can edit. The API must be running and
+migrated first, or the session check has nothing to answer it.
+
 ## Everyday commands
 
 | Command | What it does |

package/templates/web/src/app.spec.tsx

@@ -1,12 +1,142 @@
 import { screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { describe, expect, it } from 'vitest'
+import type { Profile } from '@/api-contract'
 import { fakeTransport, json } from '../test/fake-transport'
 import { renderApp } from '../test/render-app'
 
+const user = { id: 'user-1', email: 'ana@example.com', name: 'Ana' }
+
+const session = { session: { id: 'session-1', userId: user.id }, user }
+
+const profile: Profile = {
+  id: 'profile-1',
+  userId: user.id,
+  displayName: 'Ana',
+  locale: 'en',
+  timezone: 'UTC',
+  createdAt: '2026-09-14T12:57:24.057Z',
+  updatedAt: '2026-09-14T12:57:24.057Z',
+}
+
 describe('App', () => {
   it('sends a visitor without a session to sign in', async () => {
     renderApp('/', fakeTransport({ 'GET /api/auth/get-session': () => json(200, null) }))
 
     expect(await screen.findByRole('heading', { name: 'Sign in' })).toBeInTheDocument()
   })
+
+  // The protected route reads the session through ensureQueryData, which keeps a cached null. Found in a real browser:
+  // signing in succeeded, a session existed, and the visitor was sent straight back to sign in.
+  it('takes a visitor who signs in to the page they were turned away from', async () => {
+    const visitor = userEvent.setup()
+    let signedIn = false
+
+    renderApp(
+      '/',
+      fakeTransport({
+        'GET /api/auth/get-session': () => json(200, signedIn ? session : null),
+        'POST /api/auth/sign-in/email': () => {
+          signedIn = true
+          return json(200, { redirect: false, token: 'token-1', user })
+        },
+        'GET /api/v1/users/me': () => json(200, profile),
+      }),
+    )
+
+    await visitor.type(await screen.findByLabelText('Email'), user.email)
+    await visitor.type(screen.getByLabelText('Password'), 'correct-horse-battery')
+    await visitor.click(screen.getByRole('button', { name: 'Sign in' }))
+
+    expect(await screen.findByRole('heading', { name: 'Your profile' })).toBeInTheDocument()
+  })
+
+  // Starting from sign-up would hide the defect: only a protected route caches the null session first.
+  it('takes a visitor turned away to sign in, who then creates an account, into the app', async () => {
+    const visitor = userEvent.setup()
+    let registered = false
+
+    renderApp(
+      '/',
+      fakeTransport({
+        'GET /api/auth/get-session': () => json(200, registered ? session : null),
+        'POST /api/auth/sign-up/email': () => {
+          registered = true
+          return json(200, { token: 'token-1', user })
+        },
+        'GET /api/v1/users/me': () => json(200, profile),
+      }),
+    )
+
+    await visitor.click(await screen.findByRole('link', { name: 'Sign up' }))
+    await visitor.type(await screen.findByLabelText('Name'), user.name)
+    await visitor.type(screen.getByLabelText('Email'), user.email)
+    await visitor.type(screen.getByLabelText('Password'), 'correct-horse-battery')
+    await visitor.click(screen.getByRole('button', { name: 'Create account' }))
+
+    expect(await screen.findByRole('heading', { name: 'Your profile' })).toBeInTheDocument()
+  })
+
+  it('shows the next person on the tab their own profile, not the previous one', async () => {
+    const visitor = userEvent.setup()
+    const people = {
+      ana: { user, profile },
+      bruno: {
+        user: { id: 'user-2', email: 'bruno@example.com', name: 'Bruno' },
+        profile: { ...profile, id: 'profile-2', userId: 'user-2', displayName: 'Bruno' },
+      },
+    }
+    let current: keyof typeof people | null = 'ana'
+
+    renderApp(
+      '/',
+      fakeTransport({
+        'GET /api/auth/get-session': () =>
+          json(
+            200,
+            current === null
+              ? null
+              : { session: { id: `session-${current}` }, user: people[current].user },
+          ),
+        'POST /api/auth/sign-out': () => {
+          current = null
+          return json(200, { success: true })
+        },
+        'POST /api/auth/sign-in/email': () => {
+          current = 'bruno'
+          return json(200, { redirect: false, token: 'token-2', user: people.bruno.user })
+        },
+        'GET /api/v1/users/me': () => json(200, current === null ? null : people[current].profile),
+      }),
+    )
+
+    expect(await screen.findByLabelText('Display name')).toHaveValue('Ana')
+
+    await visitor.click(screen.getByRole('button', { name: 'Sign out' }))
+    await visitor.type(await screen.findByLabelText('Email'), people.bruno.user.email)
+    await visitor.type(screen.getByLabelText('Password'), 'correct-horse-battery')
+    await visitor.click(screen.getByRole('button', { name: 'Sign in' }))
+
+    await screen.findByRole('heading', { name: 'Your profile' })
+    expect(screen.getByLabelText('Display name')).toHaveValue('Bruno')
+  })
+
+  it('signs a visitor out of this tab even when the sign-out request never arrives', async () => {
+    const visitor = userEvent.setup()
+
+    renderApp(
+      '/',
+      fakeTransport({
+        'GET /api/auth/get-session': () => json(200, session),
+        'GET /api/v1/users/me': () => json(200, profile),
+        'POST /api/auth/sign-out': () => {
+          throw new TypeError('Failed to fetch')
+        },
+      }),
+    )
+
+    await visitor.click(await screen.findByRole('button', { name: 'Sign out' }))
+
+    expect(await screen.findByRole('heading', { name: 'Sign in' })).toBeInTheDocument()
+  })
 })

package/templates/web/src/features/auth/sign-in-form.tsx

@@ -38,7 +38,9 @@ export function SignInForm({ auth, redirect }: { auth: AuthClient; redirect: str
       return
     }
 
-    await queryClient.invalidateQueries({ queryKey: sessionQuery(auth).queryKey })
+    // Invalidating is not enough: nothing observes the session, and the protected route's ensureQueryData
+    // would keep returning the cached null. Refetching replaces it before the route reads it.
+    await queryClient.refetchQueries({ queryKey: sessionQuery(auth).queryKey })
     await navigate({ to: redirect ?? '/' })
   }
 

package/templates/web/src/features/auth/sign-out-button.tsx

@@ -0,0 +1,28 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { useNavigate } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import type { AuthClient } from './auth-client'
+
+export function SignOutButton({ auth }: { auth: AuthClient }) {
+  const queryClient = useQueryClient()
+  const navigate = useNavigate()
+
+  async function signOut() {
+    try {
+      await auth.signOut()
+    } catch {
+      // Better Auth throws when the request never arrives. The cache is cleared regardless, because data left behind
+      // for the next person on this tab is the worse error; the cookie survives until the server's session expires.
+    }
+
+    // The whole cache, not only the session: a query about "me" belongs to whoever was signed in.
+    queryClient.clear()
+    await navigate({ to: '/sign-in' })
+  }
+
+  return (
+    <Button type="button" variant="outline" onClick={signOut}>
+      Sign out
+    </Button>
+  )
+}

package/templates/web/src/features/auth/sign-up-form.tsx

@@ -39,7 +39,9 @@ export function SignUpForm({ auth }: { auth: AuthClient }) {
       return
     }
 
-    await queryClient.invalidateQueries({ queryKey: sessionQuery(auth).queryKey })
+    // Invalidating is not enough: nothing observes the session, and the protected route's ensureQueryData
+    // would keep returning the cached null. Refetching replaces it before the route reads it.
+    await queryClient.refetchQueries({ queryKey: sessionQuery(auth).queryKey })
     await navigate({ to: '/' })
   }
 

package/templates/web/src/routes/_authenticated/index.tsx

@@ -1,6 +1,7 @@
 import { useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
 import { profileQuery } from '@/api-contract'
+import { SignOutButton } from '@/features/auth/sign-out-button'
 import { ProfileForm } from '@/features/profile/profile-form'
 
 export const Route = createFileRoute('/_authenticated/')({
@@ -9,13 +10,14 @@ export const Route = createFileRoute('/_authenticated/')({
 })
 
 function ProfilePage() {
-  const { api } = Route.useRouteContext()
+  const { api, auth } = Route.useRouteContext()
   const { data: profile } = useSuspenseQuery(profileQuery(api))
 
   return (
     <>
       <h1 className="text-2xl font-semibold">Your profile</h1>
       <ProfileForm api={api} profile={profile} />
+      <SignOutButton auth={auth} />
     </>
   )
 }

package/templates/workspace/README.md

@@ -16,9 +16,16 @@ Node 22.17 or later, pnpm, and Docker for the API.
 | Command | What it does |
 |---|---|
 | `pnpm install` | Installs every app and package |
-| `pnpm --filter <app> dev` | Starts one app. There is no root `dev` on purpose |
+| `pnpm dev` | Starts every app at once, their output prefixed by app. Mobile runs without its QR code there; use `pnpm mobile` for that |
+| `pnpm api` · `pnpm web` · `pnpm mobile` · `pnpm site` | Starts one app; the workspace has a script for each app it holds |
 | `pnpm lint` · `pnpm typecheck` · `pnpm test` | Runs across every app and package |
 
+## Trying it
+
+With the API migrated, run `pnpm dev`. If the workspace holds `web`, open `http://localhost:5173`: you are sent to
+sign in, and **Sign up** creates an account and takes you to your profile. Each app's README says what it needs
+before it starts.
+
 ## Conventions
 
 The rules this project follows live in `.prumo/`, and `AGENTS.md` points to them. Read those before