ugly-app 0.1.910 → 0.1.912

package/README.md

@@ -1,8 +1,14 @@
 # ugly-app
 
-A full-stack TypeScript framework for shipping production web apps. Scaffold with `npx ugly-app init my-app` and get an opinionated Express + React + PostgreSQL stack with type-safe RPC over WebSocket and HTTP, real-time document tracking, built-in auth, AI generation, storage, workers, and a CLI for every workflow.
+A full-stack TypeScript framework for shipping production web apps. Scaffold with
+`npx ugly-app init my-app` and get an opinionated Express + React + PostgreSQL stack
+with type-safe RPC over WebSocket and HTTP, real-time document tracking, built-in
+auth, AI generation, storage, workers, and a CLI for every workflow.
 
-ugly-app is designed to run against [ugly.bot](https://ugly.bot), which provides auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of it through the project's dev tunnel and its `UGLY_BOT_TOKEN`.
+ugly-app is designed to run against [ugly.bot](https://ugly.bot), which provides
+auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider
+keys, and deployment. Your app talks to all of it through the project's dev tunnel
+and its `UGLY_BOT_TOKEN`.
 
 ## What's included
 
@@ -25,13 +31,16 @@ 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 other test pages already wired up.
+The scaffold gives you a working app at `http://localhost:4321` with todo CRUD, AI
+chat, file upload, auth demo, collab editing, and other test pages already wired
+up.
 
 ---
 
 ## Server — `createApp()` / `AppConfigurator`
 
-The single server entry point. Returns an `App` that owns Express, the WebSocket server, the typed DB, and the RPC dispatcher.
+The single server entry point. Returns an `App` that owns Express, the WebSocket
+server, the typed DB, and the RPC dispatcher.
 
 ```ts
 import {
@@ -76,7 +85,10 @@ function createApp<
 ): App<CollectionMap<typeof BUILTIN_DEFS & Defs>, RegistryPages<R>>;
 ```
 
-Passing `pages` in the registry (`{ requests, messages, pages }`) upgrades `app.pushSend()` to a per-route typed API. `pages` is optional; apps that only call `configurator.setPages()` still work — they just get the loose `PageRegistry` typing on `pushSend`.
+Passing `pages` in the registry (`{ requests, messages, pages }`) upgrades
+`app.pushSend()` to a per-route typed API. `pages` is optional; apps that only call
+`configurator.setPages()` still work — they just get the loose `PageRegistry`
+typing on `pushSend`.
 
 ### The returned `App`
 
@@ -90,7 +102,11 @@ Passing `pages` in the registry (`{ requests, messages, pages }`) upgrades `app.
 | `registerRoutes(fn)` | Mount additional Express routes after creation. |
 | `pushSend({ targetUserId, title, body, page, query, imageUrl?, requireAuth? })` | Send a push whose click-through target is a route from this app's `pages` table. `page` and `query` are type-checked when the registry carries `pages`; the framework mints a `https://ugly.bot/l/<code>` short link so the click-through is always absolute and dock-app-routable. |
 
-Framework services start automatically inside `app.start()`: schema drift check, NATS connection + KV buckets, data-proxy connection, event-counter flush, TTL cleanup for log tables, console/error capture, and ugly.bot log forwarding. Postgres, NATS, storage, and AI clients are loaded **lazily** — a host without `DATABASE_URL` / `NATS_URL` / `R2_BUCKET` doesn't pay their startup cost.
+Framework services start automatically inside `app.start()`: schema drift check,
+NATS connection + KV buckets, data-proxy connection, event-counter flush, TTL
+cleanup for log tables, console/error capture, and ugly.bot log forwarding.
+Postgres, NATS, storage, and AI clients are loaded **lazily** — a host without
+`DATABASE_URL` / `NATS_URL` / `R2_BUCKET` doesn't pay their startup cost.
 
 ### `AppConfigurator`
 
@@ -98,11 +114,11 @@ Every method is optional; `setPages` is what mounts the SPA.
 
 | Method | Description |
 |--------|-------------|
-| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. Dev runs Vite in middleware mode; prod serves `dist/client`. Provide `renderPage(routeName, params) => Promise<string>` to SSR any `ssr: true` pages. |
-| `setUserHelper(helper)` | Customize how the framework reads/writes the `user` collection during WS auth. |
+| `setPages({ pages, renderPage?, clientDistPath? })` | Mount the SPA. Dev runs Vite in middleware mode; prod serves `clientDistPath` (default `dist/client`). Provide `renderPage(routeName, params) => Promise<string>` to SSR any `ssr: true` pages. |
+| `setUserHelper(helper)` | Provide a `UserHelper<UserBase>` — required for WebSocket auth (framework reads/writes the `user` collection through it). |
 | `setOnUserCreate(handler)` | `(userId, { email?, phone? }, db) => Promise<void>` — called on first login; create the user record. |
 | `setAuth(provider)` | Replace the default auth provider (`verify(code)`, `authUrl(origin)`, optional `registerRoutes`). |
-| `setOnSocketMessage(handler)` | Single raw-WebSocket handler. `(ws, userId, msg) => boolean` — return `true` to consume, `false` to fall through. |
+| `setOnSocketMessage(handler)` | Single raw-WebSocket handler. `(ws, userId, msg) => boolean` — return `true` to consume, `false` to fall through. Replaces any previously registered handler. |
 | `addSocketMessageHandler(handler)` | Append to the handler chain; first `true` wins. |
 | `setWsPath(path)` | Override the WebSocket path (default `/rpc`). |
 | `setOnWsAuth(handler)` | `(ws, userId, req) => void` — fires after a socket session authenticates. |
@@ -112,7 +128,7 @@ Every method is optional; `setPages` is what mounts the SPA.
 | `setExperiments(experiments)` | Register `Experiment` definitions for `initSession` / `captureEvent` bucketing. |
 | `setIsAdmin(fn)` | `(userId, db) => boolean \| Promise<boolean>` — gate for admin-only framework requests. Defaults to matching `MAINTAIN_BOT_USER_ID`. |
 | `setOnEmail(handler)` | Handle inbound emails routed to `{domain}@ugly.bot` (delivered as internal HTTP). |
-| `setCronTasks(tasks, handlers)` | Legacy cron-only registry. Prefer `setWorkers()`. |
+| `setCronTasks(tasks, handlers)` | **Deprecated.** Legacy cron-only registry — prefer `setWorkers()`. |
 | `setWorkers(workers, handlers)` | Register named async tasks with optional Zod input schema and cron schedule. Powers `GET /_workers/manifest`, `POST /_workers/run`, and the cron orchestrator. Scheduled workers are mirrored into the cron registry automatically. |
 | `setStrings(config)` | Localization config — framework injects language + critical strings into SSR HTML. |
 | `registerRoutes(fn)` | Mount custom Express routes. |
@@ -120,7 +136,8 @@ Every method is optional; `setPages` is what mounts the SPA.
 
 ### Handler signatures
 
-Handlers are plain async functions — no context object. Access state via captured imports (`app.db`, `storage`, `pgQuery`, `uglyBotRequest`, etc.).
+Handlers are plain async functions — no context object. Access state via captured
+imports (`app.db`, `storage`, `pgQuery`, `uglyBotRequest`, etc.).
 
 ```ts
 // req() — public, userId may be null
@@ -132,18 +149,21 @@ getMe: async (userId: string, input) => { … }
 
 ### Built-in framework requests
 
-`createApp` registers several framework handlers reachable from any client via the normal RPC pipeline. App-provided handlers with the same name override the framework's defaults.
+`createApp` registers several framework handlers reachable from any client via the
+normal RPC pipeline. App-provided handlers with the same name override the
+framework's defaults.
 
 | Name | Purpose |
 |------|---------|
 | `userGet` | Returns `{ userId, name, avatarUri }` for the given user (or caller). |
-| `initSession` / `captureEvent` | Session + event logging tagged with experiment branches. |
+| `initSession` / `captureEvent` | Session + event logging tagged with experiment branches (public — no auth). |
 | `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. |
 | `shareLink` | Mint a `https://ugly.bot/l/<code>` short link with OG metadata (see the "sharing links" rule in `CLAUDE.md`). |
 | `feedbackReportCreateNoAuth` / `errorLogCaptureNoAuth` / `perfSnapshotCaptureNoAuth` | Same-origin, public endpoints used by browser telemetry to write into the project's Postgres. |
 | `submitFeedbackBot` / `feedbackReportResolve` | Bot-persona feedback submission; admin resolve/decline. |
+| `adminGetPerfLogs` | Admin-only perf telemetry read. |
 | `adminCreateTestUser` / `adminListTestUsers` / `adminDeleteTestUser` | Admin-only synthetic-user management. Gated by `setIsAdmin()` (or `MAINTAIN_BOT_USER_ID`). |
 | `projectPlanList` / `projectPlanCreate` / `projectPlanUpdate` / `projectPlanDelete` | Project plan CRUD used by Studio. |
 
@@ -151,7 +171,8 @@ getMe: async (userId: string, input) => { … }
 
 ## Shared API definitions
 
-`shared/` is consumed by both server and client. Keep all Zod schemas, types, collections, and route declarations here.
+`shared/` is consumed by both server and client. Keep all Zod schemas, types,
+collections, and route declarations here.
 
 ### Requests (`shared/api.ts`)
 
@@ -180,7 +201,9 @@ export const requests = defineRequests({
 });
 ```
 
-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.
+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`)
 
@@ -221,15 +244,21 @@ export const collections = defineCollections({
 - `search?: { fields, language? }` — full-text index over the named JSONB paths (Neon: Postgres FTS; D1: SQLite FTS5, ranked by bm25).
 - `vector?: { dimensions, metric?, filterable? }` — ANN index. The vector is supplied out-of-band at write time (`setDoc(c, doc, { vec })`) — never stored in the doc JSON. Query with `getDocs(c, filter, { near })`.
 
-All documents extend `DBObject`: `{ _id, version, created, updated }`. Use `dbDefaults()` to stamp `version` / `created` / `updated` on inserts. **Always generate `_id` with `nanoid()`** — never `crypto.randomUUID()`, `Date.now()`, or `Math.random()` (see `CLAUDE.md`).
+All documents extend `DBObject`: `{ _id, version, created, updated }`. Use
+`dbDefaults()` to stamp `version` / `created` / `updated` on inserts. **Always
+generate `_id` with `nanoid()`** — never `crypto.randomUUID()`, `Date.now()`, or
+`Math.random()` (see `CLAUDE.md`).
 
-After schema changes, run `npm run db:schema-gen` then `npm run db:migrate`. The app refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true` only as a last resort).
+After schema changes, run `npm run db:schema-gen` then `npm run db:migrate`. The
+app refuses to start when drift is detected (set `SCHEMA_CHECK_SKIP=true` only as
+a last resort).
 
 ---
 
 ## Routing
 
-Route definitions live in `shared/pages.ts`; the client-side router is created by `createRouter({ pages, allPages?, ssrPages? })`.
+Route definitions live in `shared/pages.ts`; the client-side router is created by
+`createRouter({ pages, allPages?, ssrPages? })`.
 
 ### `definePage` / `definePages` (`shared/pages.ts`)
 
@@ -245,16 +274,22 @@ export const pages = definePages({
 export type AppPages = typeof pages;
 ```
 
-`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime object carrying `PageMeta` plus a phantom `_params` used only for TypeScript inference. Options:
+`definePage<Params>(options?)` returns a `PageDef<Params>` — a runtime object
+carrying `PageMeta` plus a phantom `_params` used only for TypeScript inference.
+
+Options (all optional):
 
 - `auth` (default `true`) — protected route. When `isAuthenticated()` returns false on this route, the router synchronously renders the framework's `<AuthRoot>` in place of the page (dispatches on `window.__UGLY_APP_AUTH_MODE__`: Mode A → `<LoginPopup>`, Mode B → `<MagicLinkForm>` plus optional Google button). Apps cannot override this fallback — the framework owns the login UX so no route can accidentally ship as auth-required with no way to log in.
 - `ssr` (default `false`) — server-render the page for SEO. `{ auth: true, ssr: true }` is silently dropped to `ssr: false` with a warning: the SSR document is served from a shared edge cache and must not depend on the viewer.
 - `cacheQuery?: string[]` — query params that participate in the SSR edge-cache key. Anything NOT listed bypasses the cache instead of poisoning it (e.g. `cacheQuery: ['q']` on a search page).
 - `ssrCacheTimeout?: number` — edge cache lifetime in seconds. Default is effectively 1 year (`DEFAULT_SSR_CACHE_TIMEOUT`) because the `buildId` is part of the cache key. Override only for pages that drift between deploys.
 
-Path syntax: `:param` matches a single path segment; `*param` is greedy (captures slashes). Query-string params are declared in `Params` but never appear in the path template.
+Path syntax: `:param` matches a single path segment; `*param` is greedy (captures
+slashes). Query-string params are declared in `Params` but never appear in the
+path template.
 
-`definePages<T>(p)` is a pass-through identity — use it to give the registry a name.
+`definePages<T>(p)` is a pass-through identity — use it to give the registry a
+name.
 
 ### `createRouter()` (`ugly-app/client`)
 
@@ -285,9 +320,13 @@ export const {
 - **`Link`** — typed SPA link bound to this router. Renders a real `<a>` (right-click / cmd-click / SEO keep working) but intercepts a plain left-click and routes through `push` / `replace`. Props: `to`, `params` (both type-checked against `pages`), `replace?`, `children`, plus common anchor attrs (`className`, `style`, `target`, `aria-label`, `data-id`, `onClick`).
 - **`setAllPages(map)`** — register the lazy `PageMap<Pages>` after construction (typically from the browser entry, so the Worker's import graph stays free of every lazy page).
 
-A standalone `Link` is also exported from `ugly-app/client` for code that can't easily reach the typed one; it accepts an optional `router` prop and falls back to `<RouterProvider>` context.
+A standalone `Link` is also exported from `ugly-app/client` for code that can't
+easily reach the typed one; it accepts an optional `router` prop and falls back
+to `<RouterProvider>` context.
 
-**Never use a bare `<a href="/route">`** for internal navigation — it triggers a full document reload (white flash + repaint). See the "client navigation" rule in `CLAUDE.md`.
+**Never use a bare `<a href="/route">`** for internal navigation — it triggers a
+full document reload (white flash + repaint). See the "client navigation" rule in
+`CLAUDE.md`.
 
 ### Page map — `lazyPage` / `lazyPageLoader`
 
@@ -307,7 +346,10 @@ export const allPages = {
 - **`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.
 
-Both wrappers recover from stale-deploy chunk 404s ("Failed to fetch dynamically imported module"): on the first failure they trigger a single `window.location.reload()` (guarded by `sessionStorage` so a genuinely broken chunk can't loop) to fetch the fresh `index.html` with new chunk hashes.
+Both wrappers recover from stale-deploy chunk 404s ("Failed to fetch dynamically
+imported module"): on the first failure they trigger a single
+`window.location.reload()` (guarded by `sessionStorage` so a genuinely broken
+chunk can't loop) to fetch the fresh `index.html` with new chunk hashes.
 
 ```ts
 // pages/SlowPageLoader.tsx
@@ -337,11 +379,15 @@ replace('search', { q: 'hello' });         // → /search?q=hello
 back();                                     // browser history back
 ```
 
-Route names and params are fully typed against `pages`. `push` / `replace` no-op with a `console.error` when `buildUrl()` produces a URL that doesn't match a registered route.
+Route names and params are fully typed against `pages`. `push` / `replace` no-op
+with a `console.error` when `buildUrl()` produces a URL that doesn't match a
+registered route.
 
 ### Popups — `openPopup()`
 
-`useRouter().openPopup()` is the canonical modal / sheet / menu API. The router owns the popup layer, drives a spring animation, and stacks popups z-index-correctly above every page.
+`useRouter().openPopup()` is the canonical modal / sheet / menu API. The router
+owns the popup layer, drives a spring animation, and stacks popups z-index-
+correctly above every page.
 
 ```tsx
 const { openPopup } = useRouter();
@@ -365,13 +411,18 @@ handle.hide(); // dismiss programmatically
 - **`transient`** — 20% opacity backdrop, **dismisses** on backdrop click.
 - **`contextMenu`** — same as transient, intended for menus and pickers.
 
-`renderLayer` receives `{ content, spring, hide }`: `spring` is a `createAnimatedValue()` result driving 0 → 1; `hide` closes the popup. The default layer animates open with `easeOut` (250 ms) and closed with `easeIn` (200 ms). Popups render as siblings of the router's children (managed inside `RouterProvider`), so they stack above every page.
+`renderLayer` receives `{ content, spring, hide }`: `spring` is a
+`createAnimatedValue()` result driving 0 → 1; `hide` closes the popup. The default
+layer animates open with `easeOut` (250 ms) and closed with `easeIn` (200 ms).
+Popups render as siblings of the router's children (managed inside
+`RouterProvider`), so they stack above every page.
 
 ---
 
 ## Client — `bootstrapApp()`
 
-The recommended entry point. Handles auth detection, socket creation, background account-sync with ugly.bot, and provider wiring.
+The recommended entry point. Handles auth detection, socket creation, background
+account-sync with ugly.bot, and provider wiring.
 
 ```tsx
 // client/main.tsx
@@ -403,23 +454,35 @@ bootstrapApp({
 | `silentSso?` | Apex-domain apps that use ugly.bot as their auth authority but don't share its cookie. When `true`, a logged-out boot attempts a top-level SSO redirect (once per tab) to adopt an existing ugly.bot session. Leave unset for `*.ugly.bot` subdomains and Mode B apps. |
 | `testMode?` | Skip ugly.bot silent SSO and trust the auth cookie the fixture set. Only honored when `UGLY_APP_TEST_MODE=1`. |
 
-`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server after cookie verification). If absent, it renders unauthenticated immediately — the router's per-route auth guard surfaces `<AuthRoot>` only when the user opens a protected route. If the token is present, it connects the socket, mounts `<AppProvider>`, and renders.
+`bootstrapApp` reads `window.__AUTH_TOKEN__` (injected by the server after cookie
+verification). If absent, it renders unauthenticated immediately — the router's
+per-route auth guard surfaces `<AuthRoot>` only when the user opens a protected
+route. If the token is present, it connects the socket, mounts `<AppProvider>`,
+and renders.
 
-After render, a hidden iframe silently calls `${UGLY_BOT_URL}/oauth/silent`: if it returns a fresh code, the cookie is refreshed via `POST /auth/verify`; if the returned account differs from the current session, the page reloads onto the live account (guarded once per from→to pair to prevent loops). Any `?ugly_oauth_code=…` in the URL (redirect-fallback OAuth code from ugly.bot) is redeemed at the top of bootstrap before anything renders.
+After render, a hidden iframe silently calls `${UGLY_BOT_URL}/oauth/silent`: if it
+returns a fresh code, the cookie is refreshed via `POST /auth/verify`; if the
+returned account differs from the current session, the page reloads onto the live
+account (guarded once per from→to pair to prevent loops). Any
+`?ugly_oauth_code=…` in the URL (redirect-fallback OAuth code from ugly.bot) is
+redeemed at the top of bootstrap before anything renders.
 
-If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it renders `<MagicLinkCallback>` instead of the regular app shell.
+If `bootstrapApp` is loaded at `/auth/magic-link/verify` (Mode B), it renders
+`<MagicLinkCallback>` instead of the regular app shell.
 
 ### `AppProvider` & `useApp()`
 
-`bootstrapApp` mounts `<AppProvider>` automatically after socket connect. Use `useApp()` inside any page to access the active user, socket, and app-scoped services.
+`bootstrapApp` mounts `<AppProvider>` automatically after socket connect. Use
+`useApp()` inside any page to access the active user, socket, and app-scoped
+services.
 
 ```ts
 const {
   userId,        // current user id (string)
   user,          // UserBase doc
   socket,        // AppSocket — typed RPC client
-  uglyBotSocket, // UglyBotSocket | null — for direct platform calls (STT/TTS, etc.)
-  showPopup,     // AppProvider-owned popup layer (see note below)
+  uglyBotSocket, // UglyBotSocket | null — direct platform socket for STT/TTS, etc.
+  showPopup,     // AppProvider-owned popup layer (see note below) — returns popup id
   hidePopup,
   hideAllPopups,
   runAsync,      // (label, async () => {…}, options?) — shows loading overlay while pending
@@ -428,9 +491,18 @@ const {
 } = useApp();
 ```
 
-`useApp<TAsyncOptions>()` is generic in the async-options type so apps can pass a custom option through to a custom `loadingOverlay` element (accepted as an `AppProvider` prop — the framework `cloneElement`s the overlay with `{ label, asyncOptions }` while `runAsync` is pending). `useAppOptional()` returns `null` outside the provider; `useLocalizer()` returns a localizer that prefers `<StringsProvider>` data, falls back to the `AppProvider` `localizer` prop, and finally to identity.
+`useApp<TAsyncOptions>()` is generic in the async-options type so apps can pass a
+custom option through to a custom `loadingOverlay` element (accepted as an
+`AppProvider` prop — the framework `cloneElement`s the overlay with
+`{ label, asyncOptions }` while `runAsync` is pending). `useAppOptional()`
+returns `null` outside the provider; `useLocalizer()` returns a localizer that
+prefers `<StringsProvider>` data, falls back to the `AppProvider` `localizer`
+prop, and finally to identity.
 
-Two popup APIs coexist: `useRouter().openPopup()` (spring-animated, dismissible, mode-aware — the default choice) and `useApp().showPopup()` (a flat overlay layer for content that must sit *outside* the router transition). Prefer the router's.
+Two popup APIs coexist: `useRouter().openPopup()` (spring-animated, dismissible,
+mode-aware — the default choice) and `useApp().showPopup()` (a flat overlay layer
+returning a string id, for content that must sit *outside* the router
+transition). Prefer the router's.
 
 ### Direct socket access
 
@@ -447,20 +519,23 @@ Two popup APIs coexist: `useRouter().openPopup()` (spring-animated, dismissible,
 | `connectionState` | `'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`. |
 | `disconnect()` | Close the connection. |
 
-For pure HTTP (no WebSocket), use `createHttpClient({ requests, token?, baseUrl? })` from `ugly-app/client`.
+For pure HTTP (no WebSocket), use `createHttpClient({ requests, token?, baseUrl? })`
+from `ugly-app/client`.
 
 ---
 
 ## Auth
 
-ugly-app uses HttpOnly cookies and server-side JWT injection — no `localStorage`, no client-side token handling.
+ugly-app uses HttpOnly cookies and server-side JWT injection — no `localStorage`,
+no client-side token handling.
 
 Two modes, picked from the `auth` block in the project's `.uglyapp` config:
 
 - **Mode A — `mode: 'uglybot'`** (default when no `auth` block is present). Auth is delegated to ugly.bot OAuth. AI / email / push proxies bill the end user's ugly.bot credits.
 - **Mode B — `mode: 'self'`**. The app issues its own sessions via magic-link email and/or Google OAuth. AI / email / push proxies bill the developer's ugly.bot account using the project's `AI_PROXY_TOKEN`.
 
-`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client code (incl. `<AuthRoot>`) can branch correctly.
+`window.__UGLY_APP_AUTH_MODE__` is injected into every page so client code (incl.
+`<AuthRoot>`) can branch correctly.
 
 ### Mode A — ugly.bot OAuth (default)
 
@@ -472,7 +547,9 @@ Two modes, picked from the `auth` block in the project's `.uglyapp` config:
 
 ### Mode B — self-issued sessions
 
-When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the magic-link provider as primary; if `providers.google.clientId` is configured it adds Google as an extra provider on the same router.
+When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the magic-link
+provider as primary; if `providers.google.clientId` is configured it adds Google
+as an extra provider on the same router.
 
 - `<AuthRoot>` renders `<MagicLinkForm>` (plus the Google button when configured) instead of `<LoginPopup>`.
 - Background ugly.bot silent SSO is a no-op.
@@ -482,7 +559,9 @@ When `.uglyapp` sets `auth.mode: 'self'`, `buildAuth()` wires the magic-link pro
 
 ### Token-in-URL embed
 
-Any GET request with `?token=<JWT>` will, if the token verifies, set the cookie and 302-redirect to the same URL without the token parameter — useful for embedding any page in an iframe.
+Any GET request with `?token=<JWT>` will, if the token verifies, set the cookie
+and 302-redirect to the same URL without the token parameter — useful for
+embedding any page in an iframe.
 
 ### Built-in routes
 
@@ -515,7 +594,9 @@ configurator.setAuth({
 
 ## Database — `TypedDB`
 
-Access via `app.db`. All methods accept a `CollectionDef` (from `defineCollections()`) or, on the `raw*` / `getQuery*` variants, a plain collection name string.
+Access via `app.db`. All methods accept a `CollectionDef` (from
+`defineCollections()`) or, on the `raw*` / `getQuery*` variants, a plain
+collection name string.
 
 ### Writing
 
@@ -540,7 +621,10 @@ await db.batch(async () => {
 });
 ```
 
-Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`, `$set`. All keys are dot-notation, fully typed against the collection's schema. Partial updates go through optimistic concurrency to prevent lost updates on concurrent writers.
+Supported update operators: `$inc`, `$addToSet`, `$pull`, `$unset`, `$set`. All
+keys are dot-notation, fully typed against the collection's schema. Partial
+updates go through optimistic concurrency to prevent lost updates on concurrent
+writers.
 
 ### Reading
 
@@ -574,7 +658,8 @@ 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.
+Pass `deleteHandlers` as the 5th argument to `createApp` to run per-collection
+`onDelete` callbacks.
 
 ### Search
 
@@ -623,12 +708,14 @@ Imports available from `ugly-app`:
 
 ## AI
 
-AI calls are proxied through ugly.bot — your app never holds a provider key. Pass `UGLY_BOT_TOKEN` in the environment and the framework handles routing, balance tracking, retries, and per-user billing.
+AI calls are proxied through ugly.bot — your app never holds a 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
 
 ```ts
-import { createTextGen } from 'ugly-app';        // aliased as createTextGenClient
+import { createTextGen } from 'ugly-app';
 const textGen = createTextGen(userId);
 
 const text = await textGen.generate(messages, { model: 'gemini_2_5_flash' });
@@ -645,18 +732,21 @@ const { message } = await uglyBotRequest<{ message: { content: string } }>('text
 });
 ```
 
-Available models are exposed via `textGenModels` / `textGenModelData` from `ugly-app` — the platform supports Claude, GPT, Gemini, Together, Groq, Fireworks, Kimi, and Kie families.
+Available models are exposed via `textGenModels` / `textGenModelData` from
+`ugly-app` — the platform supports Claude, GPT, Gemini, Together, Groq,
+Fireworks, Kimi, and Kie families.
 
 ### Server-side image generation
 
 ```ts
-import { createImageGen } from 'ugly-app';       // aliased as createImageGenClient
+import { createImageGen } from 'ugly-app';
 const imageGen = createImageGen(userId);
 
 const url = await imageGen.generate('A red panda eating noodles', { model: 'flux_schnell' });
 ```
 
-`imageGenModels` / `imageGenModelData` enumerate available models (Together FLUX, FAL, Google Imagen, Wavespeed, Kie Kolors).
+`imageGenModels` / `imageGenModelData` enumerate available models (Together FLUX,
+FAL, Google Imagen, Wavespeed, Kie Kolors).
 
 ### Embeddings
 
@@ -681,7 +771,8 @@ await search.enrichNews({ query: 'topic' });
 
 ### Client-side AI calls
 
-Calls from React components go through the framework RPC pipeline — no token plumbing in the browser:
+Calls from React components go through the framework RPC pipeline — no token
+plumbing in the browser:
 
 ```ts
 import { callTextGen, callJsonGen, callImageGen } from 'ugly-app/client';
@@ -693,7 +784,8 @@ const image = await callImageGen({ prompt: 'a corgi astronaut', model: 'flux_sch
 
 ### STT / TTS
 
-Speech goes **directly** from the browser to ugly.bot — never proxied through your app server (see the "STT/TTS routes to ugly.bot" rule in `CLAUDE.md`).
+Speech goes **directly** from the browser to ugly.bot — never proxied through
+your app server (see the "STT/TTS routes to ugly.bot" rule in `CLAUDE.md`).
 
 ```ts
 import { useSTT, useTTS, AudioPlayer, AudioRecorder } from 'ugly-app/client';
@@ -702,7 +794,8 @@ const { start, stop, transcript, isListening } = useSTT(uglyBotSocket, options);
 const { speak, stop: stopTTS }                 = useTTS(uglyBotSocket);
 ```
 
-`uglyBotSocket` is the `UglyBotSocket` on `useApp()`; it opens a direct WebSocket to the platform.
+`uglyBotSocket` is the `UglyBotSocket` on `useApp()`; it opens a direct WebSocket
+to the platform.
 
 ---
 
@@ -726,11 +819,15 @@ const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);
 await storage.delete('public', destKey);
 ```
 
-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.
+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.
 
-`STORAGE_KEY_PREFIX` (env) prefixes all keys — useful for per-environment isolation.
+`STORAGE_KEY_PREFIX` (env) prefixes all keys — useful for per-environment
+isolation.
 
-On Cloudflare Workers, storage uses the R2 binding directly; presigned PUTs are not exposed (browser uploads must go through a Worker endpoint).
+On Cloudflare Workers, storage uses the R2 binding directly; presigned PUTs are
+not exposed (browser uploads must go through a Worker endpoint).
 
 ---
 
@@ -762,9 +859,15 @@ const cronHandlers: WorkerHandlers<typeof cronTasks> = {
 configurator.setWorkers(cronTasks, cronHandlers);
 ```
 
-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.
+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.
 
-On the Workers adapter, scheduled workers dispatch through Cloudflare Cron Triggers and durable queueing goes through Cloudflare Queues. On the Node adapter, `enqueueWorker` runs the handler inline (in-process queues only).
+On the Workers adapter, scheduled workers dispatch through Cloudflare Cron
+Triggers and durable queueing goes through Cloudflare Queues. On the Node
+adapter, `enqueueWorker` runs the handler inline (in-process queues only).
 
 ---
 
@@ -779,7 +882,9 @@ configurator.setStrings({
 });
 ```
 
-The framework injects `window.__LANG__`, `window.__STRINGS_VERSION__`, and `window.__CRITICAL_STRINGS__` into SSR HTML. Use `useLocalizer()` / `useStrings()` / `useLang()` / `useChangeLanguage()` on the client.
+The framework injects `window.__LANG__`, `window.__STRINGS_VERSION__`, and
+`window.__CRITICAL_STRINGS__` into SSR HTML. Use `useLocalizer()` /
+`useStrings()` / `useLang()` / `useChangeLanguage()` on the client.
 
 ---
 
@@ -804,7 +909,9 @@ export const experiments: Experiment[] = [
 configurator.setExperiments(experiments);
 ```
 
-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.
+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.
 
 ---
 
@@ -859,7 +966,10 @@ The same developer source compiles for two runtimes via `src/server/adapter/`:
 - **Adapter A — Node + TCP** (`src/server/adapter/node/`): default for `npm run dev` and any non-Workers deploy. Wraps `pg.Pool`, `nats.js`, AWS S3 SDK.
 - **Adapter B — Cloudflare Workers** (`src/server/adapter/workers/`): used when the Studio publish flow deploys to Cloudflare. Hono router + Durable Objects (one `CollectionDO` per project-collection, plus a `SessionDO` per user WS) + `@neondatabase/serverless` HTTP driver + R2 binding + Cloudflare Cron Triggers + Cloudflare Queues.
 
-Developer-facing APIs (`createTypedDB`, `subscribeDoc`, `createStorageClient`, `setCronTasks`, `setWorkers`) don't change between adapters. Local Workers dev boots via `npm run dev:workers`, which starts a small Node HTTP proxy speaking Neon's wire format so the Worker can talk to a real Postgres.
+Developer-facing APIs (`createTypedDB`, `subscribeDoc`, `createStorageClient`,
+`setCronTasks`, `setWorkers`) don't change between adapters. Local Workers dev
+boots via `npm run dev:workers`, which starts a small Node HTTP proxy speaking
+Neon's wire format so the Worker can talk to a real Postgres.
 
 ---
 
@@ -888,7 +998,8 @@ Developer-facing APIs (`createTypedDB`, `subscribeDoc`, `createStorageClient`, `
 | `NEON_PROXY_URL` | Set by `dev:workers` — Neon-wire endpoint the local Neon HTTP driver dials. |
 | `CLOUDFLARE_WORKERS` | Set to `1` inside the Workers adapter for runtime detection. |
 
-Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta.env.VITE_*`.
+Browser-visible variables must be prefixed `VITE_` and consumed via
+`import.meta.env.VITE_*`.
 
 ---
 
@@ -913,7 +1024,8 @@ Browser-visible variables must be prefixed `VITE_` and consumed via `import.meta
 | `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`.
+Inside a scaffolded project, the same commands are available via `npm run …`
+scripts — see `templates/CLAUDE.md`.
 
 ---
 
@@ -926,10 +1038,13 @@ Schema changes must be deliberate:
 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).
+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 · PostgreSQL (JSONB) · Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · Cloudflare Workers + Durable Objects (Adapter B) · ugly.bot platform
+Node.js · TypeScript · Express · React 19 · Vite · PostgreSQL (JSONB) · Qdrant ·
+NATS · S3-compatible storage · Zod · JWT (jose) · Cloudflare Workers + Durable
+Objects (Adapter B) · ugly.bot platform

package/dist/cli/anythingworld.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Anything World 3D pipeline via ugly.bot's `aw*` ops. Rigs and animates ANIMALS — the one thing the
+ * other two providers cannot do:
+ *   find <query>                  search the 3D library                (FREE)
+ *   models                        every model this account has processed (FREE)
+ *   status <modelId>              poll a job, and print its clips       (FREE)
+ *   animate <file...>             upload → rig + animate               (~5 credits, ~$1.25)
+ *   rig <file...>                 upload → rig only                    (~5 credits)
+ *
+ * Measured 2026-07-25 on real four-legged bodies: Meshy returns a 24-joint BIPED (…LeftForeArm,
+ * LeftHand) with a clip called `walking_man`, and Tripo FAILS the task on rig_type 'quadruped'.
+ * Anything World's library reports `quadruped`, `quadruped_ungulate`, `winged_flyer` and `hopper`,
+ * carrying idle + walk + RUN for walkers and fly + glide for flyers.
+ *
+ * ⚠️ TWO BUDGETS. `find` / `models` / `status` are library calls against a free monthly allowance;
+ * `animate` / `rig` spend processing credits. Verify and poll on the free side — never by
+ * re-submitting. Uploads are multipart, so a local GLB goes straight in with no public hosting.
+ *
+ * ⚠️ "FREE" IS NOT "UNLIMITED", and the allowance is smaller than it looks. Measured 2026-07-25: a
+ * dozen or so `find` calls exhausted the month, after which EVERY web API call — polling included —
+ * returns `{"code":"Too many requests error"}`. Two consequences worth planning around:
+ *   · a job in flight cannot be polled once the allowance is gone, so budget calls for the whole
+ *     lifetime of the work, not just for the submit;
+ *   · asset URLs inside a response are SIGNED and expire in ~45 minutes. If a response carries a
+ *     model you want, download it in that session — re-fetching costs another call you may not have.
+ */
+interface AwOpts {
+    name?: string;
+    type?: string;
+    output?: string;
+    symmetric?: string;
+    autoRotate?: string;
+    stage?: string;
+    generated?: boolean;
+    shareForTraining?: boolean;
+}
+export declare function runAnythingWorld(op: string, args: string[], opts: AwOpts): Promise<void>;
+export {};
+//# sourceMappingURL=anythingworld.d.ts.map

package/dist/cli/anythingworld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anythingworld.d.ts","sourceRoot":"","sources":["../../src/cli/anythingworld.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,UAAU,MAAM;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAgGD,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CA4Ff"}