ugly-app 0.1.463 → 0.1.464

package/README.md

@@ -1,18 +1,22 @@
 # ugly-app
 
-A full-stack TypeScript framework for building production-ready web applications. Scaffold with `npx ugly-app init my-app` and get an opinionated Express + React + MongoDB stack with built-in auth, real-time WebSockets, AI generation, storage, and a CLI for every workflow.
+A full-stack TypeScript framework for shipping production web apps with one CLI. Scaffold with `npx ugly-app init my-app` and get an opinionated Express + React + PostgreSQL stack with built-in auth, type-safe RPC over WebSocket and HTTP, real-time document tracking, AI generation, storage, and a CLI for every workflow.
+
+ugly-app is designed to be deployed and operated through [ugly.bot](https://ugly.bot) — the platform handles auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of this through the project's dev tunnel and the per-app `UGLY_BOT_TOKEN`.
 
 ## What's included
 
 - **Server**: Express + WebSocket with type-safe RPC and Zod validation
-- **Client**: React + Vite with typed routing, lazy pages, and popup management
-- **Database**: MongoDB with typed collections, dot-notation updates, indexes, migrations, and live document tracking
-- **Auth**: JWT + HttpOnly cookies, ugly.bot OAuth out of the box, extensible via `AuthProvider`
-- **AI**: Text generation (Together, Claude, OpenAI, Google, Groq, Fireworks, Kie) + image generation (Together, FAL, Google, Wavespeed, Kie) + embeddings + STT/TTS
-- **Storage**: Cloudflare R2 / AWS S3 with presigned uploads
-- **Web search**: Kagi and UglyBot providers with search, summarize, and enrich
-- **Billing**: Usage-based billing with per-user/global limits, credits, and threshold alerts
-- **CLI**: `ugly-app` commands for dev, build, deploy, migrations, logs, and auth utilities
+- **Client**: React + Vite with typed routing, lazy pages, animated transitions, popup management
+- **Database**: PostgreSQL (JSONB) via the data proxy, with full-text search (`search`) and vector search (Qdrant `vector`)
+- **Auth**: HttpOnly cookies + JWT, ugly.bot OAuth out of the box, extensible via `AuthProvider`
+- **AI**: Text, image, embeddings, web search — all proxied through ugly.bot (no per-provider keys in your app)
+- **Realtime**: NATS pub/sub and document change subscriptions (`trackDoc` / `trackDocs`)
+- **Storage**: S3-compatible buckets with presigned uploads
+- **Workers & cron**: `setWorkers()` registers named async tasks with optional Zod input schemas and cron schedules
+- **Localization**: Strings tables with critical-string SSR injection
+- **Experiments**: Deterministic A/B bucketing tied to event logging
+- **CLI**: `ugly-app` commands for dev, build, deploy, migrations, logs, AI, and auth
 
 ## Quick start
 
@@ -22,112 +26,127 @@ cd my-app
 npm run dev
 ```
 
+The scaffold gives you a working app at `http://localhost:4321` with todo CRUD, AI chat, file upload, auth demo, collab editing, and ~20 other test pages wired up.
+
 ---
 
 ## Server
 
 ### `createApp()`
 
-Entry point for the server. Creates an Express + WebSocket server with typed RPC, auth, and all framework services.
+The single server entry point. Returns an `App` that owns Express, the WebSocket server, the typed DB, and the RPC dispatcher.
 
 ```typescript
 import {
   createApp,
-  createUserHelper,
-  getFeedbackHandlers,
   type AppConfigurator,
   type RequestHandlers,
 } from 'ugly-app';
 import { dbDefaults } from 'ugly-app/shared';
-import { requests } from '../shared/api';
+import { requests, messages } from '../shared/api';
 import { collections } from '../shared/collections';
 import { pages } from '../shared/pages';
-import type { User } from '../shared/collections';
-
-const userHelper = createUserHelper<User>(collections.user);
-const maintainBotUserId = process.env.MAINTAIN_BOT_USER_ID ?? '';
 
 const app = createApp(
-  { requests },
+  { requests, messages },
   {
-    ...getFeedbackHandlers(maintainBotUserId),
-    getMe: async (userId: string) => {
-      const user = await userHelper.get(app.db, userId);
-      return { userId, email: user?.email, phone: user?.phone };
+    createTodo: async (userId, { text }) => {
+      const _id = crypto.randomUUID();
+      await app.db.setDoc(collections.todo, { _id, userId, text, done: false, ...dbDefaults() });
+      return { id: _id };
     },
   } satisfies RequestHandlers<typeof requests>,
   collections,
   (configurator: AppConfigurator) => {
     configurator.setPages({ pages });
-    configurator.setUserHelper(userHelper);
-    configurator.setOnUserCreate(async (userId, info, db) => {
-      await userHelper.set(db, { id: userId, ...dbDefaults(), ...info });
-    });
   },
 );
 
-const port = parseInt(process.env['PORT'] ?? '3000');
-await app.start(port);
+await app.start(parseInt(process.env['PORT'] ?? '4321'));
 ```
 
 **Signature:**
 
 ```typescript
 function createApp<R extends AppRegistryBase, Defs extends CollectionDefRegistry>(
-  registry: R,
-  requests: Partial<RequestHandlers<R['requests']>>,
-  appDefs: Defs,
-  configure?: (configurator: AppConfigurator) => void,
-): App;
+  registry: R,                                       // { requests, messages }
+  requests: Partial<RequestHandlers<R['requests']>>, // handler implementations
+  appDefs: Defs,                                     // collections from defineCollections()
+  configure?: (c: AppConfigurator) => void,
+  deleteHandlers?: DeleteHandlers<Defs>,             // per-collection onDelete hooks
+): App<CollectionMap<typeof BUILTIN_DEFS & Defs>>;
 ```
 
 The returned `App` object has:
-- `start(port?)` — starts the server (default port 3000)
-- `registerRoutes(fn)` — mount additional Express routes after creation
-- `httpServer` — the underlying Node.js HTTP server
-- `db` — the `TypedDB` instance for direct database access
-- `wss` — the main `WebSocketServer` instance (path configured via `setWsPath`, default `'/rpc'`)
+- `start(port?)` — start the server (default port 3000; templates use 4321)
+- `db` — the `TypedDB` instance, also available globally via imports
+- `httpServer` — the underlying Node `http.Server`
+- `wss` — the main `WebSocketServer` (path set by `setWsPath`, default `/rpc`)
 - `dispatch(name, input, userId)` — invoke an RPC handler programmatically
+- `registerRoutes(fn)` — mount more Express routes after creation
+
+Framework-managed background services start automatically: schema drift check, NATS connection + KV buckets (`TTS`, `RATELIMIT`), data-proxy connection, event counter flush, TTL cleanup for log tables, console / error capture, and ugly.bot log forwarding.
 
 ### `AppConfigurator`
 
-The optional fourth argument to `createApp` receives a configurator object:
+Passed to the optional fourth argument of `createApp`. Every method is optional.
 
 | Method | Description |
 |--------|-------------|
-| `setPages(options)` | Serves pages with Vite (dev) or static files (prod). `options: { pages, renderPage?, clientDistPath? }` |
-| `setUserHelper(helper)` | User lookup for WebSocket auth handshake |
-| `setOnUserCreate(handler)` | Called on first login — must create the user record. `(userId, { email?, phone? }, db) => Promise<void>` |
-| `setAuth(provider)` | Custom `AuthProvider` (default: ugly.bot OAuth). Provider must implement `verify(code)` and `authUrl(origin)` |
-| `setOnSocketMessage(handler)` | Handle raw WebSocket messages. Return `true` to consume, `false` to let the framework handle it |
-| `registerRoutes(fn)` | Mount custom Express routes — `(router: express.Router) => void` |
-| `setWorkerQueue(queue)` | Register a background worker queue with `start()` and `stop()` |
-| `setWsPath(path)` | Override the WebSocket path (default: `'/rpc'`) |
-| `setOnWsAuth(handler)` | Called after a WebSocket session is authenticated. `(ws, userId, req) => void` |
-| `setOnAfterStart(handler)` | Called once after MongoDB, Redis, and NATS are ready. `(db) => Promise<void>` |
-| `setOnMinuteTick(handler)` | Fires every minute (only when `CLOCK_ENABLED=true`). `() => Promise<void>` |
-| `setOnHourlyTick(handler)` | Fires when the hour changes (only when `CLOCK_ENABLED=true`). `(now, currentHour) => Promise<void>` |
-| `setHealthHandler(handler)` | Override the default `GET /health` endpoint handler. `(req, res) => void` |
+| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. In dev, runs Vite in middleware mode; in prod, serves `dist/client`. Provide `renderPage` for SSR on pages with `ssr: true`. |
+| `setUserHelper(helper)` | Customize how the framework reads / writes the `user` collection during WebSocket auth (default looks up by id in a generic `user` collection). |
+| `setOnUserCreate(handler)` | Called on first login with `(userId, { email?, phone? }, db)` — your chance to create the user record. |
+| `setAuth(provider)` | Replace the default ugly.bot OAuth provider. Must implement `verify(code)` and `authUrl(origin)`. |
+| `setOnSocketMessage(handler)` | Single raw-WebSocket message handler. Return `true` to consume, `false` to fall through. |
+| `addSocketMessageHandler(handler)` | Append to the handler chain; first to return `true` wins. |
+| `setWsPath(path)` | Override the WebSocket path (default `/rpc`). |
+| `setOnWsAuth(handler)` | `(ws, userId, req) => void` — fires after a socket session authenticates. |
+| `setOnAfterStart(handler)` | `(db) => Promise<void>` — called once after data-proxy + NATS are ready. |
+| `setOnMinuteTick(fn)` / `setOnHourlyTick(fn)` | Framework-managed periodic callbacks. Only fire when `CLOCK_ENABLED=true`. |
+| `setHealthHandler(fn)` | Override the default `GET /health` response. |
+| `setExperiments(experiments)` | Register `Experiment` definitions for `initSession` / `captureEvent` bucketing. |
+| `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot` (called via internal HTTP). |
+| `setCronTasks(tasks, handlers)` | Legacy cron-only registry. Prefer `setWorkers()`. |
+| `setWorkers(workers, handlers)` | Register named async tasks with optional Zod input schema and cron schedule. Powers `/_workers/manifest`, `POST /_workers/run`, and the cron orchestrator. |
+| `setStrings(config)` | Localization config — framework injects language + critical strings into SSR HTML and exposes `resolveLanguage` / `getCriticalStrings`. |
+| `registerRoutes(fn)` | Mount custom Express routes. |
+| `setWorkerQueue(queue)` | Register a `WorkerQueue` with `start()` / `stop()` for app lifecycle management. |
 
 ### Handler signatures
 
-Handlers are plain async functions — no context object, just `userId` and `input`:
+Handlers are plain async functions — no context object:
 
 ```typescript
 // req() — public, userId may be null
 getPublicData: async (userId: string | null, input) => { ... }
 
-// authReq() — authenticated, 401 auto-enforced, userId always a string
+// authReq() — authenticated, framework returns 401 if no/invalid token
 getMe: async (userId: string, input) => { ... }
 ```
 
-Access `app.db`, storage, and AI clients directly via imports or the `app` object — they are not injected into handlers.
+Inside a handler, access state via captured imports — `app.db`, `storage`, `pgQuery`, `uglyBotRequest`, etc. There is no injected context.
+
+### Built-in framework requests
+
+`createApp` automatically registers several framework handlers, accessible from any client via the normal RPC pipeline:
+
+| Name | Purpose |
+|------|---------|
+| `userGet` | Returns `{ userId, name, avatarUri }` for the given user (or caller). |
+| `initSession` | Records a session start, returns experiment branch assignments. |
+| `captureEvent` | Records a client event tied to the session and experiment branches. |
+| `textGen` / `imageGen` | AI proxies — server-validated, billed through ugly.bot. |
+| `kagiSearch` / `kagiSummarize` / `kagiEnrichWeb` / `kagiEnrichNews` | Web search via ugly.bot. |
+| `uploadUrl` | Issues a presigned PUT for the `temp` bucket. |
+| `submitFeedbackBot` | Forwards `db.captureFeedback` writes for the maintain-bot persona. |
+
+App-provided handlers with the same name override the framework's defaults.
 
 ---
 
 ## Shared API definitions
 
-All type definitions live in `shared/` and are used by both server and client.
+`shared/` is consumed by both server and client. Keep all Zod schemas, types, collections, and route declarations here.
 
 ### Requests (`shared/api.ts`)
 
@@ -135,19 +154,19 @@ All type definitions live in `shared/` and are used by both server and client.
 import { authReq, defineRequests, req, z } from 'ugly-app/shared';
 
 export const requests = defineRequests({
-  // Public request — handler receives (userId: string | null, input)
+  // Public — handler signature: (userId: string | null, input) => Promise<output>
   getPublicData: req({
     input: z.object({ id: z.string() }),
     output: z.object({ data: z.string() }),
   }),
 
-  // Authenticated request — handler receives (userId: string, input)
+  // Authenticated — 401 enforced automatically, userId guaranteed string
   getMe: authReq({
     input: z.object({}),
     output: z.object({ userId: z.string(), email: z.string().optional() }),
   }),
 
-  // With rate limiting
+  // With per-endpoint rate limiting (enforced before handler runs)
   submitFeedback: authReq({
     input: z.object({ type: z.enum(['bug', 'design', 'feature']), message: z.string() }),
     output: z.object({ id: z.string() }),
@@ -156,42 +175,41 @@ export const requests = defineRequests({
 });
 ```
 
-- `req({ input, output })` — defines a public request. Handler signature: `(userId: string | null, input: I) => Promise<O>`.
-- `authReq({ input, output })` — defines an authenticated request. Handler signature: `(userId: string, input: I) => Promise<O>`. Returns 401 automatically if no token.
-- `defineRequests()` — identity wrapper that preserves types.
-- `z` is re-exported from Zod for convenience.
-
-Every endpoint is accessible via both WebSocket (`socket.request(name, input)`) and HTTP (`POST /api/:name { input }`).
+Every request is reachable as **both** `socket.request(name, input)` (WebSocket) and `POST /api/:name { input }` (HTTP). `z` is re-exported from Zod for convenience.
 
 ### Collections (`shared/collections.ts`)
 
 ```typescript
-import { defineCollections } from 'ugly-app/shared';
-import type { Note } from './types';
+import { defineCollections, InferDocType } from 'ugly-app/shared';
+import { z } from 'zod';
+
+export const TodoSchema = z.object({
+  userId: z.string(),
+  text: z.string(),
+  done: z.boolean(),
+});
+export type Todo = InferDocType<typeof TodoSchema>;
 
 export const collections = defineCollections({
-  note: {
-    type: {} as Note,
+  todo: {
+    schema: TodoSchema,
     meta: { cache: true, trackable: true, public: false, cascadeFrom: null },
   },
-  user: {
-    type: {} as User,
-    meta: { cache: true, trackable: false, public: false, cascadeFrom: null },
-  },
 });
 ```
 
-Each collection definition has:
-- `type` — phantom field for TypeScript type inference (never read at runtime)
-- `meta` — runtime metadata:
-  - `cache` — enable in-memory LRU caching for `getDoc`; `setDoc`/`deleteDoc` invalidate it
-  - `trackable` — allow real-time `trackDoc`/`trackDocs` subscriptions via Change Streams
-  - `public` — allows client reads via `getDoc`/`trackDoc`/`trackDocs` without auth
-  - `cascadeFrom` — parent collection name for cascade deletes (or `null`)
-  - `trackKeys?` — fields usable as NATS routing keys for `trackDocs`
-- `onDelete?` — optional async callback invoked on document deletion
+`CollectionMeta`:
+- `cache` — read `getDoc` through an LRU cache; writes invalidate it.
+- `trackable` — enables real-time `trackDoc` / `trackDocs` via NATS.
+- `public` — allow unauthenticated client reads.
+- `cascadeFrom` — parent collection for cascade deletes.
+- `trackKeys?` — fields usable as NATS routing keys for `trackDocs`.
+- `search?: { fields, language? }` — PostgreSQL full-text search columns.
+- `vector?: { dimensions, source }` — Qdrant vector index over the named JSONB path.
+
+All documents extend `DBObject`: `{ _id, version, created, updated }`. Use `dbDefaults()` to stamp the latter three on inserts.
 
-All documents extend `DBObject`: `{ _id: string, version: number, created: Date, updated: Date }`.
+After schema changes, run `npm run db:schema-gen` and then `npm run db:migrate`. The app refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true` only as a last resort).
 
 ### Pages (`shared/pages.ts`)
 
@@ -199,922 +217,513 @@ All documents extend `DBObject`: `{ _id: string, version: number, created: Date,
 import { definePage, definePages } from 'ugly-app/shared';
 
 export const pages = definePages({
-  '':              definePage<{}>({ auth: false }),           // /
-  'note/:noteId':  definePage<{ noteId: string }>(),          // /note/abc
-  'search':        definePage<{ q?: string }>({ auth: false }),// /search?q=foo
-  'blog/*slug':    definePage<{ slug: string }>({ ssr: true }),// /blog/any/path
+  '':              definePage<{}>({ auth: false }),             // /
+  'user/:userId':  definePage<{ userId: string }>(),            // /user/abc
+  'search':        definePage<{ q?: string }>({ auth: false }), // /search?q=foo
+  'blog/*slug':    definePage<{ slug: string }>({ ssr: true }), // /blog/any/path
 });
 export type AppPages = typeof pages;
 ```
 
-- `:param` — single path segment; `*param` — greedy rest (captures slashes)
-- `auth: true` (default) — requires login; `auth: false` — public
-- `ssr: true` — server-renders the page (supply `renderPage` to `setPages()`)
-- The generic type parameter on `definePage<Params>()` types the route's params — it's phantom (never set at runtime)
+- `:param` matches a single path segment; `*param` is greedy (captures slashes).
+- The generic on `definePage<Params>()` is **phantom** — never set at runtime, used for client-side type inference.
+- `auth` defaults to `true`. `ssr` defaults to `false`.
+- Query-string params are declared in `Params` but never appear in the path template.
 
 ---
 
 ## Client
 
-### Entry point (`client/main.tsx`)
-
-```tsx
-import { createRoot } from 'react-dom/client';
-import { AppProvider, createSocket, LoginPopup } from 'ugly-app/client';
-import { requests } from '../shared/api';
-import { RouterProvider } from './router';
-import App from './App';
-
-const token = (window as unknown as { __AUTH_TOKEN__?: string }).__AUTH_TOKEN__;
-const root = createRoot(document.getElementById('root')!);
-const loginPopup = <LoginPopup onSuccess={() => window.location.reload()} />;
-
-if (!token) {
-  root.render(
-    <RouterProvider fallback={<div>404</div>} loginFallback={loginPopup} isAuthenticated={() => false}>
-      <App socket={null} />
-    </RouterProvider>,
-  );
-} else {
-  const userId = JSON.parse(atob(token.split('.')[1]!)).sub as string;
-  const socket = createSocket({ requests, url: '/rpc' });
-  socket.connect(token).then((user) => {
-    root.render(
-      <RouterProvider fallback={<div>404</div>} loginFallback={loginPopup} isAuthenticated={() => true}>
-        <AppProvider socket={socket} userId={userId} user={user}>
-          <App socket={socket} />
-        </AppProvider>
-      </RouterProvider>,
-    );
-  });
-}
-```
-
-### `createSocket()`
-
-Creates a typed WebSocket client for RPC communication.
-
-```typescript
-const socket = createSocket({ requests, url: '/rpc' });
-await socket.connect(token); // returns UserBase
-```
-
-**`AppSocket` methods:**
-
-| Method | Description |
-|--------|-------------|
-| `connect(token)` | Authenticate and connect. Returns the user object |
-| `request(name, input)` | Invoke a typed request (query or mutation) |
-| `getDoc(collection, id)` | Fetch a single document |
-| `getDocs(collection, filter?, opts?)` | Query documents (filter, sort, limit, skip) |
-| `getQuery(collection, pipeline, opts?)` | Run an aggregation pipeline |
-| `trackDoc(collection, id, cb)` | Subscribe to real-time doc changes. Returns unsubscribe fn |
-| `trackDocs(collection, params, cb)` | Subscribe to query results (`keys`, `filter`, `sort`, `limit`, `skip`). Returns unsubscribe fn |
-| `uploadFile(file, key)` | Upload a file via presigned URL |
-| `emit(type, data)` | Send a fire-and-forget message over WebSocket |
-| `send(type, data, timeout?)` | Send a message and wait for a response |
-| `waitForConnection(timeout?)` | Wait until the socket is connected |
-| `connectionState` | Current state: `'connecting'` \| `'connected'` \| `'reconnecting'` \| `'disconnected'` \| `'idle-disconnected'` |
-| `disconnect()` | Close the connection |
-
-**`createSocket()` options:**
-
-| Option | Description |
-|--------|-------------|
-| `requests` | The requests registry from `shared/api.ts` |
-| `url?` | WebSocket path (default: `'/rpc'`) |
-| `buildId?` | Build identifier sent on connect |
-| `onCustomMessage?` | Handle custom server-pushed messages |
-| `getUrlParams?` | Extra query params appended to the WebSocket URL |
-| `messageReviver?` | JSON reviver for incoming messages (e.g. Date parsing) |
-
-### `createHttpClient()`
-
-Creates a typed HTTP client for RPC communication (no WebSocket needed).
-
-```typescript
-import { createHttpClient } from 'ugly-app/client';
-
-const client = createHttpClient({ requests, token: 'eyJ...', baseUrl: '' });
-const result = await client.request('getMe', {});
-```
-
-| Option | Description |
-|--------|-------------|
-| `requests` | The requests registry from `shared/api.ts` |
-| `token?` | Bearer token for authenticated requests |
-| `baseUrl?` | URL prefix (default: `''` — relative paths: `POST /api/:name`) |
+### `bootstrapApp()`
 
-### `AppProvider`
-
-Wraps your app with context for `useApp()`. Provides user info, socket access, popup management, async loading overlay, splash screen, and localization.
+The recommended entrypoint. Handles auth detection, socket creation, optional auto-login through the ugly.bot iframe, and provider wiring.
 
 ```tsx
-<AppProvider
-  socket={socket}
-  userId={userId}
-  user={user}
-  splashScreen={<MySplash />}        // optional
-  loadingOverlay={<MyLoader />}      // optional — shown during runAsync()
-  localizer={(key, params) => t(key)} // optional i18n function
->
-  {children}
-</AppProvider>
+// client/main.tsx
+import { bootstrapApp, FeedbackButton } from 'ugly-app/client';
+import { requests } from '../shared/api';
+import { RouterProvider, RouterView } from './router';
+import './styles.css';
+
+bootstrapApp({
+  requests,
+  RouterProvider,
+  render: () => (
+    <>
+      <RouterView />
+      <FeedbackButton />
+    </>
+  ),
+  strings: { /* optional StringsProviderConfig */ },
+});
 ```
 
-**`useApp()` returns:**
+`BootstrapAppOptions`:
 
 | Field | Description |
 |-------|-------------|
-| `userId` | Current user ID |
-| `user` | Current `UserBase` object |
-| `socket` | The `AppSocket` instance |
-| `showPopup(content)` | Show a popup (returns popup ID) |
-| `hidePopup(id)` | Hide a specific popup |
-| `hideAllPopups()` | Dismiss all popups |
-| `runAsync(label, fn, opts?)` | Run an async operation with loading overlay |
-| `splashDone(step)` | Mark a splash screen step as complete |
-| `localizer(key, params?)` | Localize a string key |
-
-`useAppOptional()` returns the same context or `null` if outside `<AppProvider>`.
+| `requests` | Your `RequestRegistry` (merged with framework requests internally). |
+| `messages?` | Your `MessageRegistry` (merged with framework messages). |
+| `RouterProvider` | The `RouterProvider` returned from `createRouter()`. |
+| `render` | Callback returning the app's UI tree (typically `<RouterView /> + <FeedbackButton />`). |
+| `root?` | Root element / selector (default `'#root'`). |
+| `fallback?` | UI for unmatched routes (default: tiny "404"). |
+| `socketUrl?` | Override the WebSocket path (default `/rpc`). |
+| `strings?` | Localization config — when present, wraps the tree with `<StringsProvider>`. |
+| `keyboard?: false` | Disable the framework `<KeyboardProvider>` wrapper. |
 
-`useLocalizer()` returns the localizer function (falls back to identity if outside provider).
+`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server). If absent, it renders unauthenticated and lets the router show `loginFallback` for auth-guarded pages. If present, it connects the socket, mounts `<AppProvider>`, and renders.
 
-### Router
-
-#### Setup (`client/router.ts`)
+### Routing — `createRouter()`
 
 ```typescript
+// client/router.ts
 import { createRouter } from 'ugly-app/client';
 import { pages } from '../shared/pages';
 import { allPages } from './allPages';
 
-export const { RouterProvider, RouterView, useRouter } = createRouter({ pages, allPages });
+export const { RouterProvider, RouterView, useRouter } = createRouter({
+  pages,
+  allPages,
+});
 ```
 
-`createRouter()` returns three things:
-- **`RouterProvider`** — wrap your app. Props: `children`, `fallback?` (shown before first route resolves), `loginFallback?` (shown for auth-guarded pages when unauthenticated), `isAuthenticated?` (function returning boolean)
-- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?`, `renderPage?`
-- **`useRouter()`** — hook returning the router context
+`createRouter` returns:
 
-#### Page map (`client/allPages.ts`)
+- **`RouterProvider`** — props: `children`, `fallback?`, `loginFallback?`, `isAuthenticated?`, `autoLogin?`. Manages route state, browser history, popups, and `<AutoLoginGate>` (silent iframe-based login check against ugly.bot).
+- **`RouterView`** — renders the active page with animated transitions. Props: `durationMs?`, `easing?`, `transitionComponent?` (replaces `ViewFlipper`), `renderPage?` (sync alternative to `allPages` loaders).
+- **`useRouter()`** — returns the router context (see below).
+
+### Page map — `lazyPage` / `lazyPageLoader`
 
 ```typescript
+// client/allPages.ts
 import { lazyPage, lazyPageLoader } from 'ugly-app/client';
 import type { PageMap } from 'ugly-app/shared';
 import type { AppPages } from '../shared/pages';
 
 export const allPages = {
   ['']:             lazyPage(() => import('./pages/HomePage')),
-  ['note/:noteId']: lazyPage(() => import('./pages/NotePage')),
-  ['search']:       lazyPage(() => import('./pages/SearchPage')),
-  ['slow']:         lazyPageLoader(() => import('./pages/SlowPageLoader')),
+  ['user/:userId']: lazyPage(() => import('./pages/UserPage')),
+  ['slow/:id']:     lazyPageLoader(() => import('./pages/SlowPageLoader')),
 } satisfies PageMap<AppPages>;
 ```
 
-- **`lazyPage(factory)`** — lazy-imports a default-exported React component. The component receives route params as props.
-- **`lazyPageLoader(factory)`** — lazy-imports an async loader function `(params) => Promise<ReactElement>` for routes that need data fetching before render. The loader file is the chunk boundary — it can statically import its page component.
+- **`lazyPage(factory)`** — lazy-imports a default-exported `React.ComponentType<Params>`. The page receives route params as props.
+- **`lazyPageLoader(factory)`** — lazy-imports an async loader `(params) => Promise<ReactElement>`. Use when a route needs data fetching before render. The loader file is the chunk boundary, so it can statically import its page component.
 
-**`lazyPageLoader` example:**
+Example loader:
 
 ```typescript
 // pages/SlowPageLoader.tsx
-import SlowPage from './SlowPage'; // static import OK — same chunk
+import SlowPage from './SlowPage';
 export default async function PageLoader({ id }: { id: string }) {
   const data = await fetchSlowData(id);
   return <SlowPage {...data} />;
 }
 ```
 
-#### Navigation with `useRouter()`
+### Navigation — `useRouter()`
 
 ```typescript
-const { push, replace, back, current, openPopup, closePopup, closeAllPopups } = useRouter();
+const { current, push, replace, back, openPopup, closePopup, closeAllPopups } = useRouter();
 
-push('note/:noteId', { noteId: '123' });   // pushes /note/123
-replace('search', { q: 'hello' });          // replaces with /search?q=hello
-back();                                      // browser back
+push('user/:userId', { userId: '123' });   // → /user/123
+replace('search', { q: 'hello' });         // → /search?q=hello
+back();                                     // browser history back
 
-// current route state
-current.routeName; // e.g. 'note/:noteId'
-current.params;    // e.g. { noteId: '123' }
+current.routeName; // typed union of all route keys
+current.params;    // typed params for the current route
 ```
 
-All route names and params are fully typed based on your `pages` definition.
+All route names and params are fully typed against `pages`. Internally `push` / `replace` are no-ops when `buildUrl()` produces a URL that doesn't match a registered route (and emit a `console.error`).
 
-#### Popups
+### Popups — `openPopup()`
 
-Always use `useRouter().openPopup()` — never build custom fixed overlays.
+Always use `useRouter().openPopup()` for modals, sheets, and menus. The router owns the popup layer, manages the spring animation, and stacks popups z-index-correctly.
 
 ```tsx
 const { openPopup } = useRouter();
 
 const handle = openPopup(<MyContent />, {
-  mode: 'transient',    // 'block' | 'transient' | 'contextMenu'
-  slideFrom: 'bottom',  // 'left' | 'right' | 'top' | 'bottom' | 'none'
-  onClose: () => {},     // called when popup closes
-  containerStyle: {},    // CSS for the content wrapper
-  backgroundStyle: {},   // CSS for the backdrop
+  mode: 'transient',    // 'block' (default) | 'transient' | 'contextMenu'
+  slideFrom: 'bottom',  // 'left' | 'right' | 'top' | 'bottom' | 'none' (default)
+  onClose: () => {},
+  containerStyle: { /* CSS for the content wrapper */ },
+  backgroundStyle: { /* CSS for the backdrop */ },
   animConfig: { duration: 300, easing: myEasingFn },
-  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the popup renderer
+  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the layer renderer
 });
 
 handle.hide(); // dismiss programmatically
 ```
 
-Popup modes:
-- **`block`** (default) — dark backdrop (40% opacity), clicking backdrop does NOT dismiss
-- **`transient`** — light backdrop (20% opacity), clicking backdrop dismisses
-- **`contextMenu`** — same as transient, intended for menus and pickers
-
-`renderLayer` receives `{ content, spring, hide }` — `spring` is an animated value from 0 to 1, `hide` is a function to close the popup.
+Modes:
+- **`block`** (default) — 40% opacity backdrop, **does not** dismiss on backdrop click.
+- **`transient`** — 20% opacity backdrop, **dismisses** on backdrop click.
+- **`contextMenu`** — same as transient, intended for menus and pickers.
 
-#### `Link` component
+`renderLayer` receives `{ content, spring, hide }` — `spring` is an `AnimatedValueRef` driving 0 → 1, `hide` closes the popup.
 
-```tsx
-import { Link } from 'ugly-app/client';
-
-<Link router={router} to="note/:noteId" params={{ noteId: '123' }}>
-  View Note
-</Link>
-```
+### `AppProvider` & `useApp()`
 
-Renders an `<a>` tag with the correct `href`. Intercepts clicks for client-side navigation (ctrl/cmd+click opens in new tab).
-
-#### Animation system
-
-Built-in animation primitives for transitions and popups. `Animated.div` and `Animated.span` accept `AnimatedStyle` — a style object where any CSS property can be an `AnimatedValueRef` or a `TransformedValue` instead of a static value.
+`bootstrapApp` mounts `<AppProvider>` automatically after socket connect. Use `useApp()` inside any page to access the active user and socket.
 
 ```typescript
-import {
-  Animated,
-  createAnimatedValue,
-  useAnimatedValue,
-  easingFunctions,
-  FadeIn,
-  SlideFromBottom,
-  SlideFromRight,
-} from 'ugly-app/client';
-
-// Create an animated value (0->1 spring)
-const spring = createAnimatedValue(0);
-spring.start(1, { duration: 300, easing: easingFunctions.easeOut });
-
-// Use in components — animated properties bypass React re-renders via direct DOM mutation
-<Animated.div style={{ opacity: spring.to((v) => String(v)) }}>
-  Content
-</Animated.div>
-
-// Hook version — creates and manages an animated value in a component
-const anim = useAnimatedValue(0);
-
-// Pre-built entrance animations (wrap any children)
-<FadeIn>{children}</FadeIn>
-<SlideFromBottom>{children}</SlideFromBottom>
-<SlideFromRight>{children}</SlideFromRight>
+const {
+  userId,        // current user id
+  user,          // UserBase doc
+  socket,        // AppSocket — typed RPC client
+  uglyBotSocket, // optional UglyBotSocket for direct platform calls (STT/TTS, etc.)
+  showPopup,     // legacy popup API (prefer useRouter().openPopup)
+  hidePopup,
+  hideAllPopups,
+  runAsync,      // runAsync('label', async () => { ... }) — shows loading overlay
+  splashDone,    // mark a splash-screen step complete
+  localizer,     // (key, params?) => string — alias for useLocalizer
+} = useApp();
 ```
 
-**`AnimatedValueRef` API:**
-
-| Member | Description |
-|--------|-------------|
-| `current` | Current numeric value |
-| `target` | Target value |
-| `isAnimating` | Whether an animation is in progress |
-| `start(target, config?)` | Animate to target. Returns `Promise<void>` |
-| `set(value)` | Jump to value immediately (no animation) |
-| `stop()` | Cancel the current animation |
-| `subscribe(cb)` | Subscribe to value changes. Returns unsubscribe fn |
-| `to(transform)` | Create a transformed value for use in `Animated` styles |
-
-**`AnimConfig`:** `{ duration?, easing?, onRest?, onUpdate?, immediate? }`
+`useAppOptional()` returns `null` outside the provider; `useLocalizer()` returns a localizer that falls back to identity.
 
-Available easings: `easingFunctions.linear`, `easeIn`, `easeOut`, `easeInOut`, `springGentle`, `springSnappy`, `springBouncy`, `slow`.
+### `Link` component
 
-Additional animation hooks:
-- `useAnimatedTransition` / `useAnimatedPresence` — mount/unmount transitions with phase tracking
-- `useScrollAnimation` / `useStaggerAnimation` — scroll-driven and staggered entrance animations
+```tsx
+import { Link } from 'ugly-app/client';
 
-#### Screenshot capture
+<Link router={router} to="user/:userId" params={{ userId: '123' }}>View profile</Link>
+```
 
-```typescript
-import { captureScreenshot } from 'ugly-app/client';
+Renders an `<a>` with the right `href`, intercepts clicks for client-side navigation, and lets `ctrl/cmd+click` open in a new tab.
 
-const dataUrl = await captureScreenshot(); // captures the current viewport
-```
+### Direct socket access
 
-#### UI components
+`AppSocket` is exposed through `useApp().socket`. Common methods:
 
-`ugly-app/client` exports a set of built-in UI components:
+| Method | Description |
+|--------|-------------|
+| `request(name, input)` | Invoke a typed RPC handler. |
+| `getDoc(collection, id)` | Server-mediated doc fetch. |
+| `getDocs(collection, filter?, opts?)` | Filtered query. |
+| `trackDoc(collection, id, cb)` | Live subscription — returns unsubscribe. |
+| `trackDocs(collection, params, cb)` | Live filtered subscription. |
+| `uploadFile(file, key)` | Presigned upload to the `temp` bucket. |
+| `connectionState` | `'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`. |
+| `disconnect()` | Close the connection. |
 
-`Button`, `Card`, `EnumInput`, `Header`, `Image`, `Input`, `Modal`, `PageLayout`, `Panel`, `PopupPanel`, `Pressable`, `ScrollView`, `SettingGroup`, `Text`, `Toast`, `View`, `ResponsiveGrid`, `TabPicker`, `HeaderTabPicker`, `TabContent`, `TabContentAllActive`
+For pure HTTP (no WebSocket), use `createHttpClient({ requests, token?, baseUrl? })`.
 
 ---
 
 ## Auth
 
-Auth uses HttpOnly cookies with server-side JWT injection. No localStorage needed.
+ugly-app uses HttpOnly cookies and server-side JWT injection — no `localStorage`, no client-side token handling.
 
 **Flow:**
 
-1. User opens `<LoginPopup />` which redirects to OAuth at `https://ugly.bot/oauth`
-2. Browser posts the auth code to `POST /auth/verify` — server sets `auth_token` HttpOnly cookie
-3. On every page load the server refreshes the cookie and injects the token into HTML:
-   ```html
-   <script>window.__AUTH_TOKEN__ = "eyJ..."</script>
-   ```
-4. Client reads `window.__AUTH_TOKEN__` synchronously and connects the WebSocket
-
-**Logout:**
+1. Unauthenticated user lands on a page; the optional `<AutoLoginGate>` opens a hidden iframe to `https://ugly.bot/iframe-auth` to check for an existing platform session.
+2. If found, the iframe posts an OAuth code back; the client POSTs to `/auth/verify`; the server exchanges it through `uglyBotAuthProvider`, sets the `auth_token` HttpOnly cookie, and the page reloads authenticated.
+3. If not found (or timeout after 4 s), `<RouterProvider>` shows `loginFallback` for auth-required routes. The default fallback is `<LoginPopup>`, which opens `https://ugly.bot/oauth` in a popup window.
+4. On every authenticated request, the server verifies the cookie token by calling `${UGLY_BOT_URL}/verify` and injects `window.__AUTH_TOKEN__` into the HTML so the client can pass it on the WebSocket handshake.
 
-```typescript
-await fetch('/auth/logout', { method: 'POST' });
-window.location.reload();
-```
+**Token-in-URL embed mode:** any GET request with `?token=<JWT>` will, if the token verifies against ugly.bot, set the cookie and 302-redirect to the same URL without the token — letting any page be embedded in an iframe.
 
-**Built-in auth endpoints:**
+**Built-in routes** (mounted on every app):
 
 | Endpoint | Description |
 |----------|-------------|
-| `POST /auth/verify` | Exchange OAuth code for a session cookie |
-| `POST /auth/logout` | Clear the auth cookie |
-| `GET /auth/token` | Refresh and return the current token |
-| `GET /auth/url` | Get the OAuth popup URL |
+| `POST /auth/verify` | Exchange an OAuth `code` for a session cookie. |
+| `POST /auth/logout` | Clear the cookie. |
+| `GET /auth/token` | Refresh and return the current token (used by clients that need an explicit token). |
+| `GET /auth/url` | Return the OAuth popup URL. |
 
-**Custom auth provider:**
+**Custom provider:**
 
 ```typescript
 configurator.setAuth({
-  verify: async (code: string) => ({ userId: '...', email: '...' }),
-  authUrl: (origin: string) => 'https://my-oauth.com/authorize?...',
+  verify: async (code) => ({ userId: '...', token: 'platform-issued-jwt' }),
+  authUrl: (origin) => `https://my-oauth.example/authorize?origin=${origin}`,
   registerRoutes: (router) => { /* optional extra routes */ },
 });
 ```
 
-The `AuthProvider` interface:
+**Server-side helpers** (`ugly-app`):
 
-```typescript
-interface AuthProvider {
-  verify(code: string): Promise<{ userId: string; email?: string; phone?: string; token?: string }>;
-  authUrl(origin: string): string;
-  registerRoutes?(router: express.Router): void;
-}
-```
+- `verifyToken(token)` — verifies a token against ugly.bot and returns the `userId`.
+- `getRequestUser(req)` — synchronous decode of the per-project `UGLY_PROJECT_TOKEN` cookie set by ugly.bot's wake-on-traffic gate. Returns `{ userId } | null` without a network round-trip; safe to use as the primary auth check in deployed-app handlers.
 
 ---
 
-## Database (`TypedDB`)
+## Database — `TypedDB`
 
-Access via `app.db` or by importing `createTypedDB` / `getMongoClient` from `'ugly-app'`.
-
-All methods accept either a `CollectionDef` object (from `defineCollections`) or a plain collection name string as the first argument.
+Access via `app.db` or via `import { app } from './your-app-module'`. All methods accept a `CollectionDef` (from `defineCollections`) or a plain collection name string.
 
 ### Writing
 
 ```typescript
-// Insert or replace a document
-await db.setDoc(collections.note, doc);
-await db.setDoc(collections.note, doc, { skipIfExists: true });
-
-// Partial update — only specified fields (supports dot-notation paths)
-await db.setDocFields(collections.note, id, { title: 'New title' });
+await db.setDoc(collections.note, doc);                                  // upsert
+await db.setDoc(collections.note, doc, { skipIfExists: true });          // insert-only
 
-// Partial update — returns null if document doesn't exist (no error)
-const doc = await db.setDocFieldsOrIgnore(collections.note, id, { title });
+await db.setDocFields(collections.note, id, { title: 'New' });           // partial; throws if missing
+await db.setDocFieldsOrIgnore(collections.note, id, { title });          // returns null if missing
+await db.setDocFieldsOrCreate(collections.note, id, { title }, default); // upsert with default
 
-// Partial update — creates the document if it doesn't exist (obj = default doc for insert)
-await db.setDocFieldsOrCreate(collections.note, id, { title }, defaultDoc);
-
-// MongoDB update operators ($inc, $addToSet, $pull, $unset, $set)
-await db.setDocOp(collections.note, id, { $inc: { views: 1 } });
-await db.setDocOpOrIgnore(collections.note, id, { $inc: { views: 1 } }); // no error if missing
+await db.setDocOp(collections.note, id, { $inc: { views: 1 } });         // MongoDB-style ops
+await db.setDocOpOrIgnore(collections.note, id, { $inc: { views: 1 } });
 ```
 
+Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`, `$set`. All keys are dot-notation, fully typed against the collection's schema.
+
 ### Reading
 
 ```typescript
-const note  = await db.getDoc(collections.note, id);
-const notes = await db.getDocs(collections.note, { userId }, { sort: { created: -1 }, limit: 20 });
+const doc  = await db.getDoc(collections.note, id);
+const docs = await db.getDocs(collections.note, { userId }, { sort: { created: -1 }, limit: 20 });
 
-// Aggregation pipeline
+// Typed SQL-native query API (preferred for new code)
+const notes = await db.find(collections.note, { userId, done: { $ne: true } }, { sort: { created: -1 }, limit: 20 });
+const count = await db.findCount(collections.note, { userId });
+const sample = await db.findRandom(collections.note, { userId }, 5);
+
+// Aggregation pipelines (legacy / advanced)
 const results = await db.getQuery<MyResult>('note', pipeline, { skip, limit });
-const count   = await db.getQueryCount('note', pipeline);
-const raw     = await db.getQueryRaw<T>('note', pipeline);
+const total   = await db.getQueryCount('note', pipeline);
 
-// Dynamic/untyped access (when collection name is a runtime string)
-const doc  = await db.rawGetDoc(collectionName, id);
-const docs = await db.rawGetDocs(collectionName, filter);
+// Dynamic / untyped access — when the collection name is a runtime string
+await db.rawGetDoc('note', id);
+await db.rawGetDocs('note', filter);
 ```
 
 ### Deleting
 
 ```typescript
-await db.deleteDoc(collections.note, id);           // single doc (cascades via cascadeFrom)
-await db.deleteQuery(collections.note, { userId }); // bulk delete by filter (cascades + calls onDelete)
+await db.deleteDoc(collections.note, id);                  // cascade-deletes children
+await db.deleteWhere(collections.note, { userId });        // typed bulk delete
+await db.deleteQuery(collections.note, { userId });        // legacy untyped bulk delete
+```
+
+Pass `deleteHandlers` as the 5th argument to `createApp` to run per-collection `onDelete` callbacks.
+
+### Search
+
+```typescript
+// Full-text search — requires `search: { fields, language? }` on the collection
+const hits = await db.searchDocs(collections.note, 'react hooks', { limit: 10 });
+
+// Vector search — requires `vector: { dimensions, source }` (uses Qdrant)
+const similar = await db.vectorSearch(collections.note, embeddingVector, { limit: 10 });
 ```
 
 ### Caching
 
 ```typescript
-const cached = db.cacheGet<MyType>(key);
+db.cacheGet<MyType>(key);
 db.cacheSet(key, value, ttlMs);
-db.cacheDelete(key);
-const key = db.cacheKey('prefix', id); // generate a cache key
+db.cacheDelete(key);                                       // broadcasts invalidation via NATS
+const k = db.cacheKey('prefix', id);
 ```
 
 ### Helpers
 
 ```typescript
-import { createUserHelper } from 'ugly-app';
-import { dbDefaults } from 'ugly-app/shared';
+import { createUserHelper, dbDefaults } from 'ugly-app';
 
-// dbDefaults() returns { version: 1, created: new Date(), updated: new Date() }
-const doc = { id: newId(), ...dbDefaults(), title: 'Hello' };
+const newDoc = { _id: crypto.randomUUID(), ...dbDefaults(), title: 'Hi' };
+//                                          ^^^^^^^^^^^^^^^ { version: 1, created, updated }
 
-// createUserHelper — typed user CRUD with get, set, update methods
 const userHelper = createUserHelper<User>(collections.user);
 const user = await userHelper.get(db, userId);
-await userHelper.set(db, { id: userId, ...dbDefaults(), email });
 ```
 
-### Indexes
+### Direct SQL & infra
 
-Indexes are defined on the collection definition in `shared/collections.ts`:
+Imports available from `ugly-app`:
 
-```typescript
-export const collections = defineCollections({
-  note: {
-    type: {} as Note,
-    meta: { cache: true, trackable: true, public: false, cascadeFrom: null },
-    indexes: [
-      { fields: { userId: 1, created: -1 } },
-      { fields: { title: 1 }, unique: true },
-    ],
-  },
-});
-```
-
-After adding or modifying indexes:
-1. Run `npm run db:schema-gen` to generate a migration file
-2. Run `npm run db:migrate` to apply the migration
+- `pgQuery(sql, params?)` — parameterized SQL on the data proxy.
+- `ensureTable(...)`, `tableExists(...)`, `ensureSearchColumn(...)`.
+- `ensureQdrantCollection(...)`, `upsertVector(...)`, `searchVectors(...)`, `deleteVector(...)`, `deleteQdrantCollection(...)`.
+- `connectNats()`, `natsPublish(subject, payload)`, `natsSubscribe(subject, cb)`, `ensureKvBucket(name, opts)`, `jsPublish(...)`, `jsConsumerCreate(...)`, `jsConsumerConsume(...)`.
+- `subscribeCollection`, `subscribeDoc`, `subscribeDocKey` — NATS subjects emitted by the data proxy on writes.
 
 ---
 
 ## AI
 
-### Text generation
+AI calls are proxied through ugly.bot — your app never holds an AI provider key. Pass `UGLY_BOT_TOKEN` in the environment and the framework handles routing, balance tracking, retries, and per-user billing.
+
+### Server-side text generation
 
 ```typescript
 import { createTextGenClient } from 'ugly-app';
-const textGen = createTextGenClient();
+const textGen = createTextGenClient(userId);
 
-const text   = await textGen.generate(messages);
-const json   = await textGen.generateJson(schema, messages);   // Zod schema, retries on parse failure
-const result = await textGen.generateWithTools(messages, tools); // automatic tool-call loop
+const text = await textGen.generate(messages, { model: 'gemini_2_5_flash' });
 ```
 
-| Provider | `provider` value | Default model | JSON | Tools | Vision |
-|----------|-----------------|---------------|------|-------|--------|
-| Together AI | `'together'` | Llama-4-Maverick-17B-128E | yes | yes | yes |
-| Anthropic | `'claude'` | claude-sonnet-4-6 | yes | yes | yes |
-| OpenAI | `'openai'` | gpt-4o | yes | yes | yes |
-| Google | `'google'` | gemini-2.5-flash | yes | yes | yes |
-| Groq | `'groq'` | llama-3.3-70b-versatile | yes | yes | no |
-| Fireworks | `'fireworks'` | llama-v3p1-70b-instruct | yes | yes | yes |
-| Kie.ai | `'kie'` | gemini-2.0-flash | yes | yes | yes |
+Or call the framework `textGen` request directly:
+
+```typescript
+import { uglyBotRequest } from 'ugly-app';
+const { message } = await uglyBotRequest<{ message: { content: string } }>('textGen', {
+  model: 'gemini_2_5_flash',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  options: { maxTokens: 512 },
+});
+```
 
-Use `provider: 'auto'` (default) to let the system pick based on requirements.
+Available models are exposed via `textGenModels` / `textGenModelData` from `ugly-app` — the platform supports Claude, GPT, Gemini, Together, Groq, Fireworks, and Kie families.
 
-### Image generation
+### Server-side image generation
 
 ```typescript
 import { createImageGenClient } from 'ugly-app';
-const imageGen = createImageGenClient();
+const imageGen = createImageGenClient(userId);
 
-const url = await imageGen.generate(prompt, { width: 1024, height: 1024 });
+const url = await imageGen.generate('A red panda eating noodles', { model: 'flux_schnell' });
 ```
 
-| Provider | `provider` value |
-|----------|-----------------|
-| Together AI (FLUX schnell) | `'together'` |
-| FAL (FLUX pro) | `'fal'` |
-| Google (Imagen 3) | `'google'` |
-| Wavespeed | `'wavespeed'` |
-| Kie.ai (Kolors) | `'kie'` |
+`imageGenModels` / `imageGenModelData` enumerate available models (Together FLUX, FAL, Google Imagen, Wavespeed, Kie Kolors).
 
 ### Embeddings
 
 ```typescript
 import { createEmbeddingClient, cosineSimilarity } from 'ugly-app';
 const embeddings = createEmbeddingClient();
-const similarity = cosineSimilarity(vectorA, vectorB);
-```
-
-### Speech-to-text (STT)
-
-Server-side STT uses a provider registry pattern. Providers auto-register when their API key env var is set.
-
-```typescript
-import { registerSTTProvider, selectSTTProvider, getAllSTTProviders } from 'ugly-app';
-```
-
-**Built-in STT providers:**
-
-| Provider | Import | Env var | Mode |
-|----------|--------|---------|------|
-| Deepgram (nova-2) | `deepgramSTTProvider` | `DEEPGRAM_API_KEY` | Real-time streaming via WebSocket |
-| OpenAI Whisper | `openAIWhisperSTTProvider` | `OPENAI_API_KEY` | Batch (buffers audio, transcribes on stop) |
-| Groq Whisper | `groqWhisperSTTProvider` | `GROQ_API_KEY` | Batch |
-
-**STT provider interface:**
-
-```typescript
-interface STTProvider {
-  name: string;
-  apiKeyEnv: string;
-  connect(
-    onTranscript: (result: STTTranscript) => void,
-    onError: (err: string) => void,
-    lang?: string,
-    options?: STTConnectOptions,
-    onUsage?: (report: STTUsageReport) => void,
-  ): Promise<STTSession>;
-}
-
-interface STTSession {
-  sendAudio(pcm16: Buffer): void; // PCM16 at 16kHz mono
-  stop(): Promise<void>;
-}
-
-interface STTTranscript { text: string; isFinal: boolean; lang?: string; words?: STTWord[] }
-```
-
-**Client-side hook:**
-
-```typescript
-import { useSTT } from 'ugly-app/client';
-const { start, stop, transcript, isListening } = useSTT(socket, options);
-```
-
-### Text-to-speech (TTS)
-
-```typescript
-import { registerTTSProvider, selectTTSProvider, azureTTSProvider } from 'ugly-app';
-```
-
-**Built-in TTS provider:**
-
-| Provider | Import | Env vars |
-|----------|--------|----------|
-| Azure TTS | `azureTTSProvider` | `AZURE_TTS_KEY`, `AZURE_TTS_REGION` |
-
-**TTS provider interface:**
-
-```typescript
-interface TTSProvider {
-  name: string;
-  apiKeyEnv: string;
-  stream(text: string, voice: string, options?: TTSStreamOptions): AsyncGenerator<TTSChunk>;
-}
-
-interface TTSChunk {
-  audio: Buffer;       // PCM16, mono, 24kHz
-  word?: string;
-  startMs?: number;
-  durationMs?: number;
-  visemes?: TTSViseme[]; // When requestVisemes=true (for lip sync)
-}
-```
-
-**Client-side hook:**
-
-```typescript
-import { useTTS, AudioPlayer, AudioRecorder } from 'ugly-app/client';
+const vector = await embeddings.embed('hello world');
+const sim = cosineSimilarity(vectorA, vectorB);
 ```
 
 ### Web search
 
 ```typescript
-import { createWebSearchClient, registerWebSearchProvider } from 'ugly-app';
+import { createWebSearchClient } from 'ugly-app';
 const search = createWebSearchClient(userId);
 
-const results = await search.search({ query: 'hello', limit: 10 });
-const summary = await search.summarize({ url: 'https://...' });
-const web     = await search.enrichWeb({ query: 'topic' });
-const news    = await search.enrichNews({ query: 'topic' });
+await search.search({ query: 'react 19', limit: 10 });
+await search.summarize({ url: 'https://...' });
+await search.enrichWeb({ query: 'topic' });
+await search.enrichNews({ query: 'topic' });
 ```
 
-**`WebSearchClient` methods:**
-
-| Method | Description |
-|--------|-------------|
-| `search({ query, limit? })` | Web search — returns `{ items, related? }` |
-| `summarize({ url?, text? })` | Summarize a URL or text — returns summary string |
-| `enrichWeb({ query })` | Enriched web results |
-| `enrichNews({ query })` | Enriched news results |
-
-Built-in providers: Kagi (`KAGI_API_KEY`) and UglyBot.
+### Client-side AI calls
 
-### Custom providers
+Calls from React components go through the framework RPC pipeline — no token plumbing in the browser:
 
 ```typescript
-import { registerTextGenProvider, registerImageGenProvider, registerEmbeddingProvider } from 'ugly-app';
+import { callTextGen, callJsonGen, callImageGen } from 'ugly-app/client';
 
-registerTextGenProvider('myProvider', myTextGenImplementation);
-registerImageGenProvider('myProvider', myImageGenImplementation);
-registerEmbeddingProvider('myProvider', myEmbeddingImplementation);
+const text  = await callTextGen({ messages, model: 'gemini_2_5_flash' });
+const json  = await callJsonGen({ messages, schema, model: 'gemini_2_5_flash' });
+const image = await callImageGen({ prompt: 'a corgi astronaut', model: 'flux_schnell' });
 ```
 
-### Client-side AI calls
+### STT / TTS
 
-The client can call AI through the server proxy without managing tokens directly:
+Speech goes **directly** from the browser to ugly.bot — never proxied through your app server.
 
 ```typescript
-import { callTextGen, callJsonGen, callImageGen } from 'ugly-app/client';
+import { useSTT, useTTS, AudioPlayer, AudioRecorder } from 'ugly-app/client';
 
-const text  = await callTextGen(input);
-const json  = await callJsonGen(input);
-const image = await callImageGen(input);
+const { start, stop, transcript, isListening } = useSTT(socket, options);
+const { speak, stop: stopTTS } = useTTS(socket, { voice: 'alloy' });
 ```
 
-These call `POST /ai/request` (same-origin, avoids CORS). The server verifies the user JWT and forwards to `https://ugly.bot` using the `UGLY_BOT_TOKEN` env var.
-
 ---
 
 ## Storage
 
+S3-compatible. Two logical buckets:
+
+- **`temp`** — short-lived uploads (presigned PUT from the browser).
+- **`public`** — durable, served by CDN.
+
+Server-side:
+
 ```typescript
-// Server-side — put a file
-const url = await storage.put('temp', key, buffer, 'image/png');
+import { createStorageClient } from 'ugly-app';
+const storage = createStorageClient();
 
-// Move from temp to public bucket
+await storage.put('temp', key, buffer, 'image/png');
 const publicUrl = await storage.moveToPublic(tempKey, destKey);
-
-// Get a public URL
 const url = storage.url('public', destKey);
-
-// Browser direct upload via presigned URL
 const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);
 ```
 
-Buckets: `'public'` and `'temp'`. Supports Cloudflare R2 (production) or MinIO (dev).
+Client-side, use `socket.uploadFile(file, key)` — it requests a presigned URL via the built-in `uploadUrl` framework request and streams the upload. In dev, uploads go through a same-origin `/_s3` proxy to avoid CORS with local MinIO.
 
-The `StorageClient` interface:
-
-```typescript
-interface StorageClient {
-  put(bucket: 'public' | 'temp', key: string, body: Buffer, contentType: string): Promise<string>;
-  moveToPublic(tempKey: string, destKey: string): Promise<string>;
-  url(bucket: 'public' | 'temp', key: string): string;
-  presignedPut(bucket: 'temp', key: string): Promise<{ uploadUrl: string; resultUrl: string }>;
-}
-```
-
-Static build-time assets go in `client/public/`. Never hardcode `/asset/...` paths — use the `buildId` from `shared/Build.ts`.
+`STORAGE_KEY_PREFIX` (env) prefixes all keys — useful for per-environment isolation.
 
 ---
 
-## Billing
-
-Usage-based billing with per-user limits, global provider limits, pre-paid credits, and threshold alerts.
+## Workers & cron
 
 ```typescript
-import { initBillingGateway, getBillingGateway } from 'ugly-app';
+// shared/cron.ts
+import { defineWorkers, z } from 'ugly-app/shared';
 
-const billing = initBillingGateway(db, {
-  global: { hourlyUsd: 100, thresholdPct: 0.8 },
-  providers: {
-    openai: { hourlyUsd: 50, thresholdPct: 0.9 },
+export const cronTasks = defineWorkers({
+  dailyCleanup: {
+    schedule: '0 3 * * *',   // every day at 03:00 UTC
+    description: 'Delete completed todos older than 30 days',
+  },
+  resyncSearch: {
+    inputSchema: z.object({ since: z.string().datetime() }),
+    description: 'Re-embed search vectors since the given ISO timestamp',
   },
-  profitMarginPct: 0.2, // 20% markup on costs
-});
-
-// Charge a user
-await billing.charge({
-  userId: '...',
-  provider: 'openai',
-  model: 'gpt-4o',
-  type: 'textGen',       // 'textGen' | 'imageGen' | 'stt' | 'tts' | 'embedding' | 'service'
-  costUsd: 0.03,
-  inputTokens: 1000,
-  outputTokens: 500,
 });
+```
 
-// Pre-flight check
-const canPay = await billing.canCharge(userId, 0.05);
+```typescript
+// server/index.ts
+const cronHandlers: WorkerHandlers<typeof cronTasks> = {
+  dailyCleanup: async () => { /* runs on schedule */ },
+  resyncSearch: async ({ since }) => { /* runs on manual trigger from studio */ },
+};
 
-// Grant credits
-await billing.grantCredit(userId, 10.00);
+configurator.setWorkers(cronTasks, cronHandlers);
+```
 
-// Query spend
-const usage = await billing.getSpend(userId, { from, to });
+Each worker can have `inputSchema`, `outputSchema`, `schedule`, `timeout`, `description`. Workers without a schedule are still invocable via `POST /_workers/run` (auth: localhost in dev, `Authorization: Bearer $CRON_SECRET` in prod). Scheduled workers also appear in `/_cron/manifest` for the deploy orchestrator.
 
-// Threshold callbacks
-billing.setUserThresholdCallback((userId, period, spend, limit) => { /* alert */ });
-billing.setGlobalThresholdCallback((period, spend, limit) => { /* alert */ });
-```
+---
 
-**Per-user limits** are resolved via `setUserLimitHook()`:
+## Localization
 
 ```typescript
-billing.setUserLimitHook(async (userId) => ({
-  hourlyUsd: 5,
-  dailyUsd: 50,
-  weeklyUsd: 200,
-  thresholds: { hourly: 0.8, daily: 0.9, weekly: 0.95 },
-}));
+configurator.setStrings({
+  defaultLang: 'en',
+  langs: ['en', 'es'],
+  criticalKeys: ['app.title', 'nav.home'],
+  getTable: (lang) => tables[lang] ?? tables.en,
+});
 ```
 
-The billing state machine tracks spend across hourly, daily, and weekly windows. Global and per-provider limits are always enforced; user credits act as a fallback when user limits are exceeded but never bypass global limits.
+The framework injects `window.__LANG__`, `window.__STRINGS_VERSION__`, and `window.__CRITICAL_STRINGS__` into SSR HTML. Use `useLocalizer()` / `useStrings()` / `useLang()` / `useChangeLanguage()` on the client.
 
 ---
 
 ## Experiments
 
-A/B testing with deterministic user bucketing and event tracking.
-
 ```typescript
-// shared/experiments.ts
 import type { Experiment } from 'ugly-app/shared';
 
 export const experiments: Experiment[] = [
   {
     id: 'new-onboarding',
-    name: 'New Onboarding Flow',
-    description: 'Test the redesigned onboarding',
+    name: 'New Onboarding',
     active: true,
     branches: [
-      { id: 'control', name: 'Control', weight: 50 },
-      { id: 'variant', name: 'Variant', weight: 50 },
+      { id: 'control', weight: 50 },
+      { id: 'variant', weight: 50 },
     ],
-    events: ['ONBOARDING_COMPLETE', 'ONBOARDING_SKIP'],
+    events: ['ONBOARDING_COMPLETE'],
   },
 ];
-```
-
-**Server-side assignment:**
-
-```typescript
-import { getExperimentAssignments, getExperimentBranch } from 'ugly-app';
-
-// Get all active experiment assignments for a user
-const branches = getExperimentAssignments(userId, sessionId, experiments);
-// => { 'new-onboarding': 'variant' }
-
-// Get a single experiment branch
-const branch = getExperimentBranch(experiment, userId, sessionId);
-```
-
-Bucketing uses a deterministic hash of `experimentId:userId` (or `sessionId` if no user), so the same user always gets the same branch. Weights control the relative distribution across branches.
-
----
-
-## Event logging
-
-Server-side event capture for analytics, tied to experiments.
-
-```typescript
-import { eventLogCapture, eventLogServerCapture } from 'ugly-app';
-
-// Capture with returned eventId
-const { eventId } = await eventLogCapture({
-  eventName: 'BUTTON_CLICK',
-  sessionId,
-  userId,
-  properties: { page: 'home' },
-  experimentBranches: branches,
-}, userId);
-
-// Fire-and-forget server capture
-await eventLogServerCapture('SESSION_START', { source: 'web' }, sessionId, userId, branches);
-```
-
-**Query functions:**
-
-| Function | Description |
-|----------|-------------|
-| `eventLogGetList(input)` | Paginated event list (cursor, date range, filters) |
-| `eventLogGetTopUsers(input)` | Top users by event count |
-| `eventLogGetTopSessions(input)` | Top sessions by event count |
-| `eventLogGetTopEvents(input)` | Top events by frequency |
-| `eventLogGetCounts(input)` | Time-series counts (granularity: `'seconds'` \| `'minutes'` \| `'days'`) |
-| `eventLogGetUniqueUsersCounts(input)` | Unique users per time interval |
-| `eventLogGetUniqueSessionsCounts(input)` | Unique sessions per time interval |
-
----
-
-## Additional server APIs
-
-### Email
-
-```typescript
-import { sendEmail, sendTemplateEmail, loadEmailTemplate } from 'ugly-app';
-
-await sendEmail({ to: 'user@example.com', subject: 'Hello', html: '<p>Hi</p>' });
-await sendTemplateEmail('welcome', { name: 'Alice' }, { to: 'user@example.com' });
-```
-
-### Push notifications
-
-```typescript
-import { sendPush, sendFcmPush } from 'ugly-app';
-
-await sendPush(userId, { title: 'New message', body: 'You have a new message' });
-```
-
-### NATS (pub/sub)
-
-```typescript
-import { natsPublish, natsSubscribe, subscribeCollection, subscribeDoc } from 'ugly-app';
-
-natsPublish('my.subject', payload);
-const sub = natsSubscribe('my.subject', (msg) => { /* ... */ });
-sub(); // unsubscribe
-```
 
-### Redis
-
-```typescript
-import { getRedisClient, redisGet, redisSet, redisDel, redisPublish, redisSubscribe } from 'ugly-app';
-const redis = getRedisClient();
-```
-
-### Worker queues
-
-```typescript
-import { createWorkerQueue } from 'ugly-app';
-
-const queue = createWorkerQueue({
-  streamName: 'JOBS',        // NATS stream name (default: 'JOBS')
-  concurrency: 10,           // max concurrent jobs (default: 10)
-  maxRetries: 3,             // max retry attempts (default: 3)
-  clockServerOnly: true,     // only process if IS_CLOCK_SERVER=true (default: true)
-});
-
-queue.registerHandler<MyPayload>('sendEmail', async (job) => {
-  job.working(); // extend ack deadline for long-running jobs
-  await doWork(job.payload);
-});
-
-await queue.enqueue('sendEmail', { to: 'user@example.com' }, { delay: 5000 });
-
-configurator.setWorkerQueue(queue); // register with the app for lifecycle management
-```
-
-**Scheduled tasks** — prevent duplicate enqueuing via MongoDB upsert:
-
-```typescript
-import { enqueueTask } from 'ugly-app';
-
-await enqueueTask(taskDoc, queue, { delay: 60000 });
-```
-
-### Billing
-
-```typescript
-import { initBillingGateway, getBillingGateway } from 'ugly-app';
-
-await initBillingGateway({ /* config */ });
-const billing = getBillingGateway();
-```
-
-### Client error capture
-
-```typescript
-import { captureClientError, initClientLogger } from 'ugly-app/client';
-
-initClientLogger(); // call once at startup — captures unhandled errors
-captureClientError(error); // manually report an error to POST /api/client-error
-```
-
-### Feedback
-
-```typescript
-import { FeedbackButton, setFeedbackContext, clearFeedbackContext } from 'ugly-app/client';
-
-// Render the built-in feedback button (bottom-right, always at [data-id="feedback-button"])
-<FeedbackButton />
-
-// Set contextual data attached to feedback submissions
-setFeedbackContext({ page: 'editor', noteId: '123' });
-clearFeedbackContext();
+configurator.setExperiments(experiments);
 ```
 
-Server-side, `getFeedbackHandlers(maintainBotUserId)` provides the RPC handlers for submitting and managing feedback. User feedback history is available at `GET /my_feedback` (requires auth cookie, returns markdown).
-
-### Rate limiting
-
-Rate limiting is configured per-endpoint in the request definition:
-
-```typescript
-submitFeedback: authReq({
-  input: z.object({ ... }),
-  output: z.object({ ... }),
-  rateLimit: { max: 20, window: 60 },  // 20 requests per 60 seconds
-})
-```
-
-The framework enforces rate limits automatically before calling the handler.
+Bucketing is deterministic: `hash(experimentId + userId)` (or `sessionId` for unauthenticated users). The framework's `initSession` / `captureEvent` requests automatically tag events with the user's branch assignments.
 
 ---
 
@@ -1122,59 +731,19 @@ The framework enforces rate limits automatically before calling the handler.
 
 | Endpoint | Description |
 |----------|-------------|
-| `GET /health` | Health check — returns `{ status: 'ok', timestamp }` |
-| `POST /auth/verify` | Exchange OAuth code for a session cookie |
-| `POST /auth/logout` | Clear the auth cookie |
-| `GET /auth/token` | Refresh and return the current token |
-| `GET /auth/url` | Get the OAuth popup URL |
-| `POST /api/:name` | RPC endpoint — dispatches any registered request handler |
-| `POST /ai/request` | AI proxy — forwards to ugly.bot (requires auth) |
-| `POST /api/client-error` | Client-side error capture |
-| `GET /my_feedback` | User feedback history (markdown, requires auth) |
-
----
-
-## Migrations
-
-Never change a collection field type without writing a migration:
-
-```typescript
-// server/migrations/001-add-bio.ts
-export const name = '001-add-bio';
-export async function up(db: Db) {
-  await db.collection('user').updateMany({}, { $set: { bio: '' } });
-}
-```
-
-Run with `npm run db:migrate`. Use `npm run db:migrate -- --status` to preview pending migrations.
-
----
-
-## CLI reference
-
-| Command | Description |
-|---------|-------------|
-| `ugly-app init <name>` | Scaffold a new project |
-| `ugly-app upgrade` | Upgrade framework config files to the latest version |
-| `ugly-app configure` | Generate `.uglyapp` config |
-| `ugly-app dev` | Start all dev services (Docker, server, Vite, tsc, eslint) |
-| `ugly-app build` | Production build |
-| `ugly-app login` | Login to ugly.bot |
-| `ugly-app db:migrate` | Run pending migrations (`--status` to preview) |
-| `ugly-app deploy:single` | Deploy to a single server |
-| `ugly-app deploy:multi` | Deploy to multiple servers |
-| `ugly-app publish:assets` | Push static assets to CDN (`--dry-run` to preview) |
-| `ugly-app purge:assets` | Clean old builds (`--keep <n>`, `--dry-run`) |
-| `ugly-app test:e2e` | Run Playwright end-to-end tests (`--headed` for browser) |
-| `ugly-app logs:local` | Query local dev logs |
-| `ugly-app logs:server` | Query server logs from MongoDB |
-| `ugly-app error:dev` / `error:prod` | Query error logs (dev tunnel / production) |
-| `ugly-app perf:dev` / `perf:prod` | Query performance metrics (dev tunnel / production) |
-| `ugly-app feedback:dev` / `feedback:prod` | Query user feedback (dev tunnel / production) |
-| `ugly-app auth:create-account` | Create an account in the database |
-| `ugly-app auth:create-token` | Generate a JWT for a userId |
-| `ugly-app textGen [prompt]` | Generate text via AI (`--model`, `--system-prompt`, `--max-tokens`, `--json`) |
-| `ugly-app imageGen [prompt]` | Generate an image via AI (`--model`, `--output <path>`) |
+| `GET /health` | Health check — returns `{ status, timestamp, lastRequestAt }`. |
+| `POST /api/:name` | Dispatch any registered request handler over HTTP. |
+| `POST /auth/verify` | Exchange OAuth code for session cookie. |
+| `POST /auth/logout` | Clear the auth cookie. |
+| `GET /auth/token` | Refresh and return the current token. |
+| `GET /auth/url` | Get the OAuth popup URL. |
+| `GET /_workers/manifest` | Worker definitions (used by ugly-studio). |
+| `POST /_workers/run` | Synchronously invoke a worker handler. |
+| `GET /_workers/runs` | Recent in-memory worker runs (last 200). |
+| `GET /_cron/manifest` | Cron tasks for the deploy orchestrator. |
+| `POST /api/_cron/:taskName` | Trigger a cron task (auth via `CRON_SECRET`). |
+| `POST /internal/email-callback` | Inbound email gateway (auth via `INTERNAL_EMAIL_SECRET`). |
+| `PUT /_s3/*` | Dev-only S3 upload proxy (avoids CORS with MinIO). |
 
 ---
 
@@ -1182,11 +751,17 @@ Run with `npm run db:migrate`. Use `npm run db:migrate -- --status` to preview p
 
 | Import path | Description |
 |-------------|-------------|
-| `ugly-app` | Server APIs (createApp, DB, auth, AI, email, storage, billing, worker queues, etc.) |
-| `ugly-app/shared` | Shared types and utilities (defineRequests, defineCollections, definePage, experiments, Zod, etc.) |
-| `ugly-app/client` | Client APIs (createSocket, createRouter, AppProvider, components, animations, audio, etc.) |
-| `ugly-app/playwright` | Playwright test utilities |
-| `ugly-app/webrtc` | WebRTC utilities |
+| `ugly-app` | Server: `createApp`, `TypedDB`, auth, AI clients, NATS, storage, email, push, workers. |
+| `ugly-app/shared` | Cross-tier: `defineRequests`, `defineCollections`, `definePage`, `defineWorkers`, Zod, experiments, time constants. |
+| `ugly-app/client` | React: `bootstrapApp`, `createRouter`, `lazyPage`, `AppProvider`, components, animations, audio, AI helpers. |
+| `ugly-app/conversation/{shared,server,client}` | AI chat sessions with persisted history. |
+| `ugly-app/collab/{server,client}` | Yjs-based collaborative editing. |
+| `ugly-app/markdown/{shared,client}` | Markdown rendering + editor. |
+| `ugly-app/webrtc`, `ugly-app/webrtc/server` | WebRTC video rooms. |
+| `ugly-app/three/{server,client}` | Three.js scene helpers. |
+| `ugly-app/worker` | Worker queue runtime. |
+| `ugly-app/playwright` | Test utilities. |
+| `ugly-app/vite`, `ugly-app/eslint` | Build-tool plugins. |
 
 ---
 
@@ -1194,75 +769,67 @@ Run with `npm run db:migrate`. Use `npm run db:migrate -- --status` to preview p
 
 | Variable | Description |
 |----------|-------------|
-| `JWT_SECRET` | **Required** — signs auth tokens |
-| `JWT_EXPIRY_SECONDS` | Token lifetime (optional, default: 2592000 = 30 days) |
-| `MONGODB_URI` | MongoDB connection string |
-| `PORT` | Server port (default: 3000) |
-| `NODE_ENV` | `development` or `production` |
-| `UGLY_BOT_TOKEN` | App token for AI proxy (`/ai/request`) |
-| `REDIS_URL` | Redis (optional, in-memory fallback for dev) |
-| `NATS_URL` | NATS server URL |
-| `CLOCK_ENABLED` | Set to `true` to enable `setOnMinuteTick`/`setOnHourlyTick` handlers |
-| `IS_CLOCK_SERVER` | Set to `true` on the instance that should process delayed worker queue jobs |
-| `STORAGE_ACCOUNT_ID` | Cloudflare R2 account ID |
-| `STORAGE_ACCESS_KEY_ID` | R2 access key |
-| `STORAGE_SECRET_ACCESS_KEY` | R2 secret key |
-| `STORAGE_PUBLIC_BUCKET` | R2 public bucket name |
-| `STORAGE_TEMP_BUCKET` | R2 temp bucket name |
-| `STORAGE_PUBLIC_URL` | Base URL for public assets |
-| `TOGETHER_API_KEY` | Together AI key |
-| `ANTHROPIC_API_KEY` | Anthropic Claude key |
-| `OPENAI_API_KEY` | OpenAI key |
-| `GOOGLE_API_KEY` | Google Gemini key |
-| `GROQ_API_KEY` | Groq key |
-| `KIE_API_KEY` | Kie.ai key |
-| `KIE_BASE_URL` | Kie.ai base URL override (optional) |
-| `DEEPGRAM_API_KEY` | Deepgram STT key |
-| `AZURE_TTS_KEY` | Azure TTS key |
-| `AZURE_TTS_REGION` | Azure TTS region |
-| `KAGI_API_KEY` | Kagi web search key |
-| `MAILGUN_API_KEY` | Mailgun key |
-| `MAILGUN_DOMAIN` | Mailgun sending domain |
-| `MAILGUN_FROM` | Default from address |
-
-Client-side variables must be prefixed with `VITE_`.
+| `PORT` | Server port (templates default to 4321). |
+| `NODE_ENV` | `development` or `production`. |
+| `UGLY_BOT_TOKEN` | App token for the ugly.bot platform — required for AI, logs, billing. |
+| `UGLY_BOT_URL` | Override the platform base URL (default `https://ugly.bot`). |
+| `DATA_PROXY_URL` | WebSocket URL for the data proxy (default `ws://localhost:4200`). |
+| `DATA_PROXY_TOKEN` | Auth token for the data proxy. |
+| `STORAGE_KEY_PREFIX` | Prefix all storage keys (per-env isolation). |
+| `MINIO_ENDPOINT` | Dev-only S3 endpoint for the upload proxy. |
+| `NATS_PREFIX` / `COMPOSE_PROJECT_NAME` | NATS subject prefix for per-env isolation. |
+| `CLOCK_ENABLED` | `true` to enable `setOnMinuteTick` / `setOnHourlyTick`. |
+| `CRON_SECRET` | Bearer secret for `POST /api/_cron/:taskName` and prod `POST /_workers/run`. |
+| `MAINTAIN_BOT_USER_ID` | User id allowed to access admin-only handlers. |
+| `INTERNAL_EMAIL_SECRET` | Shared secret for `/internal/email-callback`. |
+| `JWT_SECRET` | Required when using `getRequestUser()` for the per-project session cookie. |
+| `APP_DOMAIN` | App domain; combined with `NATS_PREFIX` for `getRequestUser()` validation. |
+| `LOG_CAPTURE_URL` | Studio override for client log capture (empty → ugly.bot default). |
+| `UGLY_APP_HMR` | Set to `false` to disable Vite HMR in dev. |
+| `SCHEMA_CHECK_SKIP` | `true` to start despite schema drift (unsafe). |
+
+Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta.env.VITE_*`.
 
 ---
 
-## Shared utilities
+## CLI
 
-`ugly-app/shared` exports common helpers used by both server and client:
+| Command | Description |
+|---------|-------------|
+| `ugly-app init <name>` | Scaffold a new project. |
+| `ugly-app upgrade` | Upgrade framework config files to the latest version. |
+| `ugly-app configure` | Generate/update `.uglyapp` config. |
+| `ugly-app login` | Authenticate with ugly.bot. |
+| `ugly-app url` | Print the local dev server URL. |
+| `ugly-app deploy` | Build + push to production infrastructure. |
+| `ugly-app prod --buildId <id>` | Promote a build to prod. |
+| `ugly-app versions` | List deployed versions. |
+| `ugly-app versions:prune` | Clean up non-prod versions. |
+| `ugly-app infra:destroy` | Tear down all project infra. |
+| `ugly-app textGen [prompt]` | Generate text via AI (`--model`, `--system-prompt`, `--max-tokens`, `--json`). |
+| `ugly-app imageGen [prompt]` | Generate an image (`--model`, `--output <path>`). |
+| `ugly-app error:dev` / `error:prod` | Query error logs (your tunnel / production). |
+| `ugly-app perf:dev` / `perf:prod` | Query performance metrics. |
+| `ugly-app feedback:dev` / `feedback:prod` | Query user feedback. |
+| `ugly-app feedback:submit` / `feedback:resolve` | Manage feedback (run with `--help` for flags). |
+
+Inside a scaffolded project, the same commands are available via `npm run …` scripts — see `templates/CLAUDE.md` for the full list.
 
-```typescript
-import {
-  isDefined,
-  compact,
-  debounce,
-  formatDate,
-  formatRelativeTime,
-  oneSecond,
-  oneMinute,
-  oneHour,
-  oneDay,
-  oneWeek,
-} from 'ugly-app/shared';
-
-isDefined(value);                  // type guard — true if not null/undefined
-compact([1, null, 2, undefined]);  // [1, 2] — filters out null/undefined
-const debouncedFn = debounce(fn, 300);
-formatDate(new Date());            // locale-formatted date string
-formatRelativeTime(new Date());    // "2 hours ago", "just now", etc.
-
-// Time constants (milliseconds)
-oneSecond; // 1000
-oneMinute; // 60_000
-oneHour;   // 3_600_000
-oneDay;    // 86_400_000
-oneWeek;   // 604_800_000
-```
+---
+
+## Migrations
+
+Schema changes must be deliberate:
+
+1. Update the Zod schema in `shared/collections.ts`.
+2. Run `npm run db:schema-gen` — produces a migration file with compile-blocking `REPLACE_ME` placeholders for any non-trivial change.
+3. Replace every `REPLACE_ME` with the correct migration logic.
+4. Run `npm run db:migrate`.
+
+The framework refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true` only as a temporary escape hatch).
 
 ---
 
 ## Tech stack
 
-Node.js · TypeScript · Express · React 19 · Vite · Tailwind CSS · MongoDB · NATS · Redis · Cloudflare R2 · Zod · JWT (jose) · ugly.bot OAuth
+Node.js · TypeScript · Express · React 19 · Vite · PostgreSQL (JSONB) · Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · ugly.bot platform