@tomorrowos/sdk 0.9.29 → 0.9.31

package/VERCEL_SETUP.md

@@ -5,7 +5,8 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.7` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> 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.”
 
 ## User trigger (copy-paste)
 
@@ -16,11 +17,14 @@ 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).
-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), package.json `start` must run TomorrowOS Node, GET /status on the production URL must return JSON (not HTML), and GET / must return the Control Panel (not 404 NOT_FOUND).
-Do not put startCommand or processes in vercel.json (v0 schema rejects them). Do not move server.ts into api/.
+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.
 ```
 
 Alternate triggers:
@@ -74,14 +78,14 @@ almost always means **Vercel still thinks this is a Next.js / static deploy**, n
 2. **Install Command** = `npm install` / `pnpm install` / `yarn` (normal install).
 3. **Build Command** = a **no-op that exits 0** (e.g. `node -e "process.exit(0)"` or `npm run build` where `build` is that no-op).  
    **Never** run `next build` for Production.
-4. **Start / Dev Command for Production** = `npm run start` / `pnpm start` → **`tsx server.ts`** (or `.mts`) that calls `TomorrowOS.listen` and **`export default server`**.
+4. **Production entry** = Fluid **Vercel Function** `api/index.ts` that **`export default server`** from shared `cms-app.ts` (see [WebSockets docs](https://vercel.com/docs/functions/websockets)). Local `npm start` may still use root `server.ts`.
 5. **Output Directory** = **empty / unset**. Do **not** set `outputDirectory: "."` as a fake static site.
-6. **Do not** create a root `api/index.ts` that exports a raw `http.Server` and catch-all `routes` to “fix” 404 — Vercel Fluid does **not** treat that as a supported handler for this CMS. That pattern causes more 404s.
+6. **Do** use a single `api/index.ts` that exports the TomorrowOS `http.Server`. **Do not** create a second TomorrowOS in `api/ws.ts`, and **do not** use bare `(req, res)` handlers that drop upgrades.
 7. If Preview needs Next, keep Next files **isolated** so Production auto-detect cannot latch onto them:
    - Prefer `preview/` (or similar) for `next.config.*`, `app/`, `pages/` used only by v0 Preview, **or**
-   - Ensure Production Framework Preset is forced to **Other** and Start Command never runs `next`.
+   - Ensure Production Framework Preset is forced to **Other** and never runs `next` as the CMS.
 
-**Setup is NOT complete** while Production `GET /` returns `404: NOT_FOUND`. Fix Framework Preset + Start Command and redeploy.
+**Setup is NOT complete** while Production `GET /` returns `404: NOT_FOUND` or WebSocket upgrade returns 200 HTML.
 
 ### Publish static trap — `public/` served without Node (read this)
 
@@ -92,11 +96,11 @@ A common **worse** failure mode than `404: NOT_FOUND`:
 - The panel shows **CMS unreachable** and console:  
   `Unexpected token 'T', "The page c"... is not valid JSON`
 
-**Root cause:** Vercel deployed `public/` as a **static site** (Output Directory = `public` or Framework=Other default *“public if it exists”*). **No Node process** is running `tsx server.ts`, so API routes never hit `TomorrowOS`.
+**Root cause:** Vercel deployed `public/` as a **static site** (Output Directory = `public` or Framework=Other default *“public if it exists”*). **No Function** is running TomorrowOS.
 
-**Fix (Scheme A — see dedicated section below):** force Vercel to run the **root `server.ts` Node entry** with Fluid. `public/` must be served **at runtime** via `staticRoot` in `listen()`, **not** as the build output directory.
+**Fix (Scheme A):** use `cms-panel/` (not `public/`), Fluid Function `api/index.ts` + rewrites, Output Directory empty. Static UI is served **at runtime** via `staticRoot` in `listen()`.
 
-**Publish gate (mandatory):** after deploy, `GET /status` must return **JSON** starting with `{`, not HTML starting with `<` or `The page`.
+**Publish gate (mandatory):** after deploy, `GET /status` must return **JSON** starting with `{`, not HTML starting with `<` or `The page`. **And** WebSocket upgrade on `/` or `/api` must return **101**.
 
 ```bash
 curl -s https://YOUR-PROJECT.vercel.app/status | head -c 80
@@ -104,7 +108,7 @@ curl -s https://YOUR-PROJECT.vercel.app/status | head -c 80
 # Failure:  The page could not be found  OR  <!DOCTYPE html>
 ```
 
-**Setup is NOT complete** while `/status` returns HTML or the panel shows the JSON parse error.
+**Setup is NOT complete** while `/status` returns HTML, the panel shows the JSON parse error, or devices cannot open `wss://`.
 
 ### Preview (v0 / Vercel Agent sandbox) — Next.js shell allowed
 
@@ -127,15 +131,25 @@ 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**:
+Ask **only** these questions, in **this exact order**. After each answer, **configure that step immediately**, then proceed:
 
-| 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 |
+| 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 |
 
-**That is the complete list.** Do **not** ask how many screens / devices.
+**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`)
 
 **Forbidden extra questions (never ask, even if the user skips a step):**
 
@@ -159,187 +173,198 @@ 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. **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`: root `server.ts`, `cms-panel/`, `vercel.json`). For Replit 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. Confirm Project settings after scaffold.
-11. **Production:** export the HTTP server Vercel can capture: `const server = tomorrowos.listen(...); export default server;` (or equivalent). **Do not** make `next start` the Production entrypoint.
-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 `/`). Do not run a long test suite.
+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.
 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` **or** `/status` returns HTML (static `public/` trap).
-18. **Scheme A is doc-driven:** achieve Production Node Publish by **project layout + `vercel.json` + dashboard settings** during setup — **no SDK code changes** required (see **Scheme A** section).
+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 → Q2 → Q3 → execution checklist.
+**Question order:** Q1 → **configure Q1** → Q2 → **configure Q2** → Q3 → **write brand.json** → deploy checklist.
 
 ---
 
-## Scheme A — Standard Node Publish (mandatory for Production)
+## Scheme A — Vercel Functions + WebSockets (mandatory for Production)
 
-> **Goal:** Preview may use Next + proxy; **Publish** runs **only** root `server.ts` + `TomorrowOS.listen` on Vercel Fluid.  
-> **Scope:** This section is implemented entirely during setup (move files, write `vercel.json`, patch dashboard). **Do not** change `@tomorrowos/sdk` source.
+> **Goal:** Preview may use Next + proxy; **Publish** runs TomorrowOS as a **Vercel Function** (`api/index.ts`) on **Fluid**, with WebSocket support per [Vercel WebSockets docs](https://vercel.com/docs/functions/websockets).  
+> **Scope:** Layout + `vercel.json` + dashboard. Prefer `npx @tomorrowos/sdk init --hosting v0` (`cms-starter-v0`).  
+> **Do not** break Replit/Railway: those keep using default `init` → `cms-starter` (root `server.ts` + `server.listen`, no `api/`).
 
 ### Why Scheme A exists
 
 | Layer | Preview (v0) | Publish (Production) |
 |-------|----------------|----------------------|
-| Host | Next.js shell + HTTP proxy | **Node `server.ts`** only |
-| `public/` | Proxied from TomorrowOS | Served by **`staticRoot`** inside `listen()` — **not** as Vercel Output Directory |
-| WebSocket | Optional / may fail in Preview | Required on same origin (`wss://`) |
-| Next files | Allowed under `preview/` | **Must not** live at project root |
+| 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 |
+
+**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)).
 
 ### A1 — Project layout (Agent must enforce)
 
-**At project root (Production):**
+**Production (Vercel / v0 starter):**
 
 ```
-server.ts          ← REQUIRED name at root (or server.mts)
+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
-package.json
+cms-panel/
 brand.json
-public/            ← CMS static UI; NOT the Vercel output directory
-```
-
-**Preview only (when v0 needs Next) — move ALL of these under `preview/`:**
-
-```
-preview/
-  next.config.mjs
-  app/               ← Next proxy routes
-  postcss.config.mjs
-  next-env.d.ts
-  tsconfig.json      ← Next/tsconfig if separate from server
+package.json       ← "dev": "npm run dev:preview"
 ```
 
-**Remove from project root after move:** `next.config.mjs`, `app/`, root Next `tsconfig` plugin config, `postcss.config.mjs`, `next-env.d.ts`.
-
 **Do NOT:**
 
-- ❌ Leave `next.config.mjs` + `app/` at root while claiming Production is Node-only
-- ❌ Create root `api/index.ts` exporting `http.Server` + `routes` catch-all
-- ❌ Set Output Directory to `public` or `.`
+- ❌ Add `app/page.tsx` that returns null (v0 shows “Your v0 generation will show here”)
+- ❌ 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`
 
-**Update `package.json` scripts when Preview uses `preview/`:**
+**`package.json` scripts:**
 
 ```json
 {
   "scripts": {
-    "dev": "tsx watch server.ts",
+    "dev": "npm run dev:preview",
     "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
     "dev:tomorrowos": "cross-env TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
-    "dev:next": "cd preview && next dev -p 3000",
+    "dev:next": "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.
 
-### A2 — `server.ts` entry (Vercel zero-config Node detection)
-
-Vercel detects a **root** `server.ts` / `server.mts` and routes traffic to it when:
+### A2 — Function entry (matches Vercel WebSockets docs)
 
-1. The file lives at **project root** (not only under `api/`)
-2. **`listen()` runs at module load** (top-level, not inside an unexported function)
-3. The file **`export default server`** (the `http.Server` from `tomorrowos.listen`)
-
-Use the pattern in **Runtime & Vercel deploy rules** below. On Publish, **do not** set `TOMORROWOS_INTERNAL_PORT` — let Vercel inject `PORT`.
+```ts
+// api/index.ts
+export { server as default } from "../cms-app.js";
+```
 
-### A3 — `vercel.json` (Production)
+```ts
+// cms-app.ts (shared)
+const server = tomorrowos.listen({
+  port: Number(process.env.PORT) || 3000,
+  host: "0.0.0.0",
+  staticRoot: join(__dirname, "cms-panel"),
+});
+export { server, tomorrowos };
+```
 
-**v0 / `.v0/vercel.deploy.json` schema:** only a **minimal** object is valid. These keys are **rejected** — never add them:
+SDK behaviour (0.9.30+):
 
-- ❌ `startCommand`
-- ❌ `processes`
-- ❌ `routes` / `rewrites` to fake API routing
-- ❌ `outputDirectory: "public"` or `"."`
+- 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
+- Pattern aligns with docs: create `http.Server`, attach `ws`, **`export default server`**
 
-Vercel discovers the start command from **`package.json` → `"start": "tsx server.ts"`**, not from `vercel.json`.
+### A3 — `vercel.json` (Production)
 
 ```json
 {
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build"
+  "buildCommand": "npm run build",
+  "functions": {
+    "api/index.ts": {
+      "maxDuration": 300,
+      "memory": 1024,
+      "includeFiles": "{cms-panel/**,brand.json,assets/**}"
+    }
+  },
+  "rewrites": [
+    { "source": "/((?!api/).*)", "destination": "/api" }
+  ]
 }
 ```
 
-Use `pnpm` / `yarn` equivalents if the project uses them.
+**`maxDuration` plan limits:** Hobby / many default plans allow **1–300** seconds. **800** requires a higher Vercel plan. Prefer **`300`** unless the account already allows more — otherwise Publish fails with *“maxDuration must be between 1 and 300… upgrade your plan”*.
 
-**Critical:**
+**Why rewrites:** Public URLs stay `https://app.vercel.app/` and `/status` while the Function mount is `/api`. Device `wss://app.vercel.app/` is rewritten to the same Function so one isolate handles HTTP + WS.
+
+**v0 schema:** never add `startCommand` or `processes`.
 
-- **Do not** add `startCommand` to `vercel.json` (invalid in v0; redundant on full Vercel — use `package.json` `start`)
-- **Do not** set `outputDirectory` to `public` or `.`
-- `"buildCommand"` must run the no-op `npm run build` — **never** `next build` for Production
-- Set **Output Directory empty** in the **Vercel dashboard** (Scheme A4) — that is where static-vs-Node is decided, not via invalid `vercel.json` keys
+**Critical:**
 
-### A4 — Vercel Project Settings (dashboard or API — mandatory)
+- `"fluid": true` is required for WebSockets
+- **Do not** set `outputDirectory` to `cms-panel` / `public`
+- `"buildCommand"` = no-op — **never** `next build` for Production
+- Dashboard Output Directory must stay **empty**
 
-`vercel.json` alone is **not enough** if the dashboard still shows Framework = **Next.js** or Output = `public`.
+### A4 — Vercel Project Settings (dashboard — mandatory)
 
 | Setting | Required value |
 |---------|----------------|
 | Framework Preset | **Other** / null — **not Next.js** |
-| Install Command | `npm install` (or pnpm/yarn) |
-| Build Command | `npm run build` (no-op exit 0) |
-| **Output Directory** | **empty / null** — **NOT `public`** |
-| **Start Command** | `npm run start` → `tsx server.ts` |
+| Install Command | `npm install` |
+| Build Command | `npm run build` (no-op) |
+| **Output Directory** | **empty** |
 | Fluid compute | **On** |
+| WebSockets | Account must allow Functions WebSockets (see docs “Permissions Required”) |
 
-If Framework Preset still shows **Next.js** after `vercel.json`: **patch via Vercel API / CLI / dashboard**, then redeploy.
+### A5 — Publish acceptance (all must pass)
 
-### A5 — Publish acceptance (all must pass before “setup complete”)
+1. `curl -s https://PROD/status` → JSON (`{"status":...}`)
+2. `curl -s https://PROD/` → Control Panel HTML
+3. **WebSocket upgrade returns 101**, not 200 HTML:
 
-1. Deploy logs show Node starting / `[TomorrowOS] listening on ...` (not only “Uploading static files”)
-2. `curl -s https://PROD/status` → JSON (`{"status":...}`)
-3. `curl -s https://PROD/` → Control Panel HTML
-4. Control Panel **does not** show `Unexpected token 'T'` / CMS unreachable
-5. Framework Preset = Other; Fluid on
-
-If (2) fails but (3) passes → **static `public/` trap**. Re-apply A3 + A4; confirm dashboard Start Command + empty Output Directory; redeploy. **Do not** add `api/` catch-all. **Do not** move `server.ts` into `api/`.
-
-### A6 — What Scheme A does **not** require
-
-- ❌ No changes to `@tomorrowos/sdk` package code
-- ❌ No `(req, res)` serverless handler refactor
-- ❌ No `next build` / `next start` on Production
-- ❌ No root `api/` directory (`api/index.ts`, `api/[...].ts`, `api/[[...slug]].ts`)
-- ❌ No `rewrites` so only `/api/status` works while `/status` stays 404
-- ❌ No renaming `start` → `dev` with `tsx watch` for Production
-- ❌ No `@vercel/node` handler that calls non-existent `tomorrowos.getStatus()`
+```bash
+curl.exe -i --http1.1 ^
+  -H "Connection: Upgrade" -H "Upgrade: websocket" ^
+  -H "Sec-WebSocket-Version: 13" ^
+  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" ^
+  "https://PROD/"
+# Also try: https://PROD/api
+```
 
-### A7 — If v0 Publish still serves static `public/` (Path B)
+4. Control Panel does **not** show CMS unreachable / `Unexpected token 'T'`
+5. Fluid on; Framework = Other
 
-When **v0 Publish** keeps returning the static trap (`/` HTML OK, `/status` HTML, `Unexpected token 'T'`) **after** Scheme A is correct, the v0 deploy pipeline may not be starting the Fluid Node server.
+If (1)+(2) pass but (3) fails → Function is serving HTTP only. Re-check Fluid, `api/index.ts` default export, rewrites, and WebSockets permission. **Do not** invent a second `api/ws.ts` TomorrowOS instance.
 
-**Path B — deploy outside v0 Publish (recommended):**
+### A6 — What Scheme A does **not** require
 
-1. Keep Scheme A layout (root `server.ts`, Next only under `preview/`, minimal `vercel.json`).
-2. Connect the repo to **Vercel Git** or run **`vercel --prod`** from the project root (full Vercel CLI / dashboard deploy — not the v0 “Publish” button).
-3. In **Vercel Dashboard → Project → Settings → General**: Framework = **Other**, Output Directory = **empty**, Build = `npm run build`, **override** Install/Start if needed so Production runs `npm run start`.
-4. Redeploy; verify `curl https://PROD/status` → JSON.
+- ❌ No Next.js as Production CMS
+- ❌ No replacing SDK transport with hand-rolled pairing
+- ❌ No SQLite as production store on Vercel
+- ❌ No changes to Replit `cms-starter` layout for Vercel-only fixes
 
-**Path C — if Vercel cannot run TomorrowOS Node + WebSocket reliably:**
+### A7 — If v0 Publish still fails (Path B / C)
 
-Host the CMS on **Railway**, **Fly.io**, or **Replit Publish** (long-lived Node). Use v0/Vercel only for Preview/demo if needed.
+**Path B:** Deploy with `vercel --prod` or Git integration (full Vercel), same Scheme A layout.
 
-### A8 — Undo a broken Agent “api/ migration”
+**Path C:** Host CMS on **Railway / Fly.io / Replit** (long-lived Node). Use Vercel only for Preview if needed.
 
-If an Agent moved `server.ts` → `api/index.ts` / `api/[...].ts` and only `/api/status` returns JSON:
+### A8 — Migrate an existing broken Vercel project
 
-1. **Restore** `server.ts` at **project root** (from git or `templates/cms-starter/server.ts`).
-2. **Delete** root `api/index.ts`, `api/[...].ts`, `api/[[...slug]].ts` (Preview proxy may stay under `preview/app/` only).
-3. Revert `package.json` `start` to `tsx server.ts` (not `tsx watch` for Production).
-4. Apply minimal `vercel.json` (A3) — no `startCommand`, no `rewrites`.
-5. Dashboard: Framework Other, Output empty, Fluid on.
-6. Redeploy via Path B if v0 Publish still fails.
+1. Scaffold/compare with `cms-starter-v0` (`init --hosting v0`) or copy:
+   - `cms-app.ts`, `api/index.ts`, `server.ts`, `vercel.json`
+   - rename `public/` → `cms-panel/` if still present
+2. Ensure **one** Function exports the **same** `server` from `cms-app.ts`
+3. Fluid on → Redeploy
+4. Verify A5 (especially WebSocket 101)
+5. On TVs: enter `https://YOUR.vercel.app/` (players also try `/api` automatically on vercel.app hosts)
 
 ---
 
@@ -347,18 +372,19 @@ If an Agent moved `server.ts` → `api/index.ts` / `api/[...].ts` and only `/api
 
 ### Production runtime (Publish)
 
-- Serve with **`tsx server.ts`** (or `server.mts` / compiled Node that still calls `TomorrowOS.listen` with `staticRoot`).
-- Keep **`@tomorrowos/sdk`** and put **`tsx` in `dependencies`** (not only `devDependencies`) if production runs via `tsx`.
+- 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.
 - Node **20+**.
 - **Do not** replace the SDK with a hand-rolled server that drops WebSocket upgrades.
-- **Forbidden as the Production Deploy entrypoint:** `next start`, static export only, root `api/` fake catch-all for raw `http.Server`, or any command that does not start `TomorrowOS.listen(...)`.
+- **Forbidden as the Production CMS:** `next start`, static export only, or a bare `(req,res)` handler without `http.Server` + `ws`.
 
 ### Expected `package.json` scripts
 
 ```json
 {
   "scripts": {
-    "dev": "tsx watch server.ts",
+    "dev": "npm run dev:preview",
     "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",
@@ -370,9 +396,10 @@ If an Agent moved `server.ts` → `api/index.ts` / `api/[...].ts` and only `/api
 
 Adapt script names / process runners as needed. **Invariant:**
 
-- **`npm start` / Production** = TomorrowOS Node only.
+- **Local / v0 Preview `npm run dev`** = TomorrowOS `:3001` + Next `:3000` proxy.
+- **Vercel Production** = Function `api/index.ts` (SDK `autoListen=false` when `VERCEL` is set).
 - **`build`** = no-op exit 0 (never `next build` for Production).
-- **Preview / v0** = Next on public port + TomorrowOS on internal port + proxy.
+- **Do not** ship an empty `app/page.tsx` (v0 placeholder).
 
 ### Minimal dependencies (Production)
 
@@ -450,32 +477,37 @@ 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 when Preview is Next-hardwired
+### Preview adapter (v0 / Next reverse proxy) — required for Preview UI
 
-Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs “listening”). Then:
+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.
 
-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:
+**Required layout (cms-starter-v0):**
 
-```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.
+```
+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)
 ```
 
-Preferred UX: proxy **`/`** itself (rewrites) so the Preview URL shows the Control Panel at `/`, not only under `/api/...`.
+**Agent must:**
 
-4. Start **both** processes for Preview (`dev:preview` pattern above).
-5. Document in the final summary: **Preview = Next shell + proxy; Publish = Node only.**
+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).**
 
 **Forbidden:**
 
-- 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”.
+- 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`
 
 ### `vercel.json` (Production — explicit Node, not Next)
 
@@ -533,7 +565,8 @@ 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.
+> **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.
 
 ### Step A — Ask storage choice
 
@@ -551,6 +584,8 @@ 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`**.
@@ -563,17 +598,20 @@ 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:
+1. Set Vercel Env Vars **now** (open Env UI if available):
    - `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 `server.ts` as in **Runtime & Vercel deploy rules**.
+2. Wire store in `cms-app.ts` / `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`**.
@@ -584,14 +622,15 @@ 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:
+1. Set Vercel Env Vars **now**:
    - `DATABASE_URL=<user pooled string>`
    - `TOMORROWOS_STORE=postgres` ← **agent sets this**
    - `DATABASE_SSL=true` ← **agent sets this**
-2. Wire `server.ts` — `createTomorrowOSStore` uses `PostgresStore` for `postgres` / `supabase` drivers.
+2. Wire `createTomorrowOSStore` for Postgres.
 3. **Do not** commit the real connection string.
-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.
+4. **Do not** ask the user to fill `TOMORROWOS_STORE` or `DATABASE_SSL`.
 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**
 
@@ -604,8 +643,9 @@ 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 `server.ts` for `data/tomorrowos.db`.
+2. Keep `sqlitePath` in `cms-app.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).
 
@@ -614,25 +654,26 @@ 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.
+> 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.
 
 ### Step A — Ask storage choice
 
-**Ask exactly:**
+**Ask exactly (wording must match):**
 
 > 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.
+> **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.**
 >
-> **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.
+> **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.
 >
-> **3. Local disk only** — `public/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
+> **3. Local disk only** — `cms-panel/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** (same Question 2 — **one Env popup**)
+### Step B — If **1 / Cloudinary** (configure **immediately** — one Env popup)
 
-> **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.
+> **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.
 
 **Preferred:** Vercel Env Vars UI (or Agent secrets form) with these fields together:
 
@@ -658,10 +699,13 @@ 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** (same Question 2)
+### Step C — If **2 / Vercel Blob** (configure **immediately**)
+
+**Immediately** (do not ask Q3 yet):
 
 **Ask exactly:**
 
@@ -689,46 +733,51 @@ 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. `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.
+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**.
 
 ---
 
 ## Question 3 — Brand (`brand.json` only)
 
-> Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or `server.ts` store wiring beyond what Q1–Q2 already required.
+> Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or 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).  
+> 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**).  
 > **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.
+> 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.
 
 ### Step A — Ask branding input
 
 **Ask exactly:**
 
-> Let’s brand your TomorrowOS experience. You can answer in either way:
+> Let’s brand your TomorrowOS experience. Choose **one**:
 >
-> **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 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 B — Manual fields**  
-> Provide:
-> 1. **Product / venue name**
+> **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)
 > 2. **Tagline** (optional)
 > 3. **Primary colour** (hex, e.g. `#FF8A3D`)
-> 4. **Background colour** (hex, optional — default `#FAFAF9`)
+> 4. **Background colour** (hex — page / panel background)
 > 5. **Text colour** (hex, optional — default `#0A0908`)
 > 6. **Secondary / accent colour** (hex, optional)
-> 7. **Logo** — upload SVG/PNG into the project, or a URL I can fetch into `./assets/`
+> 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).
 
 ### Step B — If the user gives **only a website URL** (Option A)
 
-**You must:**
+**You must (immediately — do not defer brand write to “end of setup”):**
 
 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).
@@ -743,7 +792,8 @@ 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 hex + logo path) before or while writing the file — do not ask a second branding question unless fetch failed.
+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).
 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):**
@@ -788,27 +838,31 @@ 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 all answers — execution checklist
+## 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.
 
-### A. Seed the project
+### A. Seed the project (do this early if the repo is empty — before or during Q1)
 
 ```bash
-npx @tomorrowos/sdk@latest init .
+npx @tomorrowos/sdk@latest init . --hosting v0
 # If not empty and user confirms starter overwrite:
-# npx @tomorrowos/sdk@latest init . --force
+# npx @tomorrowos/sdk@latest init . --hosting v0 --force
 ```
 
 Then (**Scheme A — mandatory for Publish**):
 
-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`.
+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`.
 6. Do **not** add `.replit*`.
-7. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
+7. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge (should already be started in Q2).
 
 ### B. Environment Variables (Vercel dashboard + local)
 
@@ -883,23 +937,26 @@ Tell the user:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Node start | Scheme A: Framework = **Other**, Start = `npm run start`, Output empty, Fluid on; redeploy |
-| Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** — no Node running | Scheme A: Output empty in dashboard, `start` in package.json; undo any `api/` migration; try **Path B** deploy |
-| Only `/api/status` returns JSON, `/status` is 404 | Wrong **api/ serverless** migration + broken rewrites | **A8 undo:** restore root `server.ts`, delete root `api/*`; never accept this as “fixed” |
-| `vercel.json` error: invalid `startCommand` | v0 schema rejects it | Remove from `vercel.json`; use `package.json` `start` + dashboard Start Command |
-| Agent moved server to `api/`, added `@vercel/node` handler | Off-protocol serverless refactor | **A8 undo** — TomorrowOS needs one root `listen()` server, not per-request handlers |
-| `vercel inspect` shows Output = `public if it exists` | Framework=Other static default | Force Output Directory **empty** in dashboard; root `server.ts`; Path B redeploy |
+| Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Function | Scheme A: Framework = **Other**, Fluid on, `api/index.ts` + rewrites; redeploy |
+| Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** — no Function | Rename to `cms-panel/`; Output empty; Scheme A Function entry; **Path B** if needed |
+| Only `/api/status` returns JSON, `/status` is 404 | Missing **rewrites** to `/api` | Add Scheme A3 rewrite `/(.*) → /api` (exclude existing `/api/`); redeploy |
+| Control Panel OK, TV **could not connect** | WebSocket upgrade not reaching Function (200 HTML) | Fluid on; `export default server`; verify 101 on `/` and `/api`; check WebSockets permission |
+| `vercel.json` error: invalid `startCommand` | v0 schema rejects it | Remove from `vercel.json`; Function entry does not need startCommand |
+| 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 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 entry to `tsx server.ts` / `export default server` |
+| 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 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 |
-| Uploads break / broken thumbs in prod | Local `public/uploads` | Cloudinary or Vercel Blob |
+| Uploads break / broken thumbs in prod | Local uploads only | Cloudinary or Vercel Blob |
 | Blob uploads 401 / missing token | Blob not linked | Vercel Storage → Blob + `BLOB_READ_WRITE_TOKEN` |
-| WebSocket fails on Publish | Fluid off / static-only / Next as Production | Enable Fluid; sole Node `listen()` for Publish |
+| 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 asked Cloudinary key/secret in three chat turns | Off-protocol | Use **one Env popup** with all Cloudinary fields |
+| 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 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 |
@@ -915,10 +972,11 @@ 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 **or Vercel Blob** |
+| Media | Cloudinary or Replit Object Storage | **Cloudinary (recommended)** or Vercel Blob (not Supabase Storage) |
 | Preview | Replit Preview / Autoscale Node | **Next shell + proxy** when v0 hardwires Next |
-| 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 |
+| 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) |
 
 ---