ugly-app 0.1.0

package/dist/shared/Socket.d.ts

@@ -0,0 +1,26 @@
+import type { FunctionRegistry, RequestRegistry } from './Api.js';
+/**
+ * Unauthenticated socket — can only make public `request()` calls.
+ * Parameterized by the app's request registry.
+ */
+export interface SocketLoggedOut<Requests extends RequestRegistry> {
+    type: 'loggedOut';
+    sessionId: string;
+    request<K extends keyof Requests>(name: K, input: Requests[K]['_input']): Promise<Requests[K]['_output']>;
+}
+/**
+ * Authenticated socket — can make both authenticated `call()` and public `request()` calls.
+ * Parameterized by the app's call registry and (optionally) a separate request registry.
+ */
+export interface SocketLoggedIn<Calls extends FunctionRegistry, Requests extends RequestRegistry = Calls> {
+    type: 'loggedIn';
+    userId: string;
+    sessionId: string;
+    call<K extends keyof Calls>(name: K, input: Calls[K]['_input']): Promise<Calls[K]['_output']>;
+    request<K extends keyof Requests>(name: K, input: Requests[K]['_input']): Promise<Requests[K]['_output']>;
+}
+/**
+ * Union of logged-in and logged-out sockets.
+ */
+export type TypedAppSocket<Calls extends FunctionRegistry, Requests extends RequestRegistry = Calls> = SocketLoggedIn<Calls, Requests> | SocketLoggedOut<Requests>;
+//# sourceMappingURL=Socket.d.ts.map

package/dist/shared/Socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Socket.d.ts","sourceRoot":"","sources":["../../src/shared/Socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,eAAe;IAC/D,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,CAAC,SAAS,MAAM,QAAQ,EAC9B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAC7B,KAAK,SAAS,gBAAgB,EAC9B,QAAQ,SAAS,eAAe,GAAG,KAAK;IAExC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,CAAC,SAAS,MAAM,KAAK,EACxB,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GACxB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC,SAAS,MAAM,QAAQ,EAC9B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,KAAK,SAAS,gBAAgB,EAC9B,QAAQ,SAAS,eAAe,GAAG,KAAK,IACtC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC"}

package/dist/shared/Socket.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Socket.js.map

package/dist/shared/Socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Socket.js","sourceRoot":"","sources":["../../src/shared/Socket.ts"],"names":[],"mappings":""}

package/dist/shared/index.d.ts

@@ -0,0 +1,28 @@
+export * from './Api.js';
+export type { STTWord, TTSViseme, TTSVisemeName } from './Audio.js';
+export * from './DB.js';
+export * from './Errors.js';
+export * from './Router.js';
+export type { SocketLoggedIn, SocketLoggedOut, TypedAppSocket, } from './Socket.js';
+export declare const oneSecond = 1000;
+export declare const oneMinute: number;
+export declare const oneHour: number;
+export declare const oneDay: number;
+export declare const oneWeek: number;
+/** Returns true if value is neither null nor undefined */
+export declare function isDefined<T>(value: T | undefined | null): value is T;
+/** Removes null and undefined values from an array */
+export declare function compact<T>(arr: (T | null | undefined)[]): T[];
+/** Returns a debounced version of fn that fires after ms of silence */
+export declare function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(fn: T, ms: number): (...args: Parameters<T>) => void;
+/**
+ * Formats a Date or timestamp to a locale date string.
+ * Uses the user's system locale. For server-side, defaults to en-US.
+ */
+export declare function formatDate(date: Date | number, locale?: string): string;
+/**
+ * Returns a human-readable relative time string (e.g. "2 hours ago", "in 3 days").
+ * Uses the Intl.RelativeTimeFormat API.
+ */
+export declare function formatRelativeTime(date: Date | number, locale?: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpE,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,YAAY,EACV,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,eAAO,MAAM,SAAS,OAAQ,CAAC;AAC/B,eAAO,MAAM,SAAS,QAAiB,CAAC;AACxC,eAAO,MAAM,OAAO,QAAiB,CAAC;AACtC,eAAO,MAAM,MAAM,QAAe,CAAC;AACnC,eAAO,MAAM,OAAO,QAAa,CAAC;AAGlC,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED,sDAAsD;AACtD,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAE7D;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAC1E,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,GACT,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAMlC;AAGD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAOvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAaR"}

package/dist/shared/index.js

@@ -0,0 +1,61 @@
+export * from './Api.js';
+export * from './DB.js';
+export * from './Errors.js';
+export * from './Router.js';
+// ─── Time constants ────────────────────────────────────────────────────────
+export const oneSecond = 1_000;
+export const oneMinute = 60 * oneSecond;
+export const oneHour = 60 * oneMinute;
+export const oneDay = 24 * oneHour;
+export const oneWeek = 7 * oneDay;
+// ─── Type guards ───────────────────────────────────────────────────────────
+/** Returns true if value is neither null nor undefined */
+export function isDefined(value) {
+    return value !== undefined && value !== null;
+}
+/** Removes null and undefined values from an array */
+export function compact(arr) {
+    return arr.filter(isDefined);
+}
+/** Returns a debounced version of fn that fires after ms of silence */
+export function debounce(fn, ms) {
+    let timer;
+    return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), ms);
+    };
+}
+// ─── Date formatting ───────────────────────────────────────────────────────
+/**
+ * Formats a Date or timestamp to a locale date string.
+ * Uses the user's system locale. For server-side, defaults to en-US.
+ */
+export function formatDate(date, locale) {
+    const d = date instanceof Date ? date : new Date(date);
+    return d.toLocaleDateString(locale ?? 'en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+    });
+}
+/**
+ * Returns a human-readable relative time string (e.g. "2 hours ago", "in 3 days").
+ * Uses the Intl.RelativeTimeFormat API.
+ */
+export function formatRelativeTime(date, locale) {
+    const d = date instanceof Date ? date : new Date(date);
+    const diffMs = d.getTime() - Date.now();
+    const diffSec = Math.round(diffMs / 1000);
+    const diffMin = Math.round(diffMs / oneMinute);
+    const diffHour = Math.round(diffMs / oneHour);
+    const diffDay = Math.round(diffMs / oneDay);
+    const rtf = new Intl.RelativeTimeFormat(locale ?? 'en', { numeric: 'auto' });
+    if (Math.abs(diffSec) < 60)
+        return rtf.format(diffSec, 'second');
+    if (Math.abs(diffMin) < 60)
+        return rtf.format(diffMin, 'minute');
+    if (Math.abs(diffHour) < 24)
+        return rtf.format(diffHour, 'hour');
+    return rtf.format(diffDay, 'day');
+}
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"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"}

package/dist/webrtc/index.d.ts

@@ -0,0 +1,14 @@
+export interface WebRTCServerConfig {
+    /** Number of mediasoup workers to spawn. Defaults to CPU count. */
+    numWorkers?: number;
+    /** UDP/TCP port range for RTP. */
+    rtcMinPort?: number;
+    rtcMaxPort?: number;
+    /** Public IP or announced IP for ICE candidates. */
+    listenIp?: string;
+}
+export interface WebRTCServer {
+    close(): Promise<void>;
+}
+export declare function createWebRTCServer(config?: WebRTCServerConfig): Promise<WebRTCServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/webrtc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webrtc/index.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,YAAY,CAAC,CA6BvB"}

package/dist/webrtc/index.js

@@ -0,0 +1,24 @@
+// src/webrtc/index.ts
+// Optional WebRTC module — only import this file when WebRTC is needed.
+// Zero cost for applications that don't call createWebRTCServer().
+export async function createWebRTCServer(config = {}) {
+    // Dynamic import — mediasoup is not loaded unless this function is called.
+    // Add mediasoup to your project's dependencies to use this module:
+    //   npm install mediasoup
+    // @ts-ignore
+    const mediasoup = await import('mediasoup').catch(() => {
+        throw new Error('[WebRTC] mediasoup is not installed. Run: npm install mediasoup');
+    });
+    const { cpus } = await import('os');
+    const numWorkers = config.numWorkers ?? cpus().length;
+    const workers = await Promise.all(Array.from({ length: numWorkers }, () => mediasoup.createWorker({
+        rtcMinPort: config.rtcMinPort ?? 40000,
+        rtcMaxPort: config.rtcMaxPort ?? 49999,
+    })));
+    return {
+        async close() {
+            await Promise.all(workers.map((w) => w.close()));
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/webrtc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webrtc/index.ts"],"names":[],"mappings":"AAAA,sBAAsB;AACtB,wEAAwE;AACxE,mEAAmE;AAgBnE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAA6B,EAAE;IAE/B,2EAA2E;IAC3E,mEAAmE;IACnE,0BAA0B;IAC1B,aAAa;IACb,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACrD,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC,MAAM,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,CACtC,SAAS,CAAC,YAAY,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,KAAK;QACtC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,KAAK;KACvC,CAAC,CACH,CACF,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,KAAK;YACT,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,CAAC,CAA6B,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAC1D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "ugly-app",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/server/index.js",
+  "exports": {
+    ".": "./dist/server/index.js",
+    "./shared": "./dist/shared/index.js",
+    "./client": "./dist/client/index.js",
+    "./playwright": "./dist/playwright/index.js",
+    "./webrtc": {
+      "default": "./dist/webrtc/index.js"
+    }
+  },
+  "bin": {
+    "ugly-app": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@deepgram/sdk": "^5.0.0",
+    "@fal-ai/client": "^1.9.4",
+    "@google/generative-ai": "^0.24.1",
+    "bcrypt": "^6.0.0",
+    "commander": "^12.0.0",
+    "concurrently": "^9.0.0",
+    "cookie-parser": "^1.4.7",
+    "elevenlabs": "^1.59.0",
+    "express": "^4.21.1",
+    "fs-extra": "^11.0.0",
+    "groq-sdk": "^1.1.1",
+    "handlebars": "^4.7.8",
+    "ioredis": "^5.10.1",
+    "jose": "^6.0.13",
+    "lru-cache": "^11.0.0",
+    "mongodb": "^6.18.0",
+    "nanoid": "^5.1.5",
+    "nats": "^2.28.2",
+    "onnxruntime-node": "^1.23.0",
+    "openai": "^6.32.0",
+    "together-ai": "^0.13.0",
+    "ws": "^8.18.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/bcrypt": "^5.0.2",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^5.0.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.5.13",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^8.57.0",
+    "eslint-watch": "^7.0.0",
+    "html2canvas": "^1.4.1",
+    "jsdom": "^29.0.1",
+    "mongodb-memory-server": "^10.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@types/react": ">=18.0.0",
+    "html2canvas": ">=1.0.0",
+    "preact": "^10.29.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "html2canvas": {
+      "optional": true
+    },
+    "preact": {
+      "optional": true
+    },
+    "mediasoup": {
+      "optional": true
+    }
+  }
+}

package/templates/.claude/skills/assets.md

@@ -0,0 +1,39 @@
+# Managing Static Assets
+
+## Static assets (images, fonts, icons)
+Place in `client/assets/` — Vite serves them at `/assets/filename.ext`
+
+```tsx
+// Reference in React
+<img src="/assets/logo.png" alt="Logo" />
+```
+
+## Generating assets with imageGen
+```ts
+app.registerFunction('createAsset', async (ctx, input: { prompt: string; name: string }) => {
+  // Generate image
+  const tempUrl = await ctx.imageGen.generate(input.prompt)
+  // Extract temp key from URL
+  const tempKey = tempUrl.split('/temp/')[1]
+  // Promote to public assets
+  const publicUrl = await ctx.storage.moveToPublic(tempKey, `assets/${input.name}.png`)
+  return { publicUrl }
+})
+```
+
+## Recommended asset organization
+```
+client/assets/
+  icons/        — UI icons
+  backgrounds/  — Background images
+  generated/    — imageGen output (promoted to public bucket)
+public/         — Static files served at root (favicon.ico, robots.txt)
+```
+
+## Image sizes for flux schnell
+- Default: 1024×1024
+- Banners: use prompt guidance ("wide landscape format", "16:9 ratio")
+- Icons: generate at 1024×1024, scale down in CSS
+
+# Notes
+<!-- Claude: append observations here — record generated asset URLs -->

package/templates/.claude/skills/check-errors.md

@@ -0,0 +1,35 @@
+# Checking Error Logs
+
+## Query recent errors
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.errorLog.find({}, {message:1, stack:1, userId:1, created:1})
+  .sort({created:-1}).limit(20).pretty()
+"
+```
+
+## Group by message (find patterns)
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.errorLog.aggregate([
+  { \$group: { _id: '\$message', count: { \$sum: 1 }, last: { \$max: '\$created' } } },
+  { \$sort: { count: -1 } },
+  { \$limit: 10 }
+]).pretty()
+"
+```
+
+## Filter by level
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.errorLog.find({level:'error'}).sort({created:-1}).limit(10).pretty()
+"
+```
+
+## Tips
+- `source: 'server'` = server-side error, `source: 'browser'` = client-side
+- Check `stack` field for full stack trace
+- `userId: null` means unauthenticated user
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.claude/skills/check-feedback.md

@@ -0,0 +1,23 @@
+# Checking Feedback Logs
+
+## Query all feedback
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.feedbackLog.find().sort({created:-1}).limit(20).pretty()
+"
+```
+
+## Group by type
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.feedbackLog.aggregate([
+  { \$group: { _id: '\$type', count: { \$sum: 1 }, messages: { \$push: '\$message' } } }
+]).pretty()
+"
+```
+
+## Types: `bug`, `design`, `feature`
+## Screenshots available at `screenshotUrl` field
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.claude/skills/check-perf.md

@@ -0,0 +1,22 @@
+# Checking Performance Logs
+
+## Slowest operations
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.perfLog.aggregate([
+  { \$group: { _id: '\$operation', avgMs: { \$avg: '\$durationMs' }, maxMs: { \$max: '\$durationMs' }, count: { \$sum: 1 } } },
+  { \$sort: { avgMs: -1 } },
+  { \$limit: 10 }
+]).pretty()
+"
+```
+
+## Recent slow calls (>500ms)
+```bash
+mongosh "$MONGODB_URI" --eval "
+db.perfLog.find({durationMs:{\$gt:500}}).sort({created:-1}).limit(20).pretty()
+"
+```
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.claude/skills/create-test-users.md

@@ -0,0 +1,34 @@
+# Creating Test Users
+
+## Register a test user
+```bash
+curl -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test1@test.com","password":"testpass123"}'
+# Returns: {"token":"..."}
+```
+
+## Save token for use in tests
+```bash
+TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test1@test.com","password":"testpass123"}' | jq -r .token)
+echo $TOKEN
+```
+
+## Seed multiple users
+```bash
+for i in 1 2 3 4 5; do
+  curl -s -X POST http://localhost:3000/auth/register \
+    -H "Content-Type: application/json" \
+    -d "{\"email\":\"bot${i}@test.com\",\"password\":\"botpass123\"}"
+done
+```
+
+## Delete all test users
+```bash
+mongosh "$MONGODB_URI" --eval "db.user.deleteMany({email:/test\.com$/})"
+```
+
+# Notes
+<!-- Claude: append observations here — record which test users exist -->

package/templates/.claude/skills/extend-api.md

@@ -0,0 +1,37 @@
+# Extending the API
+
+Use this skill when adding new server functions or requests.
+
+## Steps
+
+1. **Add to `shared/api.ts`**
+```ts
+export const functions = defineFunctions({
+  // existing...
+  myNewFunction: {} as FunctionDef<{ param: string }, { result: string }>,
+})
+```
+
+2. **Register the handler in `server/index.ts`**
+```ts
+app.registerFunction('myNewFunction', async (ctx, input) => {
+  // input: { param: string } — fully typed
+  // ctx.userId, ctx.db, ctx.storage, ctx.textGen, ctx.imageGen, ctx.log
+  return { result: `Hello ${input.param}` }
+})
+```
+
+3. **Call from client**
+```ts
+const { result } = await socket.call('myNewFunction', { param: 'world' })
+```
+
+4. **For read-only operations**, use `defineRequests` + `app.registerRequest` + `socket.request()` instead.
+
+## Rules
+- Functions = mutating (writes, AI calls, side effects) → `call()`
+- Requests = read-only → `request()`
+- Both always have `ctx.userId: string`
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.claude/skills/fix-code.md

@@ -0,0 +1,5 @@
+Run type and lint checks, fix all issues.
+
+Run: `yarn build`
+
+This runs: tsc + vite build. Fix all TypeScript errors and lint warnings reported. Run again to confirm all issues are resolved.

package/templates/.claude/skills/fix-errors.md

@@ -0,0 +1,9 @@
+Fetch production errors and fix them.
+
+Run: `yarn error:server`
+
+This fetches recent errors from the production MongoDB errorLog collection. For each error:
+1. Find the relevant source file
+2. Understand the root cause
+3. Fix the code
+4. Run `yarn build` to verify the fix compiles

package/templates/.claude/skills/fix-feedback.md

@@ -0,0 +1,8 @@
+Fetch user feedback and fix reported issues.
+
+Run: `yarn feedback`
+
+This fetches recent user feedback from the production MongoDB feedbackLog collection. For each piece of feedback:
+1. Understand the user's issue or request
+2. Implement the fix or feature
+3. Run `yarn build` to verify it compiles

package/templates/.claude/skills/fix-perf.md

@@ -0,0 +1,8 @@
+Fetch performance issues and optimize slow paths.
+
+Run: `yarn perf:server`
+
+This fetches recent performance log entries from production. For each slow path:
+1. Find the source of the slowdown
+2. Optimize the code (avoid blocking operations, add caching, etc.)
+3. Run `yarn build` to verify

package/templates/.claude/skills/uploads.md

@@ -0,0 +1,38 @@
+# Uploading and Using Files
+
+## Client → upload to temp
+```ts
+// In a React component
+const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+  const file = e.target.files?.[0]
+  if (!file) return
+  const tempUrl = await socket.uploadFile(file, `uploads/${file.name}`)
+  // tempUrl is now usable — pass to a server function to promote
+}
+```
+
+## Server → promote temp to public
+```ts
+app.registerFunction('saveUpload', async (ctx, input: { tempKey: string; destKey: string }) => {
+  const publicUrl = await ctx.storage.moveToPublic(input.tempKey, input.destKey)
+  return { publicUrl }
+})
+```
+
+## Server → direct write to public (server-generated content only)
+```ts
+const url = await ctx.storage.put('public', 'assets/logo.png', buffer, 'image/png')
+```
+
+## Get a public URL without uploading
+```ts
+const url = ctx.storage.url('public', 'assets/logo.png')
+```
+
+## Rules
+- Only server can write to `public` bucket
+- Client uploads always go to `temp`
+- `temp` files expire — promote to `public` if keeping long-term
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.claude/skills/use-ai.md

@@ -0,0 +1,49 @@
+# Using Text and Image Generation
+
+## Text generation (llama4)
+```ts
+app.registerFunction('generateText', async (ctx, input: { prompt: string }) => {
+  const text = await ctx.textGen.generate([
+    { role: 'user', content: input.prompt }
+  ])
+  return { text }
+})
+```
+
+## With system prompt
+```ts
+const text = await ctx.textGen.generate(messages, {
+  systemPrompt: 'You are a helpful assistant.',
+  maxTokens: 512,
+  temperature: 0.7,
+})
+```
+
+## Image generation (flux schnell) — returns temp URL
+```ts
+app.registerFunction('generateImage', async (ctx, input: { prompt: string }) => {
+  const tempUrl = await ctx.imageGen.generate(input.prompt)
+  // Promote to public if keeping permanently:
+  // const publicUrl = await ctx.storage.moveToPublic('imagegen/xxx.png', 'assets/xxx.png')
+  return { url: tempUrl }
+})
+```
+
+## Spend limits
+- Budget set via `AI_MAX_SPEND_PER_HOUR` env var (default $1.00/hr)
+- Calls over budget are queued (max 5 min wait) then execute when window clears
+- If queue is full (100 calls), throws `SpendLimitError` — show user a friendly message
+
+## Check current spend
+```bash
+mongosh "$MONGODB_URI" --eval "
+const since = new Date(Date.now() - 3600000);
+db.aiSpend.aggregate([
+  { \$match: { created: { \$gte: since } } },
+  { \$group: { _id: '\$model', total: { \$sum: '\$costUsd' } } }
+]).pretty()
+"
+```
+
+# Notes
+<!-- Claude: append observations here -->

package/templates/.env.example

@@ -0,0 +1,49 @@
+# ── Core ────────────────────────────────────────────────────────────────────
+JWT_SECRET=CHANGE_ME_RUN_web_init_to_generate
+APP_DOMAIN=
+NODE_ENV=development
+PORT=3000
+
+# ── MongoDB ──────────────────────────────────────────────────────────────────
+# Leave blank to use local docker MongoDB
+# Get a free cluster at https://mongodb.com/atlas
+MONGODB_URI=
+
+# ── File Storage ─────────────────────────────────────────────────────────────
+# Leave blank to use local docker MinIO
+STORAGE_ACCOUNT_ID=
+STORAGE_ACCESS_KEY_ID=
+STORAGE_SECRET_ACCESS_KEY=
+STORAGE_PUBLIC_BUCKET=
+STORAGE_TEMP_BUCKET=
+STORAGE_PUBLIC_URL=
+STORAGE_TEMP_URL=
+
+# ── NATS ─────────────────────────────────────────────────────────────────────
+# Leave blank to use local docker NATS
+NATS_URL=
+NATS_CREDS=
+
+# ── Redis ────────────────────────────────────────────────────────────────────
+# Leave blank to use local docker Redis
+REDIS_URL=
+
+# ── AI Generation ────────────────────────────────────────────────────────────
+TOGETHER_API_KEY=
+AI_MAX_SPEND_PER_HOUR=1.00
+
+# ── Push Notifications ───────────────────────────────────────────────────────
+FIREBASE_PROJECT_ID=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_CLIENT_EMAIL=
+
+# ── Email ────────────────────────────────────────────────────────────────────
+MAILGUN_API_KEY=
+MAILGUN_DOMAIN=
+MAILGUN_FROM=
+
+# ── Deploy:multi only ────────────────────────────────────────────────────────
+IS_CLOCK_SERVER=
+
+# ── Maintain Bot ──────────────────────────────────────────────────────────────
+MAINTAIN_BOT_USER_ID=   # userId of maintain bot account (from web auth:create-account)