@tomorrowos/sdk 0.9.31 → 0.9.32

package/VERCEL_SETUP.md

@@ -5,8 +5,7 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.10` — pairs with `@tomorrowos/sdk` **0.9.31+** (`cms-starter-v0`: Fluid Publish + root Next Preview proxy).
-> **IRON RULE — configure immediately:** After the user answers **each** question, **finish that question’s configuration before asking the next**. Never batch “answer Q1–Q3 first, then configure everything.”
+> Protocol id: `vercel-setup/1.8` — pairs with `@tomorrowos/sdk` **0.9.32+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
 
 ## User trigger (copy-paste)
 
@@ -17,14 +16,12 @@ Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
 Ask only the questions listed in VERCEL_SETUP.md, in order. Do not use LLM_PROMPT.md or REPLIT_SETUP.md.
 Do not ask for OpenAI / Anthropic / any LLM API keys — TomorrowOS CMS setup does not require them.
 If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation).
-CRITICAL UX: After I answer each question, configure that step immediately (Env popup / brand.json write) BEFORE asking the next question. Do not wait until all three questions are answered.
-Question 2 options MUST be exactly: 1 Cloudinary (recommended), 2 Vercel Blob, 3 local disk — NEVER invent Supabase Storage or “disable media uploads”.
-Question 3 must offer Option A (website URL → brand.json) OR Option B (name + colours + background + logo) — NEVER ask only for display name.
-Prefer Supabase Session pooler URL or Neon pooled URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when a pooler URL is configured for production.
-Do not add CMS login/auth unless I explicitly ask. Do not skip steps.
-Use Next.js only as a v0/Preview shell with a reverse proxy; Production Publish must remain Fluid Function TomorrowOS (api/index.ts).
-Before claiming Publish works: Framework Other, Fluid on, GET /status JSON, GET / Control Panel, WebSocket upgrade 101 on / or /api.
-Do not put startCommand or processes in vercel.json. Use cms-starter-v0 layout. Do not create a second TomorrowOS in api/ws.ts.
+After all setup questions are answered (including Cloudinary or Vercel Blob Env Vars if you chose those), configure and deploy — minimal verification only (Control Panel at /). Prefer Supabase Session pooler URL or Neon pooled URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when a pooler URL is configured for production.
+Question 3 only updates brand.json from colours/logo/name (a website URL is brand reference only — do not add CMS login/auth unless the user explicitly asks). Do not skip steps.
+Use Next.js only as a v0/Preview shell with a reverse proxy; Production Publish must remain pure Node TomorrowOS.listen (not Next).
+Before claiming Publish works: Framework Preset must be Other/null (not Next.js), Fluid on, GET /status on the production URL must return JSON (not HTML), GET / must return the Control Panel, and WebSocket upgrade on / or /api must return 101 (not 200 HTML).
+Do not put startCommand or processes in vercel.json (v0 schema rejects them).
+Use cms-starter-v0 layout: cms-app.ts + api/index.ts (export default server) + cms-panel/ + rewrites to /api. Do not create a second TomorrowOS instance in api/ws.ts.
 ```
 
 Alternate triggers:
@@ -131,25 +128,15 @@ v0 Preview is often a **Next.js runtime** hardwired to `next dev`. A raw `tsx se
 
 ## Questionnaire scope (STRICT)
 
-Ask **only** these questions, in **this exact order**. After each answer, **configure that step immediately**, then proceed:
+Ask **only** these questions, in **this exact order**:
 
-| Step | Section | When done, before next question |
-|------|---------|----------------------------------|
-| 1 | **Question 1** — Database (Supabase → Neon → SQLite) | Collect DB URL / confirm SQLite → set Env Vars (`SUPABASE_URL` or `DATABASE_URL` + auto `TOMORROWOS_STORE` / `DATABASE_SSL`) |
-| 2 | **Question 2** — Media (**Cloudinary recommended** → Vercel Blob → local) | If Cloudinary/Blob: **open Env popup immediately** and save tokens before Q3 |
-| 3 | **Question 3** — Brand (`brand.json`: name, colours, background, logo, or website URL) | Write `brand.json` immediately, then run final deploy checklist |
+| Step | Section | When |
+|------|---------|------|
+| 1 | **Question 1** — Database (Supabase → Neon → SQLite) | Always |
+| 2 | **Question 2** — Media storage (Cloudinary → Vercel Blob → local) | Always (after Q1) |
+| 3 | **Question 3** — Brand / TomorrowOS look (`brand.json` only) | Always last |
 
-**Forbidden invented Question 2 options (never offer these):**
-
-- ❌ “Supabase Storage” / S3 bucket / `SUPABASE_SERVICE_ROLE_KEY` for media
-- ❌ “No media storage” / “disable uploads” / “remote URLs only” as a numbered choice
-- ❌ Replacing Cloudinary with Blob as the **recommended** option
-
-**Forbidden Question 3 shortcuts:**
-
-- ❌ Asking **only** for brand / product display name
-- ❌ Skipping background colour, primary colour, and logo when the user chose manual fields
-- ❌ Skipping Option A (website URL → infer full `brand.json`)
+**That is the complete list.** Do **not** ask how many screens / devices.
 
 **Forbidden extra questions (never ask, even if the user skips a step):**
 
@@ -173,25 +160,25 @@ Then ask **Question 1**.
 ## Hard rules
 
 1. **Ask only VERCEL_SETUP.md questions 1–3.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
-2. **Configure immediately after each answer.** Flow is `ask → user answers → configure that step → ask next`. Do **not** collect all answers then configure in a batch at the end.
-3. **Cloudinary:** as soon as the user picks Cloudinary, open **one** Vercel Env configuration popup / form with **all** Cloudinary fields together (cloud name + API key + API secret). Do **not** quiz one credential at a time in chat. Do **not** skip Cloudinary in favor of inventing Supabase Storage.
-4. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
-5. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
-6. **Always prefer pooled connection strings** (Supabase Session pooler port **6543**; Neon pooled host). Direct `:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
-7. **Prefer `npx @tomorrowos/sdk init --hosting v0`** (template `cms-starter-v0`). For Replit/Railway use default `init` (`cms-starter`). Do not rebuild pairing / WebSocket / playlist APIs.
-8. **Never commit secrets.** Use Vercel Environment Variables (+ optional non-secret flags in committed `.env.example`).
-9. **Skip Replit-only files:** do **not** create `.replit`, `.replit-artifact`, or Replit `deploymentTarget`.
-10. **SQLite is not a production store on Vercel.** Offer it only as option **3** after explicit warning. Keep `sqlitePath` as local-dev fallback in `createTomorrowOSStore`.
-11. **Enable Fluid compute** for Production WebSockets ([docs](https://vercel.com/docs/functions/websockets)). Confirm Project settings after scaffold.
-12. **Production:** one Vercel Function exports `http.Server` from `TomorrowOS.listen` (`api/index.ts`). **Do not** make `next start` the Production entrypoint. **Do not** spin a second TomorrowOS in `api/ws.ts`.
-13. After Q1–Q3 each configured: **install → deploy → minimal verify** (Control Panel + WS 101). Do not run a long test suite.
+2. **Cloudinary:** open **one** Vercel Env configuration popup / form with **all** Cloudinary fields together (cloud name + API key + API secret). Do **not** quiz the user one credential at a time in chat.
+3. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
+4. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
+5. **Always prefer pooled connection strings** (Supabase Session pooler port **6543**; Neon pooled host). Direct `:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
+6. **Prefer `npx @tomorrowos/sdk init --hosting v0`** (template `cms-starter-v0`: `cms-app.ts`, `api/index.ts`, `cms-panel/`, Fluid + rewrites). For Replit/Railway use default `init` (`cms-starter`). Do not rebuild pairing / WebSocket / playlist APIs.
+7. **Never commit secrets.** Use Vercel Environment Variables (+ optional non-secret flags in committed `.env.example`).
+8. **Skip Replit-only files:** do **not** create `.replit`, `.replit-artifact`, or Replit `deploymentTarget`.
+9. **SQLite is not a production store on Vercel.** Offer it only as option **3** after explicit warning. Keep `sqlitePath` as local-dev fallback in `createTomorrowOSStore`.
+10. **Enable Fluid compute** for Production WebSockets ([docs](https://vercel.com/docs/functions/websockets)). Confirm Project settings after scaffold.
+11. **Production:** one Vercel Function exports `http.Server` from `TomorrowOS.listen` (`api/index.ts`). **Do not** make `next start` the Production entrypoint. **Do not** spin a second TomorrowOS in `api/ws.ts`.
+12. **Preview:** if the environment is v0 / Next-hardwired, install the Next reverse-proxy shell (see **Preview adapter**). Do not leave Preview broken.
+13. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/` + WS 101). Do not run a long test suite.
 14. **No inventing CMS login.** A branding URL never means “build auth.” Only add login if the user **explicitly** requests it.
 15. **Skip ≠ invent.** If the user skips media choice or a credential, do not replace it with OpenAI/auth/login questions. Stay on Q1–Q3 only.
 16. **Neon / Supabase helpers are agent-owned.** After the user pastes the DB URL, **you** set `TOMORROWOS_STORE` and `DATABASE_SSL` automatically — **do not** ask the user to fill those two.
 17. **Publish gate:** do not mark setup complete while Production returns `404: NOT_FOUND`, `/status` returns HTML, **or** WebSocket upgrade returns 200 HTML instead of 101.
 18. **Scheme A is doc-driven:** Production = Fluid Function + `export default server` per Vercel WebSockets docs — Replit starter stays unchanged.
 
-**Question order:** Q1 → **configure Q1** → Q2 → **configure Q2** → Q3 → **write brand.json** → deploy checklist.
+**Question order:** Q1 → Q2 → Q3 → execution checklist.
 
 ---
 
@@ -205,10 +192,10 @@ Then ask **Question 1**.
 
 | Layer | Preview (v0) | Publish (Production) |
 |-------|----------------|----------------------|
-| Host | **Root Next** `app/[[...slug]]/route.ts` proxies → TomorrowOS `:3001` | **Vercel Function** `api/index.ts` → `export default server` |
-| Static UI | Proxied from TomorrowOS `cms-panel/` | Served by **`staticRoot`** inside `listen()` |
-| WebSocket | Optional / may fail in Preview | **Required** — Fluid Function upgrade |
-| Next files | **Root** `app/` + `next.config.mjs` (required for v0) | Ignored when Framework = Other + no-op `build` + Function entry |
+| Host | Next.js shell + HTTP proxy | **Vercel Function** `api/index.ts` → `export default server` |
+| Static UI | Proxied from TomorrowOS | Served by **`staticRoot`** (`cms-panel/`) inside `listen()` — **not** Vercel Output Directory |
+| WebSocket | Optional / may fail in Preview | **Required** — Fluid Function upgrade (`wss://` → `/` rewritten to `/api`, or direct `/api`) |
+| Next files | Allowed under `preview/` | **Must not** live at project root |
 
 **Root cause of “Control Panel works, TV cannot connect”:** HTTP can be served without WebSocket upgrades. Classic root-only `server.ts` / plain serverless handlers often return **200 HTML** on `Upgrade` instead of **101**. Official pattern is a Function that exports `http.Server` with `ws` attached ([docs](https://vercel.com/docs/functions/websockets)).
 
@@ -217,41 +204,48 @@ Then ask **Question 1**.
 **Production (Vercel / v0 starter):**
 
 ```
-cms-app.ts
-api/index.ts       ← Publish Function
-server.ts          ← local listen entry
-app/               ← Preview ONLY (Next proxy catch-all)
-  layout.tsx
-  [[...slug]]/route.ts
-next.config.mjs    ← Preview only
-vercel.json
-cms-panel/
+cms-app.ts         ← shared TomorrowOS.listen + export const server
+api/index.ts       ← export { server as default } from "../cms-app.js"
+server.ts          ← local/Preview: same default export (npm start / internal port)
+vercel.json        ← fluid + rewrites + functions.maxDuration
+package.json
 brand.json
-package.json       ← "dev": "npm run dev:preview"
+cms-panel/         ← CMS static UI (NOT named public/ — avoids static-output trap)
+preview/           ← Next proxy for v0 Preview only
+```
+
+**Preview only — keep ALL Next under `preview/`:**
+
+```
+preview/
+  next.config.mjs
+  app/
+  …
 ```
 
 **Do NOT:**
 
-- ❌ Add `app/page.tsx` that returns null (v0 shows “Your v0 generation will show here”)
+- ❌ Leave `next.config.mjs` + `app/` at project root
 - ❌ Set Output Directory to `public`, `cms-panel`, or `.`
-- ❌ Create a **second** TomorrowOS instance in `api/ws.ts`
-- ❌ Use `next build` / `next start` for Production
-- ❌ Put `startCommand` / `processes` in `vercel.json`
+- ❌ Create a **second** TomorrowOS instance in `api/ws.ts` (separate isolate = broken pairing memory)
+- ❌ Use `(req, res) =>` serverless handlers that drop `upgrade`
+- ❌ Put `startCommand` / `processes` in `vercel.json` (v0 schema rejects them)
 
 **`package.json` scripts:**
 
 ```json
 {
   "scripts": {
-    "dev": "npm run dev:preview",
+    "dev": "tsx watch server.ts",
     "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
     "dev:tomorrowos": "cross-env TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
-    "dev:next": "next dev -p 3000",
+    "dev:next": "cd preview && next dev -p 3000",
     "start": "tsx server.ts",
     "build": "node -e \"process.exit(0)\""
   }
 }
 ```
+
 - **Local / Railway-style:** `npm start` → `tsx server.ts` → SDK calls `server.listen` (no `VERCEL` env).
 - **Vercel Production:** Function loads `api/index.ts`; SDK skips `listen` when `process.env.VERCEL` is set and Vercel owns the socket.
 
@@ -272,7 +266,7 @@ const server = tomorrowos.listen({
 export { server, tomorrowos };
 ```
 
-SDK behaviour (0.9.30+):
+SDK behaviour (0.9.32+):
 
 - Accepts WebSocket upgrades on `/`, `/api`, `/api/ws` (players may use either)
 - When `VERCEL` is set: **`autoListen` defaults to false** — do not bind a port yourself
@@ -374,7 +368,7 @@ If (1)+(2) pass but (3) fails → Function is serving HTTP only. Re-check Fluid,
 
 - Serve TomorrowOS via **Vercel Function** `api/index.ts` → `export default server` (Fluid + WebSockets).
 - Keep root **`server.ts`** for **local** `npm start` / Preview internal port only (same `cms-app.ts`).
-- Keep **`@tomorrowos/sdk`** (0.9.30+) and put **`tsx` in `dependencies`** for local start.
+- Keep **`@tomorrowos/sdk`** (0.9.32+) and put **`tsx` in `dependencies`** for local start.
 - Node **20+**.
 - **Do not** replace the SDK with a hand-rolled server that drops WebSocket upgrades.
 - **Forbidden as the Production CMS:** `next start`, static export only, or a bare `(req,res)` handler without `http.Server` + `ws`.
@@ -384,10 +378,10 @@ If (1)+(2) pass but (3) fails → Function is serving HTTP only. Re-check Fluid,
 ```json
 {
   "scripts": {
-    "dev": "npm run dev:preview",
+    "dev": "tsx watch server.ts",
     "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
     "dev:tomorrowos": "cross-env PORT=3001 TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
-    "dev:next": "next dev -p 3000",
+    "dev:next": "cd preview && next dev -p 3000",
     "start": "tsx server.ts",
     "build": "node -e \"process.exit(0)\""
   }
@@ -396,10 +390,10 @@ If (1)+(2) pass but (3) fails → Function is serving HTTP only. Re-check Fluid,
 
 Adapt script names / process runners as needed. **Invariant:**
 
-- **Local / v0 Preview `npm run dev`** = TomorrowOS `:3001` + Next `:3000` proxy.
+- **Local `npm start`** = TomorrowOS Node with `server.listen`.
 - **Vercel Production** = Function `api/index.ts` (SDK `autoListen=false` when `VERCEL` is set).
 - **`build`** = no-op exit 0 (never `next build` for Production).
-- **Do not** ship an empty `app/page.tsx` (v0 placeholder).
+- **Preview / v0** = Next on public port + TomorrowOS on internal port + proxy.
 
 ### Minimal dependencies (Production)
 
@@ -477,37 +471,32 @@ export default server;
 
 Load env with `dotenv` for local/`vercel dev`. On production Deploy, Vercel injects Environment Variables natively.
 
-### Preview adapter (v0 / Next reverse proxy) — required for Preview UI
+### Preview adapter (v0 / Next reverse proxy) — required when Preview is Next-hardwired
 
-v0 Preview is hardwired to **root** Next (`app/`, `next.config.mjs`, `next dev`). An empty `app/page.tsx` (or returning `null`) produces **“Your v0 generation will show here”** and never shows the Control Panel.
+Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs “listening”). Then:
 
-**Required layout (cms-starter-v0):**
+1. Keep a **minimal** Next app **isolated when possible** (e.g. under `preview/`) so Production Framework detection does not latch onto root `next.config.*`.
+2. TomorrowOS listens on **`127.0.0.1:TOMORROWOS_INTERNAL_PORT`** (default **3001**).
+3. Add a **catch-all** Next route (or middleware) that proxies HTTP to TomorrowOS:
 
-```
-app/
-  layout.tsx                 ← minimal shell
-  [[...slug]]/route.ts       ← proxy ALL methods to http://127.0.0.1:3001
-next.config.mjs              ← Preview only (no empty page.tsx)
-cms-app.ts / server.ts       ← TomorrowOS on TOMORROWOS_INTERNAL_PORT=3001
-api/index.ts                 ← Production Function only (Publish unchanged)
+```ts
+// Example: preview app proxy handler
+// Forward method, headers, and body to http://127.0.0.1:3001/<path>
+// Return the upstream status, headers, and body to the browser.
 ```
 
-**Agent must:**
+Preferred UX: proxy **`/`** itself (rewrites) so the Preview URL shows the Control Panel at `/`, not only under `/api/...`.
 
-1. Put the Next proxy at **project root** `app/` (v0 does not reliably use `preview/` alone).
-2. **Do not** add `app/page.tsx` that returns null / placeholder copy.
-3. Implement `app/[[...slug]]/route.ts` that forwards method, headers, and body to `TOMORROWOS_INTERNAL_URL` (default `http://127.0.0.1:3001`) and returns upstream status/body. On connection failure, return a short HTML 502 explaining `npm run dev`.
-4. Set `"dev": "npm run dev:preview"` so the default v0/dev command starts **both** TomorrowOS (:3001) and Next (:3000).
-5. Keep Production on Fluid Function (`api/index.ts`, `framework: null`, no-op `build`). **Do not** make `next start` / `next build` the Publish path.
-6. Document: **Preview = Next proxy + TomorrowOS :3001; Publish = api/index.ts Fluid (unchanged).**
+4. Start **both** processes for Preview (`dev:preview` pattern above).
+5. Document in the final summary: **Preview = Next shell + proxy; Publish = Node only.**
 
 **Forbidden:**
 
-- Empty v0 placeholder page as the Preview UX
-- Making Next the Production CMS
-- Deleting `api/index.ts` / `cms-app.ts` to “fix” Preview
-- Claiming Preview complete while the iframe still says “Your v0 generation will show here”
-- Claiming setup complete if Production entrypoint is still `next start` or `GET /` is `404: NOT_FOUND`
+- Making Next the Production CMS or the only server after Publish.
+- Deleting TomorrowOS `server.ts` because Preview needed Next.
+- Claiming setup complete if Production entrypoint is still `next start`.
+- Claiming setup complete if Production `GET /` is `404: NOT_FOUND`.
+- Creating root `api/index.*` + `routes` catch-all that exports a raw `http.Server` “to fix 404”.
 
 ### `vercel.json` (Production — explicit Node, not Next)
 
@@ -565,8 +554,7 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 ## Question 1 — Database (always)
 
-> **Do not** ask screen counts. Present all three options; recommend **Supabase** for Vercel fleets.  
-> **After the user picks 1 / 2 / 3:** finish Step B/C/D (collect URL or confirm SQLite + set Env Vars) **before** asking Question 2.
+> **Do not** ask screen counts. Present all three options; recommend **Supabase** for Vercel fleets.
 
 ### Step A — Ask storage choice
 
@@ -584,8 +572,6 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 ### Step B — If **1 / Supabase**
 
-**Immediately** (same turn as acknowledging their choice — do not ask Q2 yet) ask for the connection string:
-
 **Ask exactly (connection string only):**
 
 > Paste your Supabase Postgres connection string. I will store it as **`SUPABASE_URL`**.
@@ -598,20 +584,17 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 **You must then (automatic — do NOT ask the user to type these):**
 
-1. Set Vercel Env Vars **now** (open Env UI if available):
+1. Set Vercel Env Vars:
    - `SUPABASE_URL=<user pooler string>`
    - `TOMORROWOS_STORE=supabase` ← **agent sets this**
    - `DATABASE_SSL=true` ← **agent sets this** (unless user already said SSL is off)
-2. Wire store in `cms-app.ts` / `server.ts` as in **Runtime & Vercel deploy rules**.
+2. Wire `server.ts` as in **Runtime & Vercel deploy rules**.
 3. Optional committed `.env.example` with **placeholders only**.
 4. **Do not** commit the real connection string.
 5. **Do not** open a second form asking for `TOMORROWOS_STORE` or `DATABASE_SSL`.
-6. **Only after Env Vars are saved** → ask **Question 2**.
 
 ### Step C — If **2 / Neon**
 
-**Immediately** ask for the connection string (do not ask Q2 yet):
-
 **Ask exactly (connection string only):**
 
 > Paste your **Neon pooled** Postgres connection string. I will store it as **`DATABASE_URL`**.
@@ -622,15 +605,14 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 **You must then (automatic — do NOT ask the user to type these):**
 
-1. Set Vercel Env Vars **now**:
+1. Set Vercel Env Vars:
    - `DATABASE_URL=<user pooled string>`
    - `TOMORROWOS_STORE=postgres` ← **agent sets this**
    - `DATABASE_SSL=true` ← **agent sets this**
-2. Wire `createTomorrowOSStore` for Postgres.
+2. Wire `server.ts` — `createTomorrowOSStore` uses `PostgresStore` for `postgres` / `supabase` drivers.
 3. **Do not** commit the real connection string.
-4. **Do not** ask the user to fill `TOMORROWOS_STORE` or `DATABASE_SSL`.
+4. **Do not** ask the user to fill `TOMORROWOS_STORE` or `DATABASE_SSL` in chat or in an Env popup. Those are derived from choosing Neon.
 5. If you see `ENETUNREACH` on `:5432`, switch to Neon’s **pooled** URL.
-6. **Only after Env Vars are saved** → ask **Question 2**.
 
 ### Step D — If **3 / SQLite**
 
@@ -643,9 +625,8 @@ Only proceed after the user explicitly confirms.
 **You must then (automatic):**
 
 1. Set `TOMORROWOS_STORE=sqlite` yourself (do not ask the user to type it).
-2. Keep `sqlitePath` in `cms-app.ts` for `data/tomorrowos.db`.
+2. Keep `sqlitePath` in `server.ts` for `data/tomorrowos.db`.
 3. Warn again in the final summary that they should move to Supabase or Neon for real devices.
-4. **Then** ask **Question 2**.
 
 **Later in Question 3:** set `cms.hostingTarget` to **`"vercel"`** (all Q1 branches).
 
@@ -654,26 +635,25 @@ Only proceed after the user explicitly confirms.
 ## Question 2 — Media storage
 
 > **This question is only about media files (images/videos).**  
-> It is **not** about OpenAI, AI pairing, or LLM keys. If you are about to ask for an `sk-` key, **stop** — you are off-protocol.  
-> **Copy the three options below verbatim.** Do **not** substitute Supabase Storage, “disable uploads”, or make Vercel Blob the recommended option.
+> It is **not** about OpenAI, AI pairing, or LLM keys. If you are about to ask for an `sk-` key, **stop** — you are off-protocol.
 
 ### Step A — Ask storage choice
 
-**Ask exactly (wording must match):**
+**Ask exactly:**
 
 > How should playlist media (images/videos) be stored?
 >
-> **1. Cloudinary (recommended)** — durable public HTTPS URLs (`https://res.cloudinary.com/...`). Works out of the box with `@tomorrowos/sdk` auto-detection. **Prefer this on Vercel.**
+> **1. Cloudinary (recommended)** — durable public HTTPS URLs (`https://res.cloudinary.com/...`). Works out of the box with `@tomorrowos/sdk` auto-detection.
 >
-> **2. Vercel Blob** — Vercel-native object storage; durable `https://*.public.blob.vercel-storage.com/...` URLs. Use when you want media on the same Vercel project without a Cloudinary account.
+> **2. Vercel Blob** — Vercel-native object storage; durable `https://*.public.blob.vercel-storage.com/...` URLs. Good when you want media on the same Vercel project without a Cloudinary account.
 >
-> **3. Local disk only** — `cms-panel/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
+> **3. Local disk only** — `public/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
 >
 > Reply with **1**, **2**, or **3** (or “Cloudinary” / “Vercel Blob” / “local”).
 
-### Step B — If **1 / Cloudinary** (configure **immediately** — one Env popup)
+### Step B — If **1 / Cloudinary** (same Question 2 — **one Env popup**)
 
-> **Critical UX rule:** As soon as the user chooses Cloudinary, **immediately** open the **Vercel Environment Variables configuration popup / form** with **all Cloudinary fields in one UI**. Do **not** ask Q3 first. Do **not** ask for cloud name, then key, then secret in separate chat messages.
+> **Critical UX rule:** Immediately open the **Vercel Environment Variables configuration popup / form** with **all Cloudinary fields in one UI**. Do **not** ask for cloud name, then key, then secret in separate chat messages.
 
 **Preferred:** Vercel Env Vars UI (or Agent secrets form) with these fields together:
 
@@ -699,13 +679,10 @@ Only proceed after the user explicitly confirms.
 2. **Do not** invent placeholders.
 3. **Do not** proceed to Question 3 until all three required vars exist.
 4. **Do not** run a formal Cloudinary upload test unless the user asks.
-5. **Only after Cloudinary Env Vars are saved** → ask **Question 3**.
 
 The SDK auto-detects these env vars.
 
-### Step C — If **2 / Vercel Blob** (configure **immediately**)
-
-**Immediately** (do not ask Q3 yet):
+### Step C — If **2 / Vercel Blob** (same Question 2)
 
 **Ask exactly:**
 
@@ -733,51 +710,46 @@ import { put } from "@vercel/blob";
 
 4. Warn: until the project’s Blob bridge is wired, Control Panel **Media** status may show local/ephemeral — verify uploads return `https://*.blob.vercel-storage.com/...` before calling setup complete.
 5. Do **not** proceed to Question 3 until `BLOB_READ_WRITE_TOKEN` exists (or Blob is linked and token is confirmed in the Vercel dashboard).
-6. **Only then** → ask **Question 3**.
 
 ### Step D — If **3 / local uploads**
 
-1. Ensure `cms-panel/uploads` exists (or `public/uploads` on Replit-style starters).
-2. Warn clearly: files may vanish on redeploy; players need stable HTTPS URLs — **Cloudinary is strongly preferred** on Vercel.
-3. **Then** ask **Question 3**.
+1. `mkdir -p public/uploads`
+2. Warn clearly: files may vanish on redeploy; players need stable HTTPS URLs — Cloudinary or Vercel Blob is strongly preferred for Vercel.
 
 ---
 
 ## Question 3 — Brand (`brand.json` only)
 
-> Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or store wiring beyond what Q1–Q2 already required.
+> Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or `server.ts` store wiring beyond what Q1–Q2 already required.
 >
 > **IRON RULE — website URL ≠ build a website / login / auth CMS.**  
-> If the user pastes a URL (or says “make it look like this site”), that input is **reference material for `brand.json` only** (name, colours, fonts, logo, tagline, **background**).  
+> If the user pastes a URL (or says “make it look like this site”), that input is **reference material for `brand.json` only** (name, colours, fonts, logo, tagline).  
 > **Do not** scaffold a login page, signup, OAuth, gated dashboard, or copy the reference site’s IA/pages — **unless the user explicitly asks for CMS login / auth**.  
-> Default TomorrowOS Control Panel has **no login**. Keep it that way.  
-> **Never ask only for a display name.** Always offer Option A (URL) **or** the full Option B field list below.
+> Default TomorrowOS Control Panel has **no login**. Keep it that way.
 
 ### Step A — Ask branding input
 
 **Ask exactly:**
 
-> Let’s brand your TomorrowOS experience. Choose **one**:
+> Let’s brand your TomorrowOS experience. You can answer in either way:
 >
-> **Option A — Website URL (recommended if you have a site)**  
-> Paste **one public website URL**. I will use it **only** to fill **`brand.json`**: product name, tagline, primary / secondary / **background** / text colours, fonts, and logo.  
-> I will **not** rebuild that website or add login — unless you explicitly ask for login/auth later.
+> **Option A — Website URL only (brand reference)**  
+> Paste **one public website URL**. I will use it **only** to infer colours, fonts, name, tagline, and logo for **`brand.json`**.  
+> I will **not** rebuild that website, add a login page, or change Control Panel features — unless you explicitly ask for login/auth later.
 >
-> **Option B — Manual brand fields**  
-> Send as many of these as you can (name + at least one colour + logo is ideal):
-> 1. **Product / venue name** (required)
+> **Option B — Manual fields**  
+> Provide:
+> 1. **Product / venue name**
 > 2. **Tagline** (optional)
 > 3. **Primary colour** (hex, e.g. `#FF8A3D`)
-> 4. **Background colour** (hex — page / panel background)
+> 4. **Background colour** (hex, optional — default `#FAFAF9`)
 > 5. **Text colour** (hex, optional — default `#0A0908`)
 > 6. **Secondary / accent colour** (hex, optional)
-> 7. **Logo** — upload SVG/PNG into the project, or a public image URL I can fetch into `./assets/`
->
-> Reply with a URL **or** the manual fields. Do not send only a name with no colours/logo unless you want defaults (I will confirm defaults before writing).
+> 7. **Logo** — upload SVG/PNG into the project, or a URL I can fetch into `./assets/`
 
 ### Step B — If the user gives **only a website URL** (Option A)
 
-**You must (immediately — do not defer brand write to “end of setup”):**
+**You must:**
 
 1. **Fetch and inspect** the page (HTTP GET the URL; follow one redirect if needed). Do not invent colours.
 2. **Write / update `brand.json` only** from what you infer. Touch nothing else for this step (no new pages, no auth, no Next marketing site, no login UI).
@@ -792,8 +764,7 @@ import { put } from "@vercel/blob";
    - **Logo:** prefer `og:image`, then `link[rel="icon"]` / apple-touch-icon, then header `<img>` logo. Download into `./assets/logo.png` or `./assets/logo.svg` and set `logoPath` accordingly. If only favicon exists, use it and note size in the summary.
 4. **Contrast check:** if background is dark, set `activationScreen.theme` to `"dark"` and add `logoPathOnDark` when a light logo variant exists.
 5. **Infer `cms.useCase`** from page content when obvious (restaurant / retail / corporate / etc.); otherwise `"other"`.
-6. **Show a one-line summary** to the user (name + primary + background hex + logo path) while writing the file — do not ask a second branding question unless fetch failed.
-7. **Then** run the final deploy checklist (seed layout already done / Publish).
+6. **Show a one-line summary** to the user (name + primary hex + logo path) before or while writing the file — do not ask a second branding question unless fetch failed.
 7. If the URL is unreachable, blocked, or has no usable styles, say so and fall back to **Option B** manual questions for missing fields only.
 
 **Explicitly forbidden when the user only gave a URL (no login request):**
@@ -838,31 +809,27 @@ Validate mentally against `brand.schema.json`. Minimum:
 
 Always set **`cms.hostingTarget`: `"vercel"`** without asking. Default `expectedScreens` to `5` unless the user already volunteered a number. Set `cmsEndpoint` only if they already know the public `https://…vercel.app` URL; otherwise tell them to pair TVs with the **Published** HTTPS origin (player maps `https://` → `wss://`).
 
-**If Option B (manual):** map every field the user provided into `brand.json` **immediately** (`name`, `primaryColor`, `backgroundColor`, `textColor`, `secondaryColor`, `logoPath`, `tagline`). If they only sent a name, ask once for missing **background**, **primary colour**, and **logo** — do not proceed to deploy with name-only branding without confirming defaults.
-
 ---
 
-## After Q1–Q3 configured — final deploy checklist
-
-> Env Vars for Q1/Q2 and `brand.json` for Q3 should **already be done** during each question. This section is **scaffold + Publish verify only** — do not re-ask for Cloudinary/DB secrets here.
+## After all answers — execution checklist
 
-### A. Seed the project (do this early if the repo is empty — before or during Q1)
+### A. Seed the project
 
 ```bash
-npx @tomorrowos/sdk@latest init . --hosting v0
+npx @tomorrowos/sdk@latest init .
 # If not empty and user confirms starter overwrite:
-# npx @tomorrowos/sdk@latest init . --hosting v0 --force
+# npx @tomorrowos/sdk@latest init . --force
 ```
 
 Then (**Scheme A — mandatory for Publish**):
 
-1. Ensure **`cms-app.ts`** + **`api/index.ts`** (`export default server`) + **`cms-panel/`**.
-2. If Preview needs Next: keep Next under **`preview/`** only.
-3. Write `vercel.json` per **Scheme A3** (`fluid`, rewrites, `maxDuration: 300` — **no** `startCommand`).
-4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory empty, Fluid on).
-5. Do **not** add a second TomorrowOS in `api/ws.ts`.
+1. Keep **`server.ts`** at **project root** with top-level `listen()` + `export default server`.
+2. If Preview needs Next: **move** `next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts` into **`preview/`** — remove them from root so Production is not mistaken for Next/static.
+3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, no-op `buildCommand` — **no** `startCommand`).
+4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory empty, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js.
+5. Do **not** add root `api/` catch-all for raw `http.Server`.
 6. Do **not** add `.replit*`.
-7. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge (should already be started in Q2).
+7. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
 
 ### B. Environment Variables (Vercel dashboard + local)
 
@@ -945,7 +912,7 @@ Tell the user:
 | Separate `api/ws.ts` with a second `new TomorrowOS` | Two isolates — pairing memory split | **One** Function only (`api/index.ts` → shared `cms-app.ts`) |
 | `vercel inspect` shows Output = `public if it exists` | Framework=Other static default | Force Output Directory **empty**; use `cms-panel/`; Path B redeploy |
 | Build runs `next build` / missing routes-manifest | Next auto-detected from root `next.config` / `app/` | Move Next to `preview/`; Framework null/Other; `build` = no-op |
-| Preview blank / “Your v0 generation will show here” | Empty `app/page.tsx` or Next not proxying / TomorrowOS not on :3001 | Root `app/[[...slug]]/route.ts` proxy; `"dev": "npm run dev:preview"`; no null page |
+| Preview blank but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy → internal TomorrowOS port |
 | Preview works, Publish broken / Next-only | Production still on Next | Switch Production to Fluid Function `api/index.ts` |
 | `ENETUNREACH` / IPv6 / `:5432` | Direct Postgres URL | Use **pooled** URL (Supabase `:6543` or Neon pooler) |
 | Control Panel OK, devices never stay paired after restart | SQLite / ephemeral disk | Use Supabase or Neon |
@@ -954,9 +921,7 @@ Tell the user:
 | WebSocket fails on Publish | Fluid off / static-only / Next as Production / no Function WS | Enable Fluid; Scheme A; test 101 upgrade |
 | Devices fail only on Preview | Next proxy cannot upgrade `wss` | Expected — pair on Publish URL |
 | Agent asked user to fill `TOMORROWOS_STORE` / `DATABASE_SSL` | Off-protocol | Agent must auto-set those after Neon/Supabase choice |
-| Agent offered Supabase Storage / “disable media” for Q2 | Invented options | Re-ask Q2 verbatim: Cloudinary → Blob → local |
-| Agent asked only brand display name for Q3 | Shortcut | Re-ask Q3 Option A (URL) or full Option B (colours + background + logo) |
-| Agent batched all Q&A then configured Env at the end | Off-protocol UX | Stop; configure the current question’s Env before asking the next |
+| Agent asked Cloudinary key/secret in three chat turns | Off-protocol | Use **one Env popup** with all Cloudinary fields |
 | Agent asked for OpenAI / `sk-` key during setup | Hallucinated “AI pairing” requirement | **Refuse.** TomorrowOS does not need LLM keys. Return to Q2 media choices only |
 | Agent built a login page after user pasted a URL | Misread brand reference as product scope | Remove login; keep starter Control Panel; apply URL only to `brand.json` |
 | Secrets in git | Mistake | Rotate keys; move to Vercel Env Vars |
@@ -972,11 +937,10 @@ Tell the user:
 | Deploy config | `.replit`, artifact `kind=web` | `vercel.json` + Fluid; **Framework = Other**; **no** `.replit` |
 | `hostingTarget` | `"here"` | `"vercel"` |
 | Database | Supabase (primary) | Supabase **or Neon** (pooled); SQLite demo only |
-| Media | Cloudinary or Replit Object Storage | **Cloudinary (recommended)** or Vercel Blob (not Supabase Storage) |
+| Media | Cloudinary or Replit Object Storage | Cloudinary **or Vercel Blob** |
 | Preview | Replit Preview / Autoscale Node | **Next shell + proxy** when v0 hardwires Next |
-| Publish | Long-lived Node | **Fluid Function + WebSockets** (not Next); gate on `/status` JSON + WS 101 |
-| Brand from URL | Not in Replit protocol | **Option A** — full **`brand.json`** (name/colours/background/logo); never invent login |
-| Configure timing | Per Replit protocol | **After each question immediately** (never batch Q1–Q3 then configure) |
+| Publish | Long-lived Node | **Node `TomorrowOS.listen` only** (not Next); gate on no `404 NOT_FOUND` |
+| Brand from URL | Not in Replit protocol | **Option A** — infer **`brand.json` only**; never invent login |
 
 ---