@tomorrowos/sdk 0.9.31 → 0.9.33

package/VERCEL_SETUP.md

@@ -5,8 +5,10 @@
 >
 > **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.9` — pairs with `@tomorrowos/sdk` **0.9.33+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+>
+> **Copy questions verbatim from this file.** Do not invent alternate Q2 options (no “Supabase Storage”, no “disable media”, no making Blob the recommended option).  
+> **`TOMORROWOS_STORE` and `DATABASE_SSL` are agent-only** — set them automatically after Q1; never put them in a user-facing Env form for the customer to type.
 
 ## User trigger (copy-paste)
 
@@ -14,17 +16,13 @@ When a human pastes a prompt like this, **read this file and start Question 1 im
 
 ```text
 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.
+Ask only the questions listed in VERCEL_SETUP.md, in order — copy Question 1/2/3 wording verbatim. Do not use LLM_PROMPT.md or REPLIT_SETUP.md.
+Do not ask for OpenAI / Anthropic / any LLM API keys.
+Question 2 MUST be exactly: 1 Cloudinary (recommended), 2 Vercel Blob, 3 local disk. NEVER offer Supabase Storage, “no media storage”, or Blob as recommended.
+After I choose a database, YOU set TOMORROWOS_STORE and DATABASE_SSL automatically — do not ask me to fill those two Env Vars.
+If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation). Prefer Supabase Session pooler or Neon pooled URL.
+Question 3 only updates brand.json (website URL = brand reference only — no CMS login unless I ask).
+Use cms-starter-v0 layout. Publish = Fluid Function (api/index.ts). Preview may use Next proxy.
 ```
 
 Alternate triggers:
@@ -131,40 +129,43 @@ 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**. **Copy the “Ask exactly” blocks verbatim** — do not paraphrase options.
+
+| Step | Section | When |
+|------|---------|------|
+| 1 | **Question 1** — Database (Supabase → Neon → SQLite) | Always |
+| 2 | **Question 2** — Media (**Cloudinary recommended** → 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):**
+**Forbidden invented Question 2 options (never offer these in chat or UI):**
 
+- ❌ “Vercel Blob **(recommended)**” as option 1 — Blob is option **2**, not recommended over Cloudinary
 - ❌ “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
+- ❌ “No media storage” / “disable media uploads” / “remote URLs only” as a numbered choice
+- ❌ Any media list that does not start with **Cloudinary (recommended)**
 
-**Forbidden Question 3 shortcuts:**
+**Forbidden Env UX after Question 1:**
 
-- ❌ 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`)
+- ❌ Showing the user empty fields for `TOMORROWOS_STORE` or `DATABASE_SSL` to fill
+- ❌ Asking in chat “what should TOMORROWOS_STORE be?”
+- ✅ After DB choice + URL paste: **you** write those two vars silently (see Q1 Steps B/C/D)
 
 **Forbidden extra questions (never ask, even if the user skips a step):**
 
 - ❌ OpenAI / Anthropic / Gemini / any LLM API key (`sk-…`, etc.)
 - ❌ “AI pairing”, “AI feature logic”, or inventing auth that needs an LLM key
-- ❌ Asking the user to type `TOMORROWOS_STORE` or `DATABASE_SSL` after they already chose Neon/Supabase — **you set those automatically**
+- ❌ Asking the user to type `TOMORROWOS_STORE` or `DATABASE_SSL`
 - ❌ Any secret not listed in Questions 1–3 (DB URL, media credentials, brand)
 
 TomorrowOS pairing and Control Panel logic live in `@tomorrowos/sdk`. They do **not** call OpenAI.
 
-If the user **skips** a Question 2 option, do **not** invent a substitute question. Re-state Question 2 choices, or proceed with a documented default (e.g. local uploads with a warning) — never pivot to LLM keys.
+If the user **skips** a Question 2 option, do **not** invent a substitute question. Re-state Question 2 choices **verbatim**, or proceed with local uploads + warning — never pivot to LLM keys or Supabase Storage.
 
 If the user says “just set it up, don’t ask questions,” respond:
 
-> I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage, and branding). It takes about a minute and ensures the CMS works on Vercel.
+> I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage with Cloudinary recommended, and branding). It takes about a minute and ensures the CMS works on Vercel.
 
 Then ask **Question 1**.
 
@@ -172,26 +173,26 @@ 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.
-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.
+1. **Ask only VERCEL_SETUP.md questions 1–3, verbatim.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
+2. **Question 2 options are fixed:** (1) Cloudinary **(recommended)**, (2) Vercel Blob, (3) local disk. Do not reorder; do not invent Supabase Storage / disable-uploads.
+3. **Cloudinary:** open **one** Vercel Env popup with **all** Cloudinary fields together. Do **not** quiz one credential at a time.
+4. **`TOMORROWOS_STORE` + `DATABASE_SSL` = agent-owned.** After Q1 choice (and URL if needed), set them yourself in Vercel Env Vars. **Never** include them as blank fields for the customer. Mapping: Supabase → `TOMORROWOS_STORE=supabase` + `DATABASE_SSL=true`; Neon → `TOMORROWOS_STORE=postgres` + `DATABASE_SSL=true`; SQLite → `TOMORROWOS_STORE=sqlite` (no `DATABASE_SSL` required).
+5. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
+6. **Postgres env naming:** prefer **`SUPABASE_URL`** for Supabase; prefer **`DATABASE_URL`** for Neon.
+7. **Always prefer pooled connection strings** (Supabase Session pooler **6543**; Neon pooled host).
+8. **Prefer `npx @tomorrowos/sdk init --hosting v0`**. For Replit/Railway use default `init`. Do not rebuild pairing / WebSocket APIs.
+9. **Never commit secrets.** Use Vercel Environment Variables.
+10. **Skip Replit-only files.**
+11. **SQLite is not a production store on Vercel.**
+12. **Enable Fluid compute** for Production WebSockets.
+13. **Production:** `api/index.ts` exports `http.Server` from `TomorrowOS.listen`. Not `next start`. No second TomorrowOS in `api/ws.ts`.
+14. **Preview:** Next reverse-proxy shell when v0 is Next-hardwired.
+15. After Q&A: **configure → install → deploy → minimal verify**.
+16. **No inventing CMS login** from a branding URL.
+17. **Skip ≠ invent.** Stay on Q1–Q3 only.
+18. **Publish gate:** `/status` JSON + WebSocket 101; no static `public/` trap.
+
+**Question order:** Q1 → (auto-set store env) → Q2 → Q3 → execution checklist.
 
 ---
 
@@ -205,10 +206,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 +218,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 +280,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 +382,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 +392,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 +404,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 +485,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)
 
@@ -566,7 +569,17 @@ 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.
+> **After the user picks a database:** collect the URL if needed, then **you** set `TOMORROWOS_STORE` + `DATABASE_SSL` (see mapping below). The customer must **never** be asked to type those two names or values.
+
+### Agent-owned env mapping (mandatory)
+
+| User chose | You set (silently) | User only provides |
+|------------|--------------------|--------------------|
+| 1 Supabase | `TOMORROWOS_STORE=supabase`, `DATABASE_SSL=true` | `SUPABASE_URL` (pooler string) |
+| 2 Neon | `TOMORROWOS_STORE=postgres`, `DATABASE_SSL=true` | `DATABASE_URL` (pooled string) |
+| 3 SQLite | `TOMORROWOS_STORE=sqlite` | Confirmation only |
+
+If you open an Env configuration UI for Q1, fields visible to the user may include **only** `SUPABASE_URL` or `DATABASE_URL`. **Do not** show blank `TOMORROWOS_STORE` / `DATABASE_SSL` inputs — write those yourself in the same step.
 
 ### Step A — Ask storage choice
 
@@ -584,11 +597,9 @@ 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):**
+**Ask exactly (connection string only — not TOMORROWOS_STORE / DATABASE_SSL):**
 
-> Paste your Supabase Postgres connection string. I will store it as **`SUPABASE_URL`**.
+> Paste your Supabase Postgres connection string. I will store it as **`SUPABASE_URL`**. I will set **`TOMORROWOS_STORE`** and **`DATABASE_SSL`** for you automatically.
 >
 > In Supabase: **Project Settings → Database → Connection string → Connection pooling** (Session mode).  
 > Preferred shape:  
@@ -596,41 +607,37 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 >
 > **Do not** use the direct host `db.*.supabase.co:5432` for Vercel.
 
-**You must then (automatic — do NOT ask the user to type these):**
+**You must then (automatic — do NOT ask the user to type store/ssl 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 store in `cms-app.ts` / `server.ts` as in **Runtime & Vercel deploy rules**.
+1. Set Vercel Env Vars in one step:
+   - `SUPABASE_URL=<user pooler string>` ← from user
+   - `TOMORROWOS_STORE=supabase` ← **you set; never ask**
+   - `DATABASE_SSL=true` ← **you set; never ask**
+2. Wire `cms-app.ts` / `server.ts` store 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**.
+5. **Do not** open a form whose blank fields include `TOMORROWOS_STORE` or `DATABASE_SSL`.
 
 ### 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`**.
+> Paste your **Neon pooled** Postgres connection string. I will store it as **`DATABASE_URL`**. I will set **`TOMORROWOS_STORE`** and **`DATABASE_SSL`** for you automatically.
 >
 > In Neon: **Dashboard → Connection details → Pooled connection**.  
 > Typical shape:  
 > `postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require`
 
-**You must then (automatic — do NOT ask the user to type these):**
+**You must then (automatic):**
 
-1. Set Vercel Env Vars **now**:
-   - `DATABASE_URL=<user pooled string>`
-   - `TOMORROWOS_STORE=postgres` ← **agent sets this**
-   - `DATABASE_SSL=true` ← **agent sets this**
+1. Set Vercel Env Vars:
+   - `DATABASE_URL=<user pooled string>` ← from user
+   - `TOMORROWOS_STORE=postgres` ← **you set; never ask**
+   - `DATABASE_SSL=true` ← **you set; never ask**
 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`.
+4. **Do not** ask the user to fill `TOMORROWOS_STORE` or `DATABASE_SSL` in chat or Env UI.
 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 +650,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` 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).
 
@@ -655,11 +661,11 @@ Only proceed after the user explicitly confirms.
 
 > **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.
+> **Copy the three options below verbatim.** Wrong examples that must **never** appear: “Vercel Blob (recommended)”, “Supabase Storage”, “No media storage / disable uploads”.
 
 ### Step A — Ask storage choice
 
-**Ask exactly (wording must match):**
+**Ask exactly (wording must match — Cloudinary is recommended):**
 
 > How should playlist media (images/videos) be stored?
 >
@@ -667,13 +673,15 @@ Only proceed after the user explicitly confirms.
 >
 > **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** — `cms-panel/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
+> **3. Local disk only** — `cms-panel/uploads` or `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)
+If you catch yourself about to offer Blob-as-recommended, Supabase Storage, or “no media”, **stop and paste the block above instead**.
 
-> **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.
+### Step B — If **1 / Cloudinary** (same Question 2 — **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.
 
 **Preferred:** Vercel Env Vars UI (or Agent secrets form) with these fields together:
 
@@ -699,13 +707,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 +738,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 +792,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 +837,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)
 
@@ -870,8 +865,8 @@ Then (**Scheme A — mandatory for Publish**):
 |------|----------|--------------|
 | `SUPABASE_URL` | If Q1 = Supabase | User pastes URL |
 | `DATABASE_URL` | If Q1 = Neon | User pastes URL |
-| `TOMORROWOS_STORE` | Yes | **Agent auto-sets** (`supabase` / `postgres` / `sqlite`) |
-| `DATABASE_SSL` | Yes for Postgres | **Agent auto-sets** `true` |
+| `TOMORROWOS_STORE` | Yes | **Agent auto-sets only** — never a blank field for the user (`supabase` / `postgres` / `sqlite`) |
+| `DATABASE_SSL` | Yes for Postgres | **Agent auto-sets only** — never a blank field for the user (`true`) |
 | `CLOUDINARY_*` | If Q2 = Cloudinary | User via **one Env popup** (all fields) |
 | `BLOB_READ_WRITE_TOKEN` | If Q2 = Vercel Blob | User / Blob link |
 | `TOMORROWOS_INTERNAL_PORT` | Preview only | Agent (e.g. `3001`) |
@@ -945,7 +940,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 |
@@ -953,10 +948,9 @@ Tell the user:
 | 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 / 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 user to fill `TOMORROWOS_STORE` / `DATABASE_SSL` | Off-protocol | Agent must auto-set after DB choice; remove those fields from user Env forms |
+| Agent offered Blob-as-recommended / Supabase Storage / “no media” for Q2 | Invented options | Re-ask Q2 verbatim: **1 Cloudinary (recommended)**, 2 Blob, 3 local |
+| 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 +966,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 |
 
 ---