@tomorrowos/sdk 0.9.22 → 0.9.23

package/README.md

@@ -4,7 +4,7 @@
 
 **On Replit:** if the user asks to set up / configure a CMS interactively, follow **`REPLIT_SETUP.md`** instead (Q&A for store → media → `brand.json`).
 
-**On Vercel:** if the user asks to set up / configure a CMS interactively, follow **`VERCEL_SETUP.md`** (Supabase or Neon pooled Postgres, Cloudinary or Vercel Blob media, Fluid compute + WebSocket, `cms.hostingTarget: "vercel"`).
+**On Vercel:** if the user asks to set up / configure a CMS interactively, follow **`VERCEL_SETUP.md`** (Supabase or Neon pooled Postgres, Cloudinary or Vercel Blob media, v0 Preview Next proxy shell + **Publish = Node only**, Fluid compute + WebSocket, `cms.hostingTarget: "vercel"`).
 
 TomorrowOS is the open standard for digital signage. This SDK lets you build a CMS that controls Samsung Tizen, BrightSign, LG webOS, Android, ChromeOS, and Windows screens through a single unified API.
 
@@ -72,8 +72,9 @@ IF any step contradicts Vercel, adapt to settings that Vercel can accept.
 ```
 
 That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary** → **Vercel Blob** → local),
-branding (manual fields or **infer from a website URL**), enables Fluid compute for WebSockets, and sets
-`cms.hostingTarget` to `"vercel"`.
+branding (manual fields or **infer from a website URL**). Preview may use a thin **Next.js reverse proxy**;
+**Publish stays pure Node** `TomorrowOS.listen` (not Next). Cloudinary credentials are collected one-at-a-time
+(cloud name → API key → API secret). Sets `cms.hostingTarget` to `"vercel"`.
 
 ### Replit upgrade (existing CMS)
 

package/VERCEL_SETUP.md

@@ -5,7 +5,7 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.1` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> Protocol id: `vercel-setup/1.2` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
 
 ## User trigger (copy-paste)
 
@@ -17,6 +17,7 @@ Ask only the questions listed in VERCEL_SETUP.md, in order. Do not use LLM_PROMP
 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. 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).
 ```
 
 Alternate triggers:
@@ -28,7 +29,7 @@ When any of these fire, **ignore `REPLIT_SETUP.md` and `LLM_PROMPT.md`** for the
 
 ---
 
-## IRON RULE: long-lived Node + WebSocket (not classic static / short Functions)
+## IRON RULE: Preview vs Publish (dual runtime)
 
 > **This is the #1 deployability rule on Vercel. Non-negotiable.**
 
@@ -37,16 +38,35 @@ TomorrowOS CMS is **one Node process** that serves:
 - Browser Control Panel at `GET /` (`public/` via `staticRoot`)
 - Device **WebSocket** on the same origin (`https` → players use `wss`)
 
+### Production / Publish — Node only (no Next.js)
+
 | Required | Forbidden |
 |----------|-----------|
-| Single **Node HTTP server** entry (`tsx server.ts` / exported `http.Server` from `listen()`) | Next.js / Remix / static-only site as the CMS |
+| Single **Node HTTP server** entry (`tsx server.ts` / exported `http.Server` from `listen()`) | **Next.js as the Production CMS** (`next start`, Next App Router as the live app) |
 | **Fluid compute** enabled (needed for WebSockets on Vercel) | Classic short-lived serverless with no WebSocket / no Fluid |
 | Durable store = **Postgres** (Supabase or Neon, pooled URL) | **SQLite / `data/*.db` as production store** on Vercel (ephemeral filesystem) |
 | Media = **Cloudinary** or **Vercel Blob** (durable HTTPS URLs) | Relying on local `public/uploads` alone for production fleets |
 | Env vars in **Vercel Project → Settings → Environment Variables** | Committing passwords / API secrets / `.env` with secrets |
 | `cms.hostingTarget`: `"vercel"` in `brand.json` | Creating `.replit` / Replit artifact files |
 
-**Do not** scaffold a leftover Next.js app “and put TomorrowOS beside it.” Remove Next scaffolds so TomorrowOS `server.ts` is the sole app.
+**Publish / Production Deploy** must run **`TomorrowOS.listen(...)`** directly. Do **not** put Next.js in front of Production traffic.
+
+### Preview (v0 / Vercel Agent sandbox) — Next.js shell allowed
+
+v0 Preview is often a **Next.js runtime** hardwired to `next dev`. A raw `tsx server.ts` may listen successfully while Preview still shows a blank page, because the sandbox intercepts the public port with Next before requests reach TomorrowOS.
+
+**For Preview only**, you **must** keep a thin Next.js host that **reverse-proxies** HTTP to TomorrowOS on an **internal** port.
+
+| Preview requirement | Detail |
+|---------------------|--------|
+| Next.js remains the Preview host | Satisfies v0 / sandbox expectations |
+| TomorrowOS on internal port | e.g. `TOMORROWOS_INTERNAL_PORT=3001` (not the public Preview port) |
+| Transparent HTTP reverse proxy | Next route/middleware forwards `/` (and Control Panel paths) → `http://127.0.0.1:3001` |
+| Start both processes in Preview | Next + `tsx server.ts` (or a `dev:preview` script that starts both) |
+
+**Preview WebSocket note:** HTTP proxy is enough for Control Panel HTML/API smoke checks. Device `wss` pairing may not work through a Next proxy in Preview — that is acceptable. **Pair devices against the Production Publish URL**, not v0 Preview.
+
+**Do not** replace TomorrowOS with a Next-only CMS. Next is a **Preview adapter**, not the product.
 
 ---
 
@@ -60,7 +80,7 @@ Ask **only** these questions, in **this exact order**:
 | 2 | **Question 2** — Media storage (Cloudinary → Vercel Blob → local) | Always (after Q1) |
 | 3 | **Question 3** — Brand / TomorrowOS look (`brand.json` only) | Always last |
 
-**That is the complete list.** Do **not** ask how many screens / devices. There is **no** “Question 2b” — Cloudinary / Vercel Blob credentials stay **inside Question 2**.
+**That is the complete list.** Do **not** ask how many screens / devices.
 
 If the user says “just set it up, don’t ask questions,” respond:
 
@@ -73,7 +93,7 @@ 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.
-2. **One question at a time** (exception: after Cloudinary or Vercel Blob choice, immediately collect the required env vars in the same Question 2).
+2. **One question / one credential at a time.** For Cloudinary: ask **cloud name**, then **API key alone**, then **API secret alone** — never one message that mixes key + secret.
 3. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, or brand colours.
 4. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** (or `NEON_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).
@@ -81,9 +101,10 @@ Then ask **Question 1**.
 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 WebSockets. Confirm Project settings after scaffold.
-11. **Export the HTTP server** Vercel can capture: `const server = tomorrowos.listen(...); export default server;` (or equivalent). Do not export only the `TomorrowOS` class instance unless the platform documents another capture path.
-12. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/`). Do not run a long test suite.
+10. **Enable Fluid compute** for Production WebSockets. Confirm Project settings after scaffold.
+11. **Production:** export the HTTP server Vercel can capture: `const server = tomorrowos.listen(...); export default server;` (or equivalent). **Do not** make `next start` the Production entrypoint.
+12. **Preview:** if the environment is v0 / Next-hardwired, install the Next reverse-proxy shell (see **Preview adapter**). Do not leave Preview broken.
+13. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/`). Do not run a long test suite.
 
 **Question order:** Q1 → Q2 → Q3 → execution checklist.
 
@@ -91,12 +112,13 @@ Then ask **Question 1**.
 
 ## Runtime & Vercel deploy rules (mandatory)
 
-### Runtime
+### Production runtime (Publish)
 
 - Serve with **`tsx server.ts`** (or compiled Node that still calls `TomorrowOS.listen` with `staticRoot`).
 - Keep **`@tomorrowos/sdk`** and put **`tsx` in `dependencies`** (not only `devDependencies`) if production runs via `tsx`.
 - Node **20+**.
 - **Do not** replace the SDK with a hand-rolled server that drops WebSocket upgrades.
+- **Forbidden as the Production Deploy entrypoint:** `next start`, static export only, or any command that does not start `TomorrowOS.listen(...)`.
 
 ### Expected `package.json` scripts
 
@@ -104,14 +126,21 @@ Then ask **Question 1**.
 {
   "scripts": {
     "dev": "tsx watch server.ts",
-    "start": "tsx 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",
+    "start": "tsx server.ts",
+    "build": "echo \"Production is Node — no Next production build required\""
   }
 }
 ```
 
-**Forbidden as the Deploy entrypoint:** `next start`, static export only, or any command that does not start `TomorrowOS.listen(...)`.
+Adapt script names / process runners as needed. **Invariant:**
+
+- **`npm start` / Production** = TomorrowOS Node only.
+- **Preview / v0** = Next on public port + TomorrowOS on internal port + proxy.
 
-### Minimal dependencies
+### Minimal dependencies (Production)
 
 ```json
 {
@@ -137,9 +166,11 @@ Then ask **Question 1**.
 
 Use the latest published `@tomorrowos/sdk` when scaffolding (do not invent versions).
 
-Add `@vercel/blob` to `dependencies` only when the user chooses **Vercel Blob** in Question 2.
+Add `@vercel/blob` only when the user chooses **Vercel Blob** in Question 2.
 
-### `server.ts` pattern (Vercel-adapted)
+For Preview shell only, add as needed: `next`, `react`, `react-dom`, and a process runner (`concurrently` or equivalent). These must **not** become the Production CMS.
+
+### `server.ts` pattern (Vercel-adapted — Production)
 
 ```ts
 import "dotenv/config";
@@ -162,8 +193,13 @@ const store = createTomorrowOSStore({
 
 const tomorrowos = new TomorrowOS({ brand, store });
 
+const port =
+  Number(process.env.TOMORROWOS_INTERNAL_PORT) ||
+  Number(process.env.PORT) ||
+  3000;
+
 const server = tomorrowos.listen({
-  port: Number(process.env.PORT) || 3000,
+  port,
   host: "0.0.0.0",
   staticRoot: join(__dirname, "public")
 });
@@ -172,9 +208,37 @@ const server = tomorrowos.listen({
 export default server;
 ```
 
+- **Production:** `PORT` from Vercel → TomorrowOS listens on that port (no Next).
+- **Preview:** set `TOMORROWOS_INTERNAL_PORT=3001` (or similar) so Next can own `:3000` and proxy inward.
+
 Load env with `dotenv` for local/`vercel dev`. On production Deploy, Vercel injects Environment Variables natively.
 
-### `vercel.json` (recommended minimum)
+### Preview adapter (v0 / Next reverse proxy) — required when Preview is Next-hardwired
+
+Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs “listening”). Then:
+
+1. Keep a **minimal** Next app (App Router or Pages — whichever the sandbox expects).
+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:
+
+```ts
+// Example: app/api/tomorrowos-proxy/[...path]/route.ts or a rewrite + route handler
+// Forward method, headers, and body to http://127.0.0.1:3001/<path>
+// Return the upstream status, headers, and body to the browser.
+```
+
+Preferred UX: proxy **`/`** itself (rewrites) so the Preview URL shows the Control Panel at `/`, not only under `/api/...`.
+
+4. Start **both** processes for Preview (`dev:preview` pattern above).
+5. Document in the final summary: **Preview = Next shell + proxy; Publish = Node only.**
+
+**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`.
+
+### `vercel.json` (recommended minimum — Production)
 
 Adapt to the project’s current Vercel Node-server / Fluid conventions. At minimum ensure:
 
@@ -186,23 +250,25 @@ Adapt to the project’s current Vercel Node-server / Fluid conventions. At mini
 
 Also:
 
-1. Project → **Fluid compute** enabled (required for WebSockets).
-2. Framework Preset: **Other** (or Node) — **not** Next.js unless wrapping is intentional and still exposes TomorrowOS `listen()`.
-3. Install / Start commands must end in running the CMS server (e.g. `npm run start` or Vercel’s detected `server.ts` entry).
+1. Project → **Fluid compute** enabled (required for WebSockets on Publish).
+2. Framework Preset for **Production:** **Other** (or Node) — **not** Next.js as the live CMS.
+3. Install / Start commands for **Production** must end in running the CMS Node server (e.g. `npm run start` → `tsx server.ts`).
 4. Do **not** enable “Output Directory” static-only hosting for this CMS.
+5. If the project also contains a Next Preview shell, configure Vercel so **Production Deploy ignores Next as the app** (Node `server.ts` / `export default server` remains the capture path). Document any dashboard setting you change.
 
-If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a single long-lived Node HTTP server with WebSocket upgrade on `/`**. Document the adaptation in the final summary.
+If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a single long-lived Node HTTP server with WebSocket upgrade on `/` for Production**. Document the adaptation in the final summary.
 
 ### WebSocket / multi-instance note
 
 - Device sockets are pinned to **one** function/instance. TomorrowOS device maps are **in-memory**.
 - For large fleets on multi-instance Vercel, prefer **one stable instance / region**, or accept that reconnects may land on another instance until the product adds shared presence (out of scope for this setup).
 - Always use **Postgres** (Supabase or Neon) so pairings/playlists survive cold starts and deploys.
+- **Pair TVs to the Production HTTPS origin**, not the v0 Preview URL.
 
 ### What not to create
 
 - ❌ `.replit`, `.replit-artifact`
-- ❌ Next.js `app/` / `pages/` CMS
+- ❌ Next.js as the **Production** CMS (App Router replacing TomorrowOS)
 - ❌ Separate “API project” without the Control Panel
 - ❌ Committing database passwords, Cloudinary secrets, or Blob tokens
 
@@ -309,16 +375,47 @@ Only proceed after the user explicitly confirms.
 >
 > Reply with **1**, **2**, or **3** (or “Cloudinary” / “Vercel Blob” / “local”).
 
-### Step B — If **1 / Cloudinary** (same Question 2)
+### Step B — If **1 / Cloudinary** (same Question 2 — sequential prompts)
 
-Immediately collect and store as **Vercel Environment Variables**:
+> **Critical UX rule:** Collect Cloudinary credentials in **separate messages**. Never ask for API key and API secret in the same message or the same form field group.
 
-- `CLOUDINARY_CLOUD_NAME`
-- `CLOUDINARY_API_KEY`
-- `CLOUDINARY_API_SECRET`
-- Optional: `CLOUDINARY_FOLDER` (e.g. `tomorrowos`)
+#### B1 — Cloud name (ask alone)
 
-Do **not** invent placeholders. Do **not** proceed to Question 3 until the three required vars exist. Do **not** run a formal Cloudinary upload test unless the user asks.
+**Ask exactly:**
+
+> Paste your Cloudinary **Cloud name** only (`CLOUDINARY_CLOUD_NAME`).  
+> Find it at [cloudinary.com/console](https://cloudinary.com/console) → Dashboard.
+
+Save as Vercel Env Var `CLOUDINARY_CLOUD_NAME`. Do **not** ask for key or secret yet.
+
+#### B2 — API key (ask alone — after B1 is saved)
+
+**Ask exactly:**
+
+> Paste your Cloudinary **API Key** only (`CLOUDINARY_API_KEY`).  
+> Do not paste the API Secret in this step.
+
+Save as Vercel Env Var `CLOUDINARY_API_KEY`. Do **not** ask for the secret in this message.
+
+#### B3 — API secret (ask alone — after B2 is saved)
+
+**Ask exactly:**
+
+> Paste your Cloudinary **API Secret** only (`CLOUDINARY_API_SECRET`).  
+> This is the last Cloudinary credential.
+
+Save as Vercel Env Var `CLOUDINARY_API_SECRET`.
+
+Optional fourth message (only if useful):
+
+> Optional: Cloudinary folder name (`CLOUDINARY_FOLDER`, e.g. `tomorrowos`). Press Enter to skip.
+
+**You must then:**
+
+1. Confirm all three required Env Vars exist: `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`.
+2. **Do not** invent placeholders.
+3. **Do not** proceed to Question 3 until all three exist.
+4. **Do not** run a formal Cloudinary upload test unless the user asks.
 
 The SDK auto-detects these env vars.
 
@@ -430,7 +527,7 @@ 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 deployed HTTPS origin (player maps `https://` → `wss://`).
+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://`).
 
 ---
 
@@ -446,11 +543,12 @@ npx @tomorrowos/sdk@latest init .
 
 Then:
 
-1. Remove leftover Next.js / other frameworks so TomorrowOS is sole app.
-2. Apply Vercel-adapted `server.ts` (**export `listen()` HTTP server**).
-3. Add/adjust `vercel.json` with **`fluid: true`** (or enable Fluid in the dashboard).
-4. Do **not** add `.replit*`.
-5. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
+1. Keep TomorrowOS `server.ts` as the **Production** app (**export `listen()` HTTP server**).
+2. If the environment is **v0 / Next Preview**, add the **Preview adapter** (Next shell + reverse proxy + internal TomorrowOS port). Do **not** make Next the Production CMS.
+3. Add/adjust `vercel.json` with **`fluid: true`** (or enable Fluid in the dashboard) for Publish.
+4. Ensure Production start command is **`npm run start` → `tsx server.ts`** (or equivalent Node), **not** `next start`.
+5. Do **not** add `.replit*`.
+6. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
 
 ### B. Environment Variables (Vercel dashboard + local)
 
@@ -460,9 +558,12 @@ Then:
 | `DATABASE_URL` | If Q1 = Neon | **Pooled** Neon string |
 | `TOMORROWOS_STORE` | Yes | `supabase`, `postgres`, or `sqlite` |
 | `DATABASE_SSL` | Yes (typical) | `true` |
-| `CLOUDINARY_*` | If Q2 = Cloudinary | Three keys |
+| `CLOUDINARY_CLOUD_NAME` | If Q2 = Cloudinary | Collected alone (B1) |
+| `CLOUDINARY_API_KEY` | If Q2 = Cloudinary | Collected alone after cloud name (B2) |
+| `CLOUDINARY_API_SECRET` | If Q2 = Cloudinary | Collected alone after API key (B3) |
 | `BLOB_READ_WRITE_TOKEN` | If Q2 = Vercel Blob | From Vercel Blob store |
-| `PORT` | Optional | Vercel injects as needed |
+| `TOMORROWOS_INTERNAL_PORT` | Preview only | e.g. `3001` when Next owns `:3000` |
+| `PORT` | Optional | Vercel injects for Production |
 
 Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit secrets.
 
@@ -471,34 +572,46 @@ Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit se
 ```bash
 npm install
 npm run start
-# or: vercel dev
+# Preview / v0: npm run dev:preview  (Next + TomorrowOS internal)
 ```
 
 Confirm logs: `[TomorrowOS] listening on http://0.0.0.0:…`  
-Confirm browser: Control Panel at `/`.
+Confirm browser:
 
-### D. Deploy
+- **Preview:** Control Panel visible through the Next proxy at `/`
+- **Production start:** Control Panel served directly by TomorrowOS at `/`
+
+### D. Deploy (Publish — Node only)
 
 ```bash
 vercel --prod
 # or git push → Vercel Git integration
 ```
 
+Before finishing, verify Production settings:
+
+1. Start / entry = **Node `TomorrowOS.listen`** (`npm run start` / exported `server`)
+2. **Not** `next start` as Production
+3. Fluid compute on
+4. Env Vars present for Production environment
+
 Tell the user:
 
-- **Control Panel:** `https://YOUR-PROJECT.vercel.app`
+- **Control Panel (Publish):** `https://YOUR-PROJECT.vercel.app`
 - **TV CMS endpoint:** same HTTPS origin (players use `wss://`)
+- **Preview:** Next shell is for v0 only — do not pair devices to Preview
 
 ### E. Minimal verification only
 
 **Do:**
 
-1. Control Panel HTML at `/`
-2. Server status: Media OK when Cloudinary or Blob configured
-3. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
-4. Fluid compute on
+1. Preview: Control Panel HTML at `/` (via Next proxy if applicable)
+2. Publish: Control Panel HTML at `/` from **Node** TomorrowOS
+3. Server status: Media OK when Cloudinary or Blob configured
+4. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
+5. Fluid compute on for Production
 
-**Do not block** on long WebSocket/device pairing tests unless the user asks.
+**Do not block** on long WebSocket/device pairing tests unless the user asks. Prefer pairing against **Publish**, not Preview.
 
 ---
 
@@ -506,12 +619,15 @@ Tell the user:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Preview blank but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy → internal TomorrowOS port |
+| Preview works, Publish broken / Next-only | Production still on Next | Switch Production entry to `tsx server.ts` / `export default server` |
 | `ENETUNREACH` / IPv6 / `:5432` | Direct Postgres URL | Use **pooled** URL (Supabase `:6543` or Neon pooler) |
 | Control Panel OK, devices never stay paired after restart | SQLite / ephemeral disk | Use Supabase or Neon |
 | Uploads break / broken thumbs in prod | Local `public/uploads` | Cloudinary or Vercel Blob |
 | Blob uploads 401 / missing token | Blob not linked | Vercel Storage → Blob + `BLOB_READ_WRITE_TOKEN` |
-| WebSocket fails / devices drop immediately | Fluid off / static-only / Next wrapper | Enable Fluid; sole Node `listen()` server |
-| Agent created Next.js + TomorrowOS | Wrong scaffold | Remove Next; keep cms-starter |
+| WebSocket fails on Publish | Fluid off / static-only / Next as Production | Enable Fluid; sole Node `listen()` for Publish |
+| Devices fail only on Preview | Next proxy cannot upgrade `wss` | Expected — pair on Publish URL |
+| Agent mixed Cloudinary key+secret in one prompt | Violated Step B | Re-ask key alone, then secret alone |
 | Secrets in git | Mistake | Rotate keys; move to Vercel Env Vars |
 | Replit files present | Copied wrong protocol | Delete `.replit*`; use this file |
 | Brand colours wrong from URL | SPA / blocked fetch | Manual Option B for colours + logo |
@@ -527,7 +643,8 @@ Tell the user:
 | `hostingTarget` | `"here"` | `"vercel"` |
 | Database | Supabase (primary) | Supabase **or Neon** (pooled); SQLite demo only |
 | Media | Cloudinary or Replit Object Storage | Cloudinary **or Vercel Blob** |
-| WebSocket | Long-lived Node (Autoscale) | Fluid compute + Node server export |
+| Preview | Replit Preview / Autoscale Node | **Next shell + proxy** when v0 hardwires Next |
+| Publish | Long-lived Node | **Node `TomorrowOS.listen` only** (not Next) |
 | Brand from URL | Not in Replit protocol | **Option A** in Question 3 — infer from website |
 
 ---
@@ -536,12 +653,19 @@ Tell the user:
 
 After setup, report:
 
-1. **Live URL** (Production)
-2. **Env Vars set** (names only — never values)
-3. **Store:** Supabase pooler / Neon pooled / SQLite (with warning)
-4. **Media:** Cloudinary, Vercel Blob, or local (with warning)
-5. **Brand:** name + `hostingTarget: vercel` (+ note if derived from website URL)
-6. **Adaptations from Replit protocol:** list (e.g. skipped `.replit`, exported HTTP server, Fluid, pooler URL, Blob bridge)
-7. **Open action:** if Database still ERROR, paste the pooler instruction again
+1. **Live URL** (Production Publish)
+2. **Preview note:** Next proxy shell used / not needed
+3. **Env Vars set** (names only — never values)
+4. **Store:** Supabase pooler / Neon pooled / SQLite (with warning)
+5. **Media:** Cloudinary, Vercel Blob, or local (with warning)
+6. **Brand:** name + `hostingTarget: vercel` (+ note if derived from website URL)
+7. **Runtime split:** Preview = … ; Publish = Node TomorrowOS (confirm **not** Next)
+8. **Open action:** if Database still ERROR, paste the pooler instruction again
+
+Protocol complete when:
+
+- **Preview** shows the Control Panel at `/` (via Next proxy if required), **and**
+- **Publish** is configured for pure Node `TomorrowOS.listen` with Fluid, **and**
+- Q1–Q3 configuration is saved
 
-Protocol complete when the Control Panel renders at `/` on the deployed (or local) server and Q1–Q3 configuration is saved — even if a sandbox DB probe still flakes **after** the pooled URL is correctly set for Production.
+— even if a sandbox DB probe still flakes **after** the pooled URL is correctly set for Production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "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.22",
+  "version": "0.9.23",
   "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.22",
+    "@tomorrowos/sdk": "^0.9.23",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },