@tomorrowos/sdk 0.9.30 → 0.9.31

package/README.md

@@ -74,12 +74,13 @@ In Vercel Agent (or any AI setup prompt), paste:
 ```text
 Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
 IF any step contradicts Vercel, adapt to settings that Vercel can accept.
+After each question, configure that step immediately before asking the next.
 ```
 
-That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary** → **Vercel Blob** → local),
-branding (manual fields or **website URL → `brand.json` only**, no login unless asked). Preview may use a thin **Next.js reverse proxy**;
-**Publish stays a Fluid Vercel Function** (`api/index.ts` + `export default server`, WebSockets per Vercel docs). Cloudinary uses **one Env popup** (all fields).
-Neon/Supabase: agent auto-sets `TOMORROWOS_STORE` + `DATABASE_SSL`. Sets `cms.hostingTarget` to `"vercel"`.
+That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary recommended** → **Vercel Blob** → local),
+branding (manual name/colours/background/logo **or** **website URL → full `brand.json`**, no login unless asked).
+**Configure immediately after each answer** (e.g. Cloudinary Env popup right after choosing Cloudinary).
+**Publish stays a Fluid Vercel Function** (`api/index.ts` + `export default server`, WebSockets per Vercel docs).
 
 ### Replit upgrade (existing CMS)
 

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.8` — pairs with `@tomorrowos/sdk` **0.9.30+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+> 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,12 +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), Fluid on, GET /status on the production URL must return JSON (not HTML), GET / must return the Control Panel, and WebSocket upgrade on / or /api must return 101 (not 200 HTML).
-Do not put startCommand or processes in vercel.json (v0 schema rejects them).
-Use cms-starter-v0 layout: cms-app.ts + api/index.ts (export default server) + cms-panel/ + rewrites to /api. Do not create a second TomorrowOS instance in api/ws.ts.
+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:
@@ -128,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):**
 
@@ -160,25 +173,25 @@ Then ask **Question 1**.
 ## Hard rules
 
 1. **Ask only VERCEL_SETUP.md questions 1–3.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
-2. **Cloudinary:** open **one** Vercel Env configuration popup / form with **all** Cloudinary fields together (cloud name + API key + API secret). Do **not** quiz the user one credential at a time in chat.
-3. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
-4. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
-5. **Always prefer pooled connection strings** (Supabase Session pooler port **6543**; Neon pooled host). Direct `:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
-6. **Prefer `npx @tomorrowos/sdk init --hosting v0`** (template `cms-starter-v0`: `cms-app.ts`, `api/index.ts`, `cms-panel/`, Fluid + rewrites). For Replit/Railway use default `init` (`cms-starter`). Do not rebuild pairing / WebSocket / playlist APIs.
-7. **Never commit secrets.** Use Vercel Environment Variables (+ optional non-secret flags in committed `.env.example`).
-8. **Skip Replit-only files:** do **not** create `.replit`, `.replit-artifact`, or Replit `deploymentTarget`.
-9. **SQLite is not a production store on Vercel.** Offer it only as option **3** after explicit warning. Keep `sqlitePath` as local-dev fallback in `createTomorrowOSStore`.
-10. **Enable Fluid compute** for Production WebSockets ([docs](https://vercel.com/docs/functions/websockets)). Confirm Project settings after scaffold.
-11. **Production:** one Vercel Function exports `http.Server` from `TomorrowOS.listen` (`api/index.ts`). **Do not** make `next start` the Production entrypoint. **Do not** spin a second TomorrowOS in `api/ws.ts`.
-12. **Preview:** if the environment is v0 / Next-hardwired, install the Next reverse-proxy shell (see **Preview adapter**). Do not leave Preview broken.
-13. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/` + WS 101). Do not run a long test suite.
+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 → Q2 → Q3 → execution checklist.
+**Question order:** Q1 → **configure Q1** → Q2 → **configure Q2** → Q3 → **write brand.json** → deploy checklist.
 
 ---
 
@@ -192,10 +205,10 @@ Then ask **Question 1**.
 
 | Layer | Preview (v0) | Publish (Production) |
 |-------|----------------|----------------------|
-| 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 |
+| 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)).
 
@@ -204,48 +217,41 @@ Then ask **Question 1**.
 **Production (Vercel / v0 starter):**
 
 ```
-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
+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/
 brand.json
-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/
-  …
+package.json       ← "dev": "npm run dev:preview"
 ```
 
 **Do NOT:**
 
-- ❌ Leave `next.config.mjs` + `app/` at project root
+- ❌ 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` (separate isolate = broken pairing memory)
-- ❌ Use `(req, res) =>` serverless handlers that drop `upgrade`
-- ❌ Put `startCommand` / `processes` in `vercel.json` (v0 schema rejects them)
+- ❌ Create a **second** TomorrowOS instance in `api/ws.ts`
+- ❌ Use `next build` / `next start` for Production
+- ❌ Put `startCommand` / `processes` in `vercel.json`
 
 **`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.
 
@@ -282,7 +288,7 @@ SDK behaviour (0.9.30+):
   "buildCommand": "npm run build",
   "functions": {
     "api/index.ts": {
-      "maxDuration": 800,
+      "maxDuration": 300,
       "memory": 1024,
       "includeFiles": "{cms-panel/**,brand.json,assets/**}"
     }
@@ -293,6 +299,8 @@ SDK behaviour (0.9.30+):
 }
 ```
 
+**`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”*.
+
 **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`.
@@ -376,10 +384,10 @@ If (1)+(2) pass but (3) fails → Function is serving HTTP only. Re-check Fluid,
 ```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": "cd preview && next dev -p 3000",
+    "dev:next": "next dev -p 3000",
     "start": "tsx server.ts",
     "build": "node -e \"process.exit(0)\""
   }
@@ -388,10 +396,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 `npm start`** = TomorrowOS Node with `server.listen`.
+- **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)
 
@@ -469,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)
 
@@ -552,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
 
@@ -570,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`**.
@@ -582,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`**.
@@ -603,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**
 
@@ -623,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).
 
@@ -633,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:
 
@@ -677,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:**
 
@@ -708,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).
@@ -762,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):**
@@ -807,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)
 
@@ -910,7 +945,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 but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy → internal TomorrowOS port |
+| 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 |
@@ -919,7 +954,9 @@ Tell the user:
 | WebSocket fails on Publish | Fluid off / static-only / Next as Production / no Function WS | Enable Fluid; Scheme A; test 101 upgrade |
 | Devices fail only on Preview | Next proxy cannot upgrade `wss` | Expected — pair on Publish URL |
 | Agent asked user to fill `TOMORROWOS_STORE` / `DATABASE_SSL` | Off-protocol | Agent must auto-set those after Neon/Supabase choice |
-| Agent 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 |
@@ -935,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) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "description": "TomorrowOS CMS server SDK - WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.30",
+    "@tomorrowos/sdk": "^0.9.31",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

package/templates/cms-starter-v0/README.md

@@ -1,14 +1,8 @@
 # TomorrowOS CMS Starter (Vercel / v0)
 
-This starter is for **Vercel Publish** and **v0**. It follows
-[Vercel Functions WebSockets](https://vercel.com/docs/functions/websockets):
-
-- **`cms-app.ts`** — shared `TomorrowOS.listen` + `export const server`
-- **`api/index.ts`** — Production Function: `export default server` (Fluid)
-- **`server.ts`** — local / Preview: same server (`npm start`)
-- **`cms-panel/`** — Control Panel static files (not `public/`)
-- **`preview/`** — Next.js shell for v0 Preview only
-- **`vercel.json`** — `fluid`, rewrites → `/api`, `maxDuration`
+- **Publish:** Fluid Function `api/index.ts` → `export default server` (WebSockets)
+- **Preview (v0):** root Next.js shell proxies HTTP → TomorrowOS on `:3001`
+- **`cms-panel/`** Control Panel static files (not `public/`)
 
 ## Scaffold
 
@@ -16,35 +10,26 @@ This starter is for **Vercel Publish** and **v0**. It follows
 npx @tomorrowos/sdk init my-cms --hosting v0
 ```
 
-## Local development
+## Local / v0 Preview
 
 ```bash
 npm install
 npm run dev
 ```
 
-Open `http://localhost:3000`. Pairing uses `ws://localhost:3000/` (root path).
-
-### v0-style Preview
-
-```bash
-npm run dev:preview
-```
+`npm run dev` starts **both**:
 
-Pair devices against the **Publish URL**, not Preview.
+1. TomorrowOS on `http://127.0.0.1:3001`
+2. Next on `http://localhost:3000` → proxies `/` to TomorrowOS
 
-## Production acceptance
+Open Preview at `http://localhost:3000` — you should see the Control Panel, **not** “Your v0 generation will show here”.
 
-1. `GET /status` → JSON  
-2. `GET /` → Control Panel  
-3. WebSocket upgrade on `/` or `/api` → **101** (not 200 HTML)
+## Production
 
-TV endpoint: `https://YOUR.vercel.app/` (players also try `/api` on `*.vercel.app`).
+Unchanged: `vercel.json` + `api/index.ts`. Acceptance: `/status` JSON + WebSocket **101**.
 
 ## Replit / Railway
 
-Use the default starter (unchanged Node listen, no `api/` Function):
-
 ```bash
 npx @tomorrowos/sdk init my-cms --hosting replit
 ```

package/templates/cms-starter-v0/app/[[...slug]]/route.ts

@@ -0,0 +1,89 @@
+/**
+ * v0 / local Preview shell — proxies all HTTP to TomorrowOS on :3001.
+ * Production Publish does NOT use this file; traffic goes to api/index.ts (Fluid).
+ */
+
+const INTERNAL =
+  process.env.TOMORROWOS_INTERNAL_URL || "http://127.0.0.1:3001";
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length"
+]);
+
+async function proxyToTomorrowOS(req: Request): Promise<Response> {
+  const incoming = new URL(req.url);
+  const target = new URL(incoming.pathname + incoming.search, INTERNAL);
+
+  const headers = new Headers();
+  req.headers.forEach((value, key) => {
+    if (!HOP_BY_HOP.has(key.toLowerCase())) headers.set(key, value);
+  });
+
+  const init: RequestInit = {
+    method: req.method,
+    headers,
+    redirect: "manual"
+  };
+
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    init.body = req.body;
+    // @ts-expect-error Node fetch duplex for streaming bodies
+    init.duplex = "half";
+  }
+
+  try {
+    const upstream = await fetch(target, init);
+    const outHeaders = new Headers();
+    upstream.headers.forEach((value, key) => {
+      if (!HOP_BY_HOP.has(key.toLowerCase())) outHeaders.set(key, value);
+    });
+    return new Response(upstream.body, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: outHeaders
+    });
+  } catch {
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>TomorrowOS Preview</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 40rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+    code { background: #f4f4f5; padding: 0.1em 0.35em; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>TomorrowOS Preview</h1>
+  <p>The Next.js shell is running, but TomorrowOS is not reachable at <code>${INTERNAL}</code>.</p>
+  <p>Start both processes:</p>
+  <pre><code>npm run dev</code></pre>
+  <p>(runs TomorrowOS on :3001 and Next on :3000). Publish / Production does not use this shell.</p>
+</body>
+</html>`;
+    return new Response(html, {
+      status: 502,
+      headers: { "content-type": "text/html; charset=utf-8" }
+    });
+  }
+}
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export const GET = proxyToTomorrowOS;
+export const POST = proxyToTomorrowOS;
+export const PUT = proxyToTomorrowOS;
+export const PATCH = proxyToTomorrowOS;
+export const DELETE = proxyToTomorrowOS;
+export const HEAD = proxyToTomorrowOS;
+export const OPTIONS = proxyToTomorrowOS;

package/templates/cms-starter-v0/app/layout.tsx

@@ -0,0 +1,15 @@
+/**
+ * Minimal layout so the App Router can boot for v0 Preview.
+ * All real UI is proxied from TomorrowOS via app/[[...slug]]/route.ts.
+ */
+export default function RootLayout({
+  children
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0 }}>{children}</body>
+    </html>
+  );
+}

package/templates/cms-starter-v0/next-env.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited — see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/cms-starter-v0/next.config.mjs

@@ -0,0 +1,15 @@
+/**
+ * Preview-only Next config. Production Publish ignores this
+ * (`vercel.json` → framework: null + api/index.ts Fluid Function).
+ *
+ * HTTP proxy lives in `app/[[...slug]]/route.ts` (not rewrites) so POST
+ * uploads and custom 502 pages work when TomorrowOS is down.
+ *
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+  // Do not add a root page.tsx that returns null — v0 shows
+  // "Your v0 generation will show here" instead of the Control Panel.
+};
+
+export default nextConfig;

package/templates/cms-starter-v0/package.json

@@ -1,35 +1,35 @@
 {
   "name": "my-cms",
-  "version": "0.9.30",
-  "description": "TomorrowOS CMS for Vercel / v0 Publish (Fluid Function + WebSockets + optional Next Preview).",
+  "version": "0.9.31",
+  "description": "TomorrowOS CMS for Vercel / v0 (Fluid Function Publish + Next Preview proxy).",
   "private": true,
   "type": "module",
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "dev": "tsx watch server.ts",
+    "dev": "npm run dev:preview",
     "dev:tomorrowos": "cross-env TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
-    "dev:next": "cd preview && next dev -p 3000",
-    "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
+    "dev:next": "next dev -p 3000",
+    "dev:preview": "concurrently -k -n cms,next -c cyan,magenta \"npm:dev:tomorrowos\" \"npm:dev:next\"",
     "start": "tsx server.ts",
     "build": "node -e \"process.exit(0)\"",
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.30",
+    "@tomorrowos/sdk": "^0.9.31",
+    "concurrently": "^9.1.2",
+    "cross-env": "^7.0.3",
     "dotenv": "^17.2.3",
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tsx": "^4.19.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "concurrently": "^9.1.2",
-    "cross-env": "^7.0.3",
-    "next": "^15.1.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
     "typescript": "^5.5.0"
   }
 }

package/templates/cms-starter-v0/tsconfig.json

@@ -9,5 +9,6 @@
     "noEmit": true,
     "types": ["node"]
   },
-  "include": ["server.ts"]
+  "include": ["server.ts", "cms-app.ts", "api/**/*.ts"],
+  "exclude": ["app", "node_modules", ".next"]
 }

package/templates/cms-starter-v0/vercel.json

@@ -6,7 +6,7 @@
   "buildCommand": "npm run build",
   "functions": {
     "api/index.ts": {
-      "maxDuration": 800,
+      "maxDuration": 300,
       "memory": 1024,
       "includeFiles": "{cms-panel/**,brand.json,assets/**}"
     }

package/templates/cms-starter-v0/preview/app/layout.tsx

@@ -1,11 +0,0 @@
-export default function RootLayout({
-  children
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}

package/templates/cms-starter-v0/preview/app/page.tsx

@@ -1,3 +0,0 @@
-export default function PreviewShellPage() {
-  return null;
-}

package/templates/cms-starter-v0/preview/next-env.d.ts

@@ -1,2 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />

package/templates/cms-starter-v0/preview/next.config.mjs

@@ -1,18 +0,0 @@
-const internalUrl =
-  process.env.TOMORROWOS_INTERNAL_URL || "http://127.0.0.1:3001";
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  async rewrites() {
-    return {
-      fallback: [
-        {
-          source: "/:path*",
-          destination: `${internalUrl}/:path*`
-        }
-      ]
-    };
-  }
-};
-
-export default nextConfig;

package/templates/cms-starter-v0/preview/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["dom", "dom.iterable", "esnext"],
-    "allowJs": true,
-    "skipLibCheck": true,
-    "strict": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "preserve",
-    "incremental": true,
-    "plugins": [{ "name": "next" }]
-  },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
-  "exclude": ["node_modules"]
-}