ugly-app 0.1.39 → 0.1.40

package/README.md

@@ -1,709 +1,720 @@
-# website-core
-
-A full-stack TypeScript framework for building production-ready web applications. Provides an opinionated architecture combining an Express backend, React frontend, and MongoDB database with built-in authentication, real-time communication, storage, AI integration, and audio streaming.
-
-## What's Included
-
-- **Server**: Express with type-safe RPC routing and Zod schema validation
-- **WebSockets**: Bidirectional socket server/client with RPC calls, document tracking, and file uploads
-- **Database**: MongoDB with typed collections, cascade delete, indexes, migrations, and NATS-based real-time document tracking
-- **Auth**: JWT + HttpOnly cookie sessions, OAuth (ugly.bot by default, extensible via `AuthProvider` interface)
-- **Storage**: AWS S3 / Cloudflare R2 with presigned URLs and file promotion
-- **AI**: 7 text generation providers (Together, Claude, OpenAI, Google, Groq, Fireworks, Kie) + 5 image providers (Together, FAL, Google, Kie, Wavespeed)
-- **Audio**: Text-to-speech and speech-to-text streaming with React hooks (`useTTS`, `useSTT`), optional viseme data for lip sync, and word-level timestamps
-- **Logging**: Multi-channel logging to MongoDB (error, console, perf, feedback) with server error capture, deduplication, and classification
-- **Queues**: NATS JetStream worker queues, Redis pub/sub with in-memory fallback
-- **Billing**: AI spend tracking with global/provider/per-user rolling limits (hourly/daily/weekly), threshold callbacks, profit margin markup, pre-paid user credits, full audit history, and 5-minute DB reconciliation
-- **Email**: Transactional email via Mailgun with Handlebars template support
-- **Rate Limiting**: Per-user/per-operation token-bucket limiting with queue management
-- **Push Notifications**: Real-time delivery via WebSocket + Redis, with FCM support
-- **Feedback**: Built-in user feedback collection with screenshot capture
-- **CLI**: `web` command for dev, build, deploy, migrations, log queries, and auth utilities
-
-## Installation
+# ugly-app
 
-```bash
-npm install website-core
-```
-
-Peer dependencies:
+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.
 
-```bash
-npm install react react-dom html2canvas
-```
+## What's included
 
-## Quick Start
+- **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, 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) + image generation (Together, FAL, Google, Wavespeed)
+- **Storage**: Cloudflare R2 / AWS S3 with presigned uploads
+- **CLI**: `ugly-app` commands for dev, build, deploy, migrations, logs, and auth utilities
 
-### Scaffold a new project
+## Quick start
 
 ```bash
-npx web init my-app
+npx ugly-app init my-app
+cd my-app
+npm run dev
 ```
 
-### Start development
+---
 
-```bash
-yarn dev
-# Starts Docker services, Express server, Vite, TypeScript watcher, and ESLint concurrently
-```
+## Server
 
-## Usage
+### `createApp()`
 
-### Server
+Entry point for the server. Creates an Express + WebSocket server with typed RPC, auth, and all framework services.
 
 ```typescript
-import { createApp, createUserHelper, registerFeedbackHandlers } from 'website-core';
-import { dbDefaults } from 'website-core/shared';
-import { functions, requests } from '../shared/api.js';
-import { collections } from '../shared/collections.js';
-import { pages } from '../shared/pages.js';
-import type { User } from '../shared/types.js';
+import { createApp, createUserHelper, type CallHandlers, type RequestHandlers, type HandlerContext } from 'ugly-app';
+import { dbDefaults } from 'ugly-app/shared';
+import { functions, requests } from '../shared/api';
+import { collections } from '../shared/collections';
+import { pages } from '../shared/pages';
+import type { User } from '../shared/types';
 
-export const userHelper = createUserHelper(collections.user);
+const userHelper = createUserHelper<User>(collections.user);
 
-const app = createApp({ functions, requests }, collections, (config) => {
-  config.setPages({ pages });
+const calls = {
+  myFunction: async (ctx: HandlerContext, input) => {
+    return { greeting: `Hello, ${input.name}` };
+  },
+} satisfies CallHandlers<typeof functions>;
 
-  config.setUserHelper(userHelper);           // required
+const reqs = {
+  getMe: async (ctx: HandlerContext) => {
+    const user = await userHelper.get(ctx.db, ctx.userId);
+    return { userId: ctx.userId, email: user?.email };
+  },
+} satisfies RequestHandlers<typeof requests>;
 
-  config.setOnUserCreate(async (userId, info, db) => {   // required
-    await userHelper.set(db, {
-      ...dbDefaults(),
-      id: userId,
-      email: info.email,
-      phone: info.phone,
-    });
+const app = createApp({ functions, requests }, calls, reqs, collections, (configurator) => {
+  configurator.setPages({ pages });
+  configurator.setUserHelper(userHelper);
+  configurator.setOnUserCreate(async (userId, info, db) => {
+    await userHelper.set(db, { id: userId, ...dbDefaults(), ...info });
   });
-
-  // Optional
-  // config.setAuth(myAuthProvider);
-  // config.setContextExtensions(async (base) => ({ nats: await connectNats() }));
 });
 
-app.registerRequest('getMe', async (ctx) => {
-  const user = await userHelper.get(ctx.db, ctx.userId);
-  return { userId: ctx.userId, email: user?.email };
-});
+await app.start(3000);
+```
 
-registerFeedbackHandlers(app, process.env.MAINTAIN_BOT_USER_ID ?? '');
+**Signature:**
 
-const port = parseInt(process.env['PORT'] ?? '3000');
-await app.start(port);
+```typescript
+function createApp<R extends AppRegistryBase, Defs extends CollectionDefRegistry>(
+  registry: R,
+  calls: Partial<CallHandlers<R['functions']>>,
+  requests: Partial<RequestHandlers<R['requests']>>,
+  appDefs: Defs,
+  configure?: (configurator: AppConfigurator) => void,
+): App;
 ```
 
-> Both `setUserHelper` and `setOnUserCreate` are **required** — `createApp` throws at startup if either is missing.
+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
+- `dispatch(type, name, input, userId)` — invoke an RPC handler programmatically
 
-### Shared types and API definitions
+### `AppConfigurator`
 
-```typescript
-import { fn, req, defineFunctions, defineRequests } from 'website-core/shared';
-import { z } from 'website-core/shared';
+| 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)` |
+| `setContextExtensions(fn)` | Add fields to `HandlerContext` — `(base: HandlerContext) => Promise<E>` |
+| `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()` |
 
-export const functions = defineFunctions({
-  greet: fn(
-    z.object({ name: z.string() }),
-    z.object({ message: z.string() })
-  ),
-});
-```
+### Handler context (`ctx`)
 
-### React client
+Every RPC handler receives a `HandlerContext`:
 
-```typescript
-import { AppProvider, useApp, createRouter, createSocket } from 'website-core/client';
-```
+| Field | Type | Description |
+|-------|------|-------------|
+| `ctx.userId` | `string` | Authenticated user ID (always set) |
+| `ctx.db` | `TypedDB` | MongoDB client with typed collection methods |
+| `ctx.storage` | `StorageClient` | R2/S3 presigned uploads and public URLs |
+| `ctx.textGen` | `TextGenClient` | Text generation (see AI section) |
+| `ctx.imageGen` | `ImageGenClient` | Image generation |
+| `ctx.log` | `Logger` | Structured logging to MongoDB |
+| `ctx.rateLimit` | `RateLimiter` | Token-bucket rate limiting |
 
-## Key APIs
+---
 
-### Server — `createApp()`
+## Shared API definitions
 
-```typescript
-createApp(registry, appDefs, configure?)
-```
+All type definitions live in `shared/` and are used by both server and client.
 
-- `registry` — `{ functions, requests }` from your shared API definitions
-- `appDefs` — collection defs from `defineCollections()`
-- `configure` — optional callback receiving an `AppConfigurator`:
+### Functions and requests (`shared/api.ts`)
 
 ```typescript
-interface AppConfigurator {
-  setUserHelper(helper: UserHelper<any>): void;       // required
-  setOnUserCreate(handler: OnUserCreate): void;        // required
-  setAuth(provider: AuthProvider): void;
-  setPages(options: PageServerOptions): void;
-  setOnSocketMessage(handler: (ws, userId, msg) => boolean): void;
-  setContextExtensions<E>(fn: (base: HandlerContext) => Promise<E>): void;
-  setWorkerQueue(queue: WorkerQueue): void;
-  registerRoutes(fn: (router: express.Router) => void): void;
-}
-```
-
-Registers handlers with full context (`userId`, `db`, `storage`, `textGen`, `imageGen`, `log`, `rateLimit`):
+import { defineFunctions, defineRequests, fn, req, z } from 'ugly-app/shared';
 
-```typescript
-app.registerFunction('greet', async (ctx, input) => {
-  ctx.log.info('Greeting user', { userId: ctx.userId });
-  return { message: `Hello, ${input.name}` };
+export const functions = defineFunctions({
+  createNote: fn({
+    input: z.object({ title: z.string(), body: z.string() }),
+    output: z.object({ id: z.string() }),
+  }),
 });
 
-app.registerRequest('stream', async (ctx, input) => {
-  // streaming HTTP handler — ctx.res available for request handlers
+export const requests = defineRequests({
+  getNotes: req({
+    input: z.object({}),
+    output: z.array(z.object({ id: z.string(), title: z.string() })),
+  }),
 });
 ```
 
-Built-in routes: `GET /health`, `POST /auth/verify`, `GET /auth/token`, `POST /auth/logout`, `GET /auth/url`, `POST /logs/client`, `GET /my_feedback`
-
-### Auth — Cookie Sessions
+- `fn({ input, output })` — defines a mutation (write operation). `input` and `output` are Zod schemas.
+- `req({ input, output })` — defines a query (read operation).
+- `defineFunctions()` / `defineRequests()` — identity wrappers that preserve types.
+- `z` is re-exported from Zod for convenience.
 
-After login, the server sets an `auth_token` HttpOnly cookie. On every page load the server refreshes it and injects the token into the HTML:
-
-```html
-<script>window.__AUTH_TOKEN__ = "eyJ..."</script>
-```
-
-The client reads `window.__AUTH_TOKEN__` synchronously — no localStorage, no extra HTTP round-trip. To log out:
+### Collections (`shared/collections.ts`)
 
 ```typescript
-await fetch('/auth/logout', { method: 'POST' });
-window.location.reload();
-```
-
-### Database — `TypedDB`
-
-Define collections in `shared/collections.ts`. The `defineCollections` call injects the collection name into each def, making the def itself the collection reference:
-
-```typescript
-import { defineCollections } from 'website-core/shared';
+import { defineCollections } from 'ugly-app/shared';
+import type { Note } from './types';
 
 export const collections = defineCollections({
-  notes: {
+  note: {
     type: {} as Note,
     meta: { cache: true, trackable: true, public: false, parent: null },
-    onDelete: async (doc, db) => { /* cleanup child docs */ },
   },
-  comments: {
-    type: {} as Comment,
-    meta: { cache: false, trackable: true, public: false, parent: 'notes' },
+  user: {
+    type: {} as User,
+    meta: { cache: true, trackable: false, public: false, parent: null },
   },
 });
 ```
 
-Inside handlers, use `ctx.db` — a `TypedDB` instance pre-created by `createApp`. All methods take the collection def as the first argument (not a string name):
+Collection meta fields:
+- `cache` — enable in-memory caching
+- `trackable` — allow real-time `trackDoc`/`trackDocs` subscriptions
+- `public` — accessible without auth
+- `parent` — parent collection name for cascade deletes (or `null`)
+
+All documents extend `DBObject`: `{ id: string, version: number, created: Date, updated: Date }`.
+
+### Pages (`shared/pages.ts`)
 
 ```typescript
-// Insert / replace
-await ctx.db.setDoc(collections.notes, doc);
-await ctx.db.setDoc(collections.notes, doc, { skipIfExists: true }); // INSERT only
+import { definePage, definePages } from 'ugly-app/shared';
 
-// Partial updates (dot-notation, sets `updated` automatically)
-await ctx.db.setDocFields(collections.notes, id, { title: 'New title' });
-const doc = await ctx.db.setDocFieldsOrIgnore(collections.notes, id, { title });  // null if missing
-const doc = await ctx.db.setDocFieldsOrCreate(collections.notes, id, fields, fullObj);
+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
+});
+export type AppPages = typeof pages;
+```
 
-// MongoDB update operators ($inc, $addToSet, $pull, $unset, $set)
-await ctx.db.setDocOp(collections.notes, id, { $inc: { viewCount: 1 } });
-const doc = await ctx.db.setDocOpOrIgnore(collections.notes, id, { $addToSet: { tags: 'foo' } });
+- `: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)
+
+---
 
-// Reads
-const note = await ctx.db.getDoc(collections.notes, id);
-const notes = await ctx.db.getDocs(collections.notes, { userId }, { sort: { created: -1 }, limit: 20, skip: 0 });
+## Client
 
-// Aggregate pipeline queries
-const results = await ctx.db.getQuery<MyResult>('notes', pipeline, { skip, limit });
-const count   = await ctx.db.getQueryCount('notes', pipeline);
-const raw     = await ctx.db.getQueryRaw<RawDoc>('notes', pipeline);  // no id remapping
+### Entry point (`client/main.tsx`)
 
-// Delete with cascade
-await ctx.db.deleteDoc(collections.notes, id);
-await ctx.db.deleteQuery(collections.notes, { userId });
+```tsx
+import { createRoot } from 'react-dom/client';
+import { AppProvider, createSocket, LoginPopup } from 'ugly-app/client';
+import { functions, requests } from '../shared/api';
+import { RouterProvider } from './router';
+import App from './App';
 
-// Nested / child collections (parentId compound _id: "parentId:leafId")
-await ctx.db.setDoc(collections.comments, comment, { parentId: noteId });
-await ctx.db.getDocs(collections.comments, {}, { parentId: noteId });
-await ctx.db.deleteDoc(collections.comments, commentId, { parentId: noteId });
+const token = (window as any).__AUTH_TOKEN__;
+const root = createRoot(document.getElementById('root')!);
+const loginPopup = <LoginPopup onSuccess={() => window.location.reload()} />;
 
-// Direct cache access
-const key = ctx.db.cacheKey('notes', id);
-ctx.db.cacheSet(key, value, 60_000);
-const cached = ctx.db.cacheGet<Note>(key);
-ctx.db.cacheDelete(key);
+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({ functions, 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>,
+    );
+  });
+}
 ```
 
-Per-collection `cache: true` enables automatic LRU caching on `getDoc` / `setDoc` / `deleteDoc`. Use `parent: 'collectionName'` to define parent–child relationships for compound `_id`s and cascade deletes.
+### `createSocket()`
 
-### WebSocket Client
+Creates a typed WebSocket client for RPC communication.
 
 ```typescript
-const socket = createSocket({ functions, requests });
-
-await socket.connect(token);                                  // must call first
-await socket.call('greet', { name: 'world' });               // function RPC
-await socket.request('getMe', {});                            // request RPC
-const doc = await socket.getDoc('notes', id);                 // fetch document
-socket.trackDoc('notes', id, (doc) => { /* live */ });        // live updates
-await socket.uploadFile(file, key);                           // file upload (key is a string)
+const socket = createSocket({ functions, requests, url: '/rpc' });
+await socket.connect(token); // returns UserBase
 ```
 
-`trackDocs` accepts optional `sort`, `limit`, and `skip` parameters for server-side ordering and pagination:
+**`AppSocket` methods:**
 
-```typescript
-// Live-updating query: most recent 20 notes, newest first
-socket.trackDocs('notes', { userId }, (docs) => { /* live */ }, {
-  sort: { created: -1 },
-  limit: 20,
-  skip: 0,
-});
+| Method | Description |
+|--------|-------------|
+| `connect(token)` | Authenticate and connect. Returns the user object |
+| `call(name, input)` | Invoke a function (mutation) |
+| `request(name, input)` | Invoke a request (query) |
+| `getDoc(collection, id)` | Fetch a single document |
+| `trackDoc(collection, id, cb)` | Subscribe to real-time doc changes. Returns unsubscribe fn |
+| `trackDocs(collection, filter, cb, opts?)` | Subscribe to query results. Returns unsubscribe fn |
+| `uploadFile(file, key)` | Upload a file via presigned URL |
+| `disconnect()` | Close the connection |
+
+### `AppProvider`
+
+Wraps your app with context for `useApp()`. Provides user info, socket access, popup management, async loading overlay, splash screen, and localization.
+
+```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>
 ```
 
-`getDocs` on the server also accepts the same options:
+**`useApp()` returns:**
+
+| 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 |
+
+### Router
+
+#### Setup (`client/router.ts`)
 
 ```typescript
-const docs = await ctx.db.getDocs(collections.notes, { userId }, {
-  sort: { created: -1 },
-  limit: 20,
-  skip: 0,
-});
+import { createRouter } from 'ugly-app/client';
+import { pages } from '../shared/pages';
+import { allPages } from './allPages';
+
+export const { RouterProvider, RouterView, useRouter } = createRouter({ pages, allPages });
 ```
 
-### AI — Text Generation
+`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?`
+- **`useRouter()`** — hook returning the router context
+
+#### Page map (`client/allPages.ts`)
 
 ```typescript
-const text = await ctx.textGen.generate(messages, { model });
-const json = await ctx.textGen.generateJson(schema, messages, { model });
-const result = await ctx.textGen.generateWithTools(messages, tools, { model });
+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')),
+} satisfies PageMap<AppPages>;
 ```
 
-Supported providers: `together`, `claude`, `openai`, `google`, `groq`, `fireworks`, `kie`
+- **`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.
 
-### AI — Image Generation
+#### Navigation with `useRouter()`
 
 ```typescript
-const url = await ctx.imageGen.generate(prompt, { width: 1024, height: 1024 });
+const { push, replace, back, current, openPopup, closePopup, closeAllPopups } = useRouter();
+
+push('note/:noteId', { noteId: '123' });   // pushes /note/123
+replace('search', { q: 'hello' });          // replaces with /search?q=hello
+back();                                      // browser back
+
+// current route state
+current.routeName; // e.g. 'note/:noteId'
+current.params;    // e.g. { noteId: '123' }
 ```
 
-Supported providers: `together`, `fal`, `google`, `kie`, `wavespeed`
+All route names and params are fully typed based on your `pages` definition.
 
-### Audio — TTS/STT React Hooks
+#### Popups
 
-```typescript
-// Text-to-speech
-const { playing, currentWord, play, stop } = useTTS(socket);
-await play('Hello world');
+Always use `useRouter().openPopup()` — never build custom fixed overlays.
 
-// With viseme data for lip sync (opt-in — adds latency)
-await play('Hello world', { requestVisemes: true });
-// viseme events arrive via onViseme callback in useTTS options
+```tsx
+const { openPopup } = useRouter();
 
-// Speech-to-text
-const { transcript, isFinal, listening, start, stop } = useSTT(socket, {
-  mode: 'realtime', // 'realtime' | 'batch' | 'auto'
+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
+  animConfig: { duration: 300, easing: myEasingFn },
+  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the popup renderer
 });
 
-// With word-level timestamps (opt-in — uses Groq verbose_json, slower)
-const { transcript, words } = useSTT(socket, {
-  mode: 'batch',
-  requestWords: true,
-});
-// words: STTWord[] — each has { word, startMs, durationMs }
+handle.hide(); // dismiss programmatically
 ```
 
-Viseme and word types are exported from `website-core/shared`:
+Popup modes:
+- **`block`** — 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
 
-```typescript
-import type { TTSViseme, TTSVisemeName, STTWord } from 'website-core/shared';
+#### `Link` component
+
+```tsx
+import { Link } from 'ugly-app/client';
+
+<Link router={router} to="note/:noteId" params={{ noteId: '123' }}>
+  View Note
+</Link>
 ```
 
-### Email
+Renders an `<a>` tag with the correct `href`. Intercepts clicks for client-side navigation (ctrl/cmd+click opens in new tab).
+
+---
+
+## Auth
+
+Auth uses HttpOnly cookies with server-side JWT injection. No localStorage needed.
+
+**Flow:**
 
-Send transactional email via Mailgun:
+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:**
 
 ```typescript
-import { sendEmail, loadEmailTemplate, sendTemplateEmail } from 'website-core';
+await fetch('/auth/logout', { method: 'POST' });
+window.location.reload();
+```
 
-// One-off HTML email
-await sendEmail({
-  to: 'user@example.com',
-  subject: 'Welcome!',
-  html: '<p>Thanks for signing up.</p>',
-  from: 'noreply@my-app.com',  // optional — defaults to MAILGUN_FROM env var
-  replyTo: 'support@my-app.com',
-  headers: { 'X-Campaign-Id': 'welcome' },
-});
+**Built-in auth endpoints:**
+
+| 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 |
 
-// Handlebars template email
-interface WelcomeData { name: string; confirmUrl: string }
-const welcomeTemplate = loadEmailTemplate<WelcomeData>('/path/to/welcome.hbs');
+**Custom auth provider:**
 
-await sendTemplateEmail('user@example.com', 'Confirm your email', welcomeTemplate, {
-  name: 'Alice',
-  confirmUrl: 'https://my-app.com/confirm?token=abc',
+```typescript
+configurator.setAuth({
+  verify: async (code: string) => ({ userId: '...', email: '...' }),
+  authUrl: (origin: string) => 'https://my-oauth.com/authorize?...',
+  registerRoutes: (router) => { /* optional extra routes */ },
 });
 ```
 
-Required environment variables: `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_FROM`. If `MAILGUN_API_KEY` is not set, sending is silently skipped (dev-friendly).
+---
 
-### Billing
+## Database (`TypedDB`)
 
-Track AI spend and enforce rate limits across all cost types (`textGen`, `imageGen`, `stt`, `tts`, `embedding`, `service`):
+### Writing
 
 ```typescript
-import {
-  initBillingGateway,
-  getBillingGateway,
-  BillingLimitError,
-  BillingValidationError,
-} from 'website-core';
+// Insert or replace a document
+await ctx.db.setDoc(collections.note, doc);
+await ctx.db.setDoc(collections.note, doc, { skipIfExists: true });
 
-// Initialize once at startup (before serving traffic)
-const billing = initBillingGateway(db, {
-  global: {
-    hourlyUsd: 50,           // hard cap across all providers/users
-    thresholdPct: 0.8,       // fire callback at 80%
-  },
-  providers: {
-    openai: { hourlyUsd: 20, thresholdPct: 0.9 },
-    anthropic: { hourlyUsd: 30 },
-  },
-  profitMarginPct: 0.5,           // optional: 50% markup applied before limit checks
-  reconcileIntervalMs: 300_000,   // flush to DB every 5 min (default)
-  userLimitCacheSize: 10_000,     // LRU entries (default)
-}, creditDb); // optional CreditDB for pre-paid credits
-
-// Supply per-user limits from your database
-billing.setUserLimitHook(async (userId) => {
-  const plan = await db.getDoc(collections.plans, userId);
-  return plan
-    ? { hourlyUsd: plan.hourlyUsd, dailyUsd: plan.dailyUsd, weeklyUsd: plan.weeklyUsd,
-        thresholds: { daily: 0.9 } }
-    : null; // null = no limits
-});
+// Partial update — only specified fields
+await ctx.db.setDocFields(collections.note, id, { title: 'New title' });
 
-// Alert callbacks (errors swallowed — never block a charge)
-billing.setGlobalThresholdCallback(({ limitType, spent, limit, thresholdPct, provider }) => {
-  console.warn(`[Billing] ${limitType} at ${Math.round(thresholdPct * 100)}%: $${spent}/$${limit}`);
-});
-billing.setUserThresholdCallback(({ userId, limitType, spent, limit }) => {
-  void notifyUser(userId, `You've used ${Math.round(spent / limit * 100)}% of your ${limitType} budget`);
-});
+// Partial update — returns null if document doesn't exist (no error)
+const doc = await ctx.db.setDocFieldsOrIgnore(collections.note, id, { title });
+
+// Partial update — creates the document if it doesn't exist
+await ctx.db.setDocFieldsOrCreate(collections.note, id, { title });
+
+// MongoDB update operators ($inc, $addToSet, $pull, $unset, $set)
+await ctx.db.setDocOp(collections.note, id, { $inc: { views: 1 } });
+await ctx.db.setDocOpOrIgnore(collections.note, id, { $inc: { views: 1 } }); // no error if missing
 ```
 
-**Recording a charge:**
+### Reading
 
 ```typescript
-// Returns BillingRecord on success; throws on limit violation
-try {
-  const record = await getBillingGateway().charge({
-    userId,               // optional — omit for anonymous charges
-    provider: 'openai',
-    model: 'gpt-4o',
-    type: 'textGen',      // 'textGen' | 'imageGen' | 'stt' | 'tts' | 'embedding' | 'service'
-    costUsd: 0.012,
-    inputTokens: 800,
-    outputTokens: 400,
-  });
-} catch (err) {
-  if (err instanceof BillingLimitError) {
-    // err.limitType: 'global-hourly' | 'provider-hourly' | 'user-hourly' | 'user-daily' | 'user-weekly'
-    // err.spent, err.limit
-  }
-}
+const note  = await ctx.db.getDoc(collections.note, id);
+const notes = await ctx.db.getDocs(collections.note, { userId }, { sort: { created: -1 }, limit: 20 });
+
+// Aggregation pipeline
+const results = await ctx.db.getQuery<MyResult>('note', pipeline, { skip, limit });
+const count   = await ctx.db.getQueryCount('note', pipeline);
+const raw     = await ctx.db.getQueryRaw<T>('note', pipeline);
 ```
 
-**Querying spend and history:**
+### Deleting
 
 ```typescript
-const billing = getBillingGateway();
+await ctx.db.deleteDoc(collections.note, id);        // single doc (cascades via parent)
+await ctx.db.deleteQuery(collections.note, { userId }); // bulk delete by filter
+```
 
-// Rolling window totals
-const globalHour = await billing.getWindowSpend(3_600_000);
-const userDay    = await billing.getWindowSpend(86_400_000, { userId });
-const openaiHour = await billing.getWindowSpend(3_600_000, { provider: 'openai' });
+### Caching
 
-// Audit history (default limit 100, max 1000)
-const records = await billing.getHistory({ userId, limit: 50, skip: 0 });
+```typescript
+const cached = await ctx.db.cacheGet<MyType>(key);
+await ctx.db.cacheSet(key, value, ttlMs);
+await ctx.db.cacheDelete(key);
+const key = ctx.db.cacheKey('prefix', id); // generate a cache key
 ```
 
-**Cache invalidation** (call after a user's plan changes):
+### Helpers
 
 ```typescript
-billing.invalidateUserLimit(userId);
-billing.invalidateAllUserLimits();
-```
+import { dbDefaults, createUserHelper } from 'ugly-app';
 
-**Pre-paid credits** (optional — requires `creditDb` passed to `initBillingGateway`):
+// dbDefaults() returns { version: 1, created: new Date(), updated: new Date() }
+const doc = { id: newId(), ...dbDefaults(), title: 'Hello' };
 
-When a user would otherwise be blocked by a rate limit, the gateway automatically deducts from their credit balance as a fallback. Global and provider limits are never bypassed.
+// createUserHelper — typed user CRUD
+const userHelper = createUserHelper<User>(collections.user);
+const user = await userHelper.get(db, userId);
+await userHelper.set(db, { id: userId, ...dbDefaults(), email });
+```
+
+### Indexes
 
 ```typescript
-import { CreditStore, MongoCreditDB } from 'website-core';
+// shared/dbIndexes.ts
+import { defineDbIndexes } from 'ugly-app/shared';
+
+export const dbIndexes = defineDbIndexes({
+  note: [
+    { key: { userId: 1, created: -1 } },
+    { key: { title: 'text' }, type: 'search' },
+  ],
+});
+```
 
-// Set up the credit DB (uses your TypedDB instance)
-const creditDb = new MongoCreditDB(db.userCredits);
-const billing = initBillingGateway(ledgerDb, config, creditDb);
+Run `npm run db:init` to create/update indexes.
 
-// Grant credits (e.g. after a purchase)
-await billing.grantCredit(userId, 5.00);  // $5.00
+---
 
-// Check balance
-const balance = await billing.getCreditBalance(userId);
+## AI
 
-// Invalidate cached balance (e.g. after external grant)
-billing.invalidateCreditCache(userId);
+### Text generation
+
+```typescript
+// In a handler via ctx.textGen:
+const text   = await ctx.textGen.generate(messages);
+const json   = await ctx.textGen.generateJson(schema, messages);   // Zod schema, retries on parse failure
+const result = await ctx.textGen.generateWithTools(messages, tools); // automatic tool-call loop
 ```
 
-Charges are recorded to an `aiSpend` MongoDB collection and reconciled in-memory every 5 minutes with a forced flush on `shutdown()`. Each text and image generation call from `createTextGen`/`createImageGen` is automatically charged through the gateway when initialized.
+| Provider | `provider` value | JSON | Tools | Vision |
+|----------|-----------------|------|-------|--------|
+| Together AI (Llama-4-Scout) | `'together'` | yes | yes | yes |
+| Anthropic (claude-sonnet-4-6) | `'claude'` | yes | yes | yes |
+| OpenAI (gpt-4o) | `'openai'` | yes | yes | yes |
+| Google (gemini-2.0-flash) | `'google'` | yes | yes | yes |
+| Groq (llama-3.3-70b) | `'groq'` | yes | yes | no |
+| Fireworks | `'fireworks'` | yes | yes | yes |
 
-### Rate Limiting
+Use `provider: 'auto'` (default) to let the system pick based on requirements.
 
-```typescript
-const rateLimit = createRateLimiter({
-  windowSeconds: 3600,  // 1 hour (default)
-  maxPerWindow: 1.0,    // max units per window (default)
-  maxQueueDepth: 100,   // max queued requests (default)
-  maxWaitMs: 300_000,   // max wait time in queue (default)
-});
+**Standalone client (outside handlers):**
 
-await rateLimit.check(userId, 'generate', 0.1);
-await rateLimit.charge(userId, 'generate', actualCost);
+```typescript
+import { createTextGenClient } from 'ugly-app';
+const textGen = createTextGenClient();
 ```
 
-### Worker Queues
+### Image generation
 
 ```typescript
-const queue = createWorkerQueue({
-  streamName: 'JOBS',     // NATS stream name (default: 'JOBS')
-  clockServerOnly: true,  // only process when IS_CLOCK_SERVER=true (default: true)
-  concurrency: 10,        // max concurrent jobs (default: 10)
-  maxRetries: 3,          // max retry attempts (default: 3)
-});
+const url = await ctx.imageGen.generate(prompt, { width: 1024, height: 1024 });
+```
+
+| Provider | `provider` value |
+|----------|-----------------|
+| Together AI (FLUX schnell) | `'together'` |
+| FAL (FLUX pro) | `'fal'` |
+| Google (Imagen 3) | `'google'` |
+| Wavespeed | `'wavespeed'` |
+
+**Standalone client:**
 
-await queue.enqueue('email', { to: 'user@example.com' });
-await queue.enqueue('email', payload, { delay: 5000 }); // delay in ms
-queue.registerHandler('email', async (job) => { /* job.payload, job.working() */ });
-await queue.start();
+```typescript
+import { createImageGenClient } from 'ugly-app';
+const imageGen = createImageGenClient();
 ```
 
-### Storage
+### Custom providers
 
 ```typescript
-const storage = createStorageClient();
+import { registerTextGenProvider, registerImageGenProvider } from 'ugly-app';
+
+registerTextGenProvider('myProvider', myTextGenImplementation);
+registerImageGenProvider('myProvider', myImageGenImplementation);
+```
+
+### AI proxy
 
-// Server-side upload
+The client accesses AI via `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
+
+```typescript
+// Server-side — put a file
 const url = await storage.put('temp', key, buffer, 'image/png');
+
+// Move from temp to public bucket
 const publicUrl = await storage.moveToPublic(tempKey, destKey);
+
+// Get a public URL
 const url = storage.url('public', destKey);
 
-// Presigned URL for browser direct upload
+// Browser direct upload via presigned URL
 const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);
 ```
 
-### Logging
+Buckets: `'public'` and `'temp'`.
 
-```typescript
-// In handlers, use ctx.log
-ctx.log.info('User signed in', { userId });
-ctx.log.warn('Unexpected state', { context });
-ctx.log.error('Something failed', { error: err.message });
+Static build-time assets go in `client/public/`. Never hardcode `/asset/...` paths — use the `buildId` from `shared/Build.ts`.
 
-// Performance timing — returns a stop function
-const stop = ctx.log.perf('db-query');
-// ... do work ...
-stop(); // records duration to MongoDB
-```
+---
 
-### Server Error Capture
+## Additional server APIs
 
-`captureServerError` persists unexpected errors to a MongoDB `errorLog` collection with automatic deduplication (repeated errors increment a `count` field instead of inserting duplicates). Expected/recoverable errors can be suppressed from persistence by registering patterns.
+### Email
 
 ```typescript
-import {
-  captureServerError,
-  registerExpectedErrorPattern,
-  classifyError,
-} from 'website-core';
+import { sendEmail, sendTemplateEmail, loadEmailTemplate } from 'ugly-app';
 
-// Register known-recoverable patterns at startup — matched errors log to
-// console only and are never written to MongoDB
-registerExpectedErrorPattern('ECONNRESET')
-registerExpectedErrorPattern('[STT] Session ended before audio was received')
+await sendEmail({ to: 'user@example.com', subject: 'Hello', html: '<p>Hi</p>' });
+await sendTemplateEmail('welcome', { name: 'Alice' }, { to: 'user@example.com' });
+```
 
-// Capture an error in a catch block
-try {
-  await riskyOperation()
-} catch (err) {
-  captureServerError('[MyService] Failed to process request', err, { userId })
-}
+### Push notifications
+
+```typescript
+import { sendPush, sendFcmPush } from 'ugly-app';
 
-// Classify a message manually ('expected' | 'unexpected')
-const classification = classifyError('[STT] Session ended before audio was received')
+await sendPush(userId, { title: 'New message', body: 'You have a new message' });
 ```
 
-### Push Notifications
+### NATS (pub/sub)
 
 ```typescript
-import { sendPush } from 'website-core';
+import { natsPublish, natsSubscribe, subscribeCollection, subscribeDoc } from 'ugly-app';
 
-await sendPush(userId, { title: 'New message', body: 'You have a reply' });
+natsPublish('my.subject', payload);
+const sub = natsSubscribe('my.subject', (msg) => { /* ... */ });
+sub(); // unsubscribe
 ```
 
-## CLI Commands
+### Redis
 
-| Command | Description |
-|---|---|
-| `web init <name>` | Scaffold a new project |
-| `web dev` | Start all dev services (Docker, server, Vite, TS, ESLint) |
-| `web build` | Production build |
-| `web db:init` | Create/update MongoDB indexes |
-| `web db:migrate` | Run pending database migrations (`--status` to preview) |
-| `web publish:assets` | Deploy static assets to CDN (`--dry-run` to preview) |
-| `web purge:assets` | Remove old build artifacts (keeps last 3 by default) |
-| `web logs:local` | Query local dev logs |
-| `web logs:server` | Query server logs from MongoDB |
-| `web error:local` | Query local error logs |
-| `web error:server` | Query server error logs from MongoDB |
-| `web perf:local` | Query local performance metrics |
-| `web perf:server` | Query server performance metrics from MongoDB |
-| `web feedback` | Query user feedback submissions |
-| `web auth:create-account` | Create an account directly in the database |
-| `web auth:create-token` | Generate a JWT for a userId |
-| `web test:e2e` | Run Playwright end-to-end tests (`--headed` for browser UI) |
-
-## React Components
-
-```typescript
-import {
-  Button, Card, Text, Input, Modal, Toast, PageLayout,
-  FeedbackButton,
-} from 'website-core/client';
-```
-
-The `FeedbackButton` captures a screenshot and submits it with user context automatically.
-
-## Routing (Client)
-
-```typescript
-const { useRouter, RouterProvider, RouterView } = createRouter(pages);
-
-function App() {
-  const { push, replace, back } = useRouter();
-  return (
-    <RouterProvider fallback={<NotFound />} loginFallback={<Login />} isAuthenticated={() => !!userId}>
-      <RouterView renderPage={(state) => <PageSwitch route={state.name} params={state.params} />} />
-    </RouterProvider>
-  );
-}
+```typescript
+import { getRedisClient } from 'ugly-app';
+const redis = getRedisClient();
 ```
 
-Page transitions are animated by default using `ViewFlipper`. The transition type (`PUSH`, `POP`, `REPLACE`, `NONE`) is inferred automatically from navigation calls.
-
-### Popups
+### Worker queues
 
 ```typescript
-import { useRouter } from './router';
-
-function MyComponent() {
-  const { openPopup } = useRouter();
+import { createWorkerQueue, enqueueTask } from 'ugly-app';
 
-  function openMenu() {
-    const handle = openPopup(<MyMenu />, {
-      mode: 'contextMenu',   // 'block' | 'transient' | 'contextMenu'
-      slideFrom: 'bottom',   // 'left' | 'right' | 'top' | 'bottom' | 'none'
-    });
+const queue = createWorkerQueue({ /* config */ });
+configurator.setWorkerQueue(queue);
 
-    // Dismiss programmatically
-    handle.hide();
-  }
-}
+await enqueueTask('taskName', payload);
 ```
 
-- **`block`** — modal overlay, blocks interaction behind it
-- **`transient`** — tapping the backdrop closes it
-- **`contextMenu`** — same as transient but typically for menus/pickers
+### Rate limiting
 
-### Animation Primitives
+```typescript
+// Inside a handler — always call before expensive operations
+await ctx.rateLimit.check();
+```
+
+### Embeddings
 
 ```typescript
-import {
-  createAnimatedValue,
-  useAnimatedValue,
-  Animated,
-  easingFunctions,
-} from 'website-core/client';
-import type { EasingFunction } from 'website-core/client';
+import { createEmbeddingClient, registerEmbeddingProvider } from 'ugly-app';
+const embeddings = createEmbeddingClient();
+```
 
-// Imperative animated value (RAF-driven, no React re-renders)
-const spring = createAnimatedValue(0);
-spring.animateTo(1, { duration: 300, easing: easingFunctions.easeInOut });
+### Billing
 
-// React hook version
-const opacity = useAnimatedValue(0);
+```typescript
+import { initBillingGateway, getBillingGateway } from 'ugly-app';
 
-// Apply to DOM via ref — zero re-renders
-<Animated value={spring} style={(v) => ({ opacity: v, transform: `scale(${v})` })}>
-  <div>Content</div>
-</Animated>
+await initBillingGateway({ /* config */ });
+const billing = getBillingGateway();
 ```
 
-## Project Structure
+---
 
-Projects built with `website-core` follow this layout:
+## 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: '' } });
+}
 ```
-my-app/
-├── src/
-│   ├── server/      # Express handlers, DB collections, migrations
-│   ├── client/      # React pages and components
-│   └── shared/      # API definitions and shared types
-├── static/          # Build-time static assets
-└── docker-compose.yml
-```
 
-## Environment Variables
+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 dev` | Start all dev services |
+| `ugly-app build` | Production build |
+| `ugly-app db:init` | Create/update MongoDB indexes |
+| `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 |
+| `ugly-app logs:local` | Query local dev logs |
+| `ugly-app logs:server` | Query server logs from MongoDB |
+| `ugly-app error:local` / `error:server` | Query error logs |
+| `ugly-app perf:local` / `perf:server` | Query performance metrics |
+| `ugly-app feedback` | Query user feedback submissions |
+| `ugly-app auth:create-account` | Create an account in the database |
+| `ugly-app auth:create-token` | Generate a JWT for a userId |
+
+---
+
+## Environment variables
 
 | Variable | Description |
-|---|---|
+|----------|-------------|
+| `JWT_SECRET` | **Required** — signs auth tokens |
 | `MONGODB_URI` | MongoDB connection string |
-| `JWT_SECRET` | Secret for signing JWT tokens |
-| `REDIS_URL` | Redis connection (optional, uses in-memory fallback) |
+| `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 |
-| `NATS_CREDS` | NATS credentials file path (Synadia Cloud) |
-| `STORAGE_ACCOUNT_ID` | Cloudflare R2 account ID (alias: `CLOUDFLARE_ACCOUNT_ID`) |
-| `STORAGE_ACCESS_KEY_ID` | R2 access key (alias: `CLOUDFLARE_R2_ACCESS_KEY_ID`) |
-| `STORAGE_SECRET_ACCESS_KEY` | R2 secret key (alias: `CLOUDFLARE_R2_SECRET_ACCESS_KEY`) |
-| `STORAGE_PUBLIC_BUCKET` | R2 public bucket name (alias: `CLOUDFLARE_R2_PUBLIC_BUCKET`) |
-| `STORAGE_TEMP_BUCKET` | R2 temp bucket name (alias: `CLOUDFLARE_R2_TEMP_BUCKET`) |
-| `STORAGE_PUBLIC_URL` | Base URL for public bucket (alias: `CLOUDFLARE_R2_PUBLIC_URL`) |
-| `STORAGE_TEMP_URL` | Base URL for temp bucket (alias: `CLOUDFLARE_R2_TEMP_URL`) |
-| `TOGETHER_API_KEY` | Together AI API key |
-| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
-| `OPENAI_API_KEY` | OpenAI API key |
-| `GOOGLE_API_KEY` | Google Gemini API key |
-| `IS_CLOCK_SERVER` | Set to `true` on the instance that processes worker queues |
-| `MAILGUN_API_KEY` | Mailgun API key (`key-...`) |
-| `MAILGUN_DOMAIN` | Mailgun sending domain (e.g., `mg.my-app.com`) |
-| `MAILGUN_FROM` | Default from address (e.g., `noreply@my-app.com`) |
+| `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 |
+| `MAILGUN_API_KEY` | Mailgun key |
+| `MAILGUN_DOMAIN` | Mailgun sending domain |
+| `MAILGUN_FROM` | Default from address |
 
 Client-side variables must be prefixed with `VITE_`.
 
-## Tech Stack
-
-- **Runtime**: Node.js, TypeScript (ES2022, NodeNext modules)
-- **Server**: Express, ws (WebSockets)
-- **Frontend**: React 19, Vite, Tailwind CSS
-- **Database**: MongoDB
-- **Messaging**: NATS with JetStream
-- **Cache**: Redis (in-memory fallback for dev)
-- **Storage**: AWS S3 / Cloudflare R2
-- **Auth**: JWT (jose), OAuth
-- **AI**: Together AI, Anthropic, OpenAI, Google, Groq, FAL
-- **Audio**: InWorld TTS, Groq Whisper STT
-- **Validation**: Zod
-- **Testing**: Vitest, Playwright, mongodb-memory-server
+---
 
-## Development
+## Tech stack
 
-```bash
-npm run build       # Compile TypeScript
-npm test            # Run unit tests
-npm run test:watch  # Watch mode
-```
+Node.js · TypeScript · Express · React 19 · Vite · Tailwind CSS · MongoDB · NATS · Redis · Cloudflare R2 · Zod · JWT (jose) · ugly.bot OAuth