@tomorrowos/sdk 0.9.21 → 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`** (Session pooler Supabase URL, Fluid compute + WebSocket, Cloudinary, `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.
 
@@ -71,8 +71,10 @@ Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
 IF any step contradicts Vercel, adapt to settings that Vercel can accept.
 ```
 
-That wizard requires the Supabase **Session pooler** URL, prefers Cloudinary,
-enables Fluid compute for WebSockets, and sets `cms.hostingTarget` to `"vercel"`.
+That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary** → **Vercel Blob** → local),
+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.0` — 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)
 
@@ -15,8 +15,9 @@ When a human pastes a prompt like this, **read this file and start Question 1 im
 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.
 If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation).
-After all setup questions are answered (including Cloudinary Env Vars if you chose Cloudinary), configure and deploy — minimal verification only (Control Panel at /). Prefer Supabase Session pooler URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when the pooler URL is configured for production.
+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 = **Supabase Postgres** (pooler URL) | **SQLite / `data/*.db` as production store** on Vercel (ephemeral filesystem) |
-| Media = **Cloudinary** (recommended) or other durable HTTPS URLs | Relying on local `public/uploads` alone for production fleets |
-| Env vars in **Vercel Project → Settings → Environment Variables** | Committing passwords / Cloudinary secrets / `.env` with secrets |
+| 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.
 
 ---
 
@@ -56,15 +76,15 @@ Ask **only** these questions, in **this exact order**:
 
 | Step | Section | When |
 |------|---------|------|
-| 1 | **Question 1** — Supabase **Session pooler** connection string | Always |
-| 2 | **Question 2** — Media storage (+ Cloudinary Env Vars if chosen) | Always (after Q1) |
+| 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 |
 
-**That is the complete list.** Do **not** ask how many screens / devices. There is **no** “Question 2b” — Cloudinary 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:
 
-> I need a few quick answers from VERCEL_SETUP.md (Supabase Session pooler URL, media storage — plus Cloudinary credentials if you choose Cloudinary — 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, and branding). It takes about a minute and ensures the CMS works on Vercel.
 
 Then ask **Question 1**.
 
@@ -73,17 +93,18 @@ 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 choice, immediately collect the three Cloudinary env vars in the same Question 2).
-3. **Do not invent** Cloudinary credentials, Supabase URLs, or brand colours.
-4. **Prefer `SUPABASE_URL`** for Supabase (same as Replit). `DATABASE_URL` may be used as fallback on Vercel, but document one canonical name — prefer **`SUPABASE_URL`**.
-5. **Always prefer the Supabase Session pooler URL** (port **6543**, host like `*.pooler.supabase.com`). Direct `db.*.supabase.co:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
+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).
 6. **Prefer `npx @tomorrowos/sdk init`** (or `templates/cms-starter`) as the seed. 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.** Configure Supabase for pairing/playlists. Keep `sqlitePath` only as a 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.
+9. **SQLite is not a production store on Vercel.** Offer it only as option **3** after explicit warning. Keep `sqlitePath` as local-dev fallback in `createTomorrowOSStore`.
+10. **Enable Fluid compute** for Production WebSockets. Confirm Project settings after scaffold.
+11. **Production:** export the HTTP server Vercel can capture: `const server = tomorrowos.listen(...); export default server;` (or equivalent). **Do not** make `next start` the Production entrypoint.
+12. **Preview:** if the environment is v0 / Next-hardwired, install the Next reverse-proxy shell (see **Preview adapter**). Do not leave Preview broken.
+13. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/`). Do not run a long test suite.
 
 **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,7 +166,11 @@ Then ask **Question 1**.
 
 Use the latest published `@tomorrowos/sdk` when scaffolding (do not invent versions).
 
-### `server.ts` pattern (Vercel-adapted)
+Add `@vercel/blob` only when the user chooses **Vercel Blob** in Question 2.
+
+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";
@@ -150,15 +183,23 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const brand = JSON.parse(readFileSync(join(__dirname, "brand.json"), "utf8"));
 
 const store = createTomorrowOSStore({
-  // Prefer SUPABASE_URL. On Vercel use the Session pooler connection string.
-  databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL,
+  // Supabase: SUPABASE_URL (pooler). Neon: DATABASE_URL (pooled).
+  databaseUrl:
+    process.env.SUPABASE_URL ||
+    process.env.NEON_DATABASE_URL ||
+    process.env.DATABASE_URL,
   sqlitePath: join(__dirname, "data", "tomorrowos.db") // local/dev fallback only
 });
 
 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")
 });
@@ -167,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:
 
@@ -181,35 +250,53 @@ 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 **Supabase** so pairings/playlists survive cold starts and deploys.
+- 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 `SUPABASE_URL` passwords or Cloudinary secrets
+- ❌ Committing database passwords, Cloudinary secrets, or Blob tokens
 
 ---
 
-## Question 1 — Supabase Session pooler (always)
+## Question 1 — Database (always)
 
-> Always configure Supabase for Vercel. Do **not** ask screen counts.
+> **Do not** ask screen counts. Present all three options; recommend **Supabase** for Vercel fleets.
+
+### Step A — Ask storage choice
+
+**Ask exactly:**
+
+> Which database should TomorrowOS use on Vercel?
+>
+> **1. Supabase Postgres (recommended)** — durable pairing/playlists; use the **Session pooler** URL (`*.pooler.supabase.com:6543`).
+>
+> **2. Neon Postgres** — serverless Postgres native to Vercel; use Neon’s **pooled** connection string from the Neon dashboard (not the direct un-pooled host for serverless).
+>
+> **3. SQLite (`data/tomorrowos.db`)** — **demo / local only on Vercel.** The filesystem is ephemeral; pairings and playlists will not survive redeploys. Only choose this if you understand the limitation.
+>
+> Reply with **1**, **2**, or **3** (or “Supabase” / “Neon” / “SQLite”).
+
+### Step B — If **1 / Supabase**
 
 **Ask exactly:**
 
-> Paste your Supabase Postgres **Session pooler** connection string. I will store it as the Vercel Environment Variable **`SUPABASE_URL`**.
+> Paste your Supabase Postgres connection string. I will store it as the Vercel Environment Variable **`SUPABASE_URL`**.
 >
 > In Supabase: **Project Settings → Database → Connection string → Connection pooling** (Session mode).  
 > Preferred shape:  
@@ -230,9 +317,45 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 4. **Do not** commit the real connection string.
 5. **Configuration over probing:** if local/`vercel dev` still shows `ENETUNREACH` / IPv6 errors, verify the string is the **pooler** (`pooler.supabase.com` + `:6543`). Treat remaining sandbox DNS issues as non-fatal when Production deploy Env Vars are correct — but **do** fix an obvious direct `:5432` URL before finishing.
 
-If the user refuses Supabase, warn that Vercel cannot use durable SQLite for fleets, then only continue with SQLite after explicit confirmation (local/demo only).
+### Step C — If **2 / Neon**
+
+**Ask exactly:**
+
+> Paste your **Neon pooled** Postgres connection string. I will store it as **`DATABASE_URL`** (or `NEON_DATABASE_URL` if you prefer — wire whichever you set in `server.ts`).
+>
+> In Neon: **Dashboard → Connection details → Pooled connection** (enable pooling).  
+> Typical shape:  
+> `postgresql://[user]:[password]@[endpoint].pooler.[region].aws.neon.tech/[dbname]?sslmode=require`
+>
+> **Do not** use the direct (non-pooled) connection string for Vercel serverless unless Neon docs explicitly say otherwise for your plan.
+>
+> Confirm SSL (`sslmode=require`) is on (usually **yes**).
+
+**You must then:**
+
+1. Set Vercel Env Vars:
+   - `DATABASE_URL=<pooled Neon string>` (or `NEON_DATABASE_URL` + read it in `server.ts`)
+   - `TOMORROWOS_STORE=postgres`
+   - `DATABASE_SSL=true` (unless user explicitly disables SSL)
+2. Wire `server.ts` — `createTomorrowOSStore` uses `PostgresStore` for `postgres` / `supabase` drivers.
+3. **Do not** commit the real connection string.
+4. Same pooler guidance as Supabase: if you see `ENETUNREACH` on `:5432`, switch to Neon’s **pooled** URL.
+
+### Step D — If **3 / SQLite**
+
+**Warn exactly before continuing:**
+
+> SQLite on Vercel is **not** suitable for production fleets — data in `data/tomorrowos.db` is lost when the instance is recycled or redeployed. Continue only for a quick demo.
+
+Only proceed after the user explicitly confirms.
 
-**Later in Question 3:** set `cms.hostingTarget` to **`"vercel"`**.
+**You must then:**
+
+1. Set `TOMORROWOS_STORE=sqlite` (or omit `DATABASE_URL` / `SUPABASE_URL` so the factory defaults to SQLite).
+2. Keep `sqlitePath` in `server.ts` for `data/tomorrowos.db`.
+3. Warn again in the final summary that they should move to Supabase or Neon for real devices.
+
+**Later in Question 3:** set `cms.hostingTarget` to **`"vercel"`** (all Q1 branches).
 
 ---
 
@@ -244,30 +367,91 @@ If the user refuses Supabase, warn that Vercel cannot use durable SQLite for fle
 
 > How should playlist media (images/videos) be stored?
 >
-> **Recommended on Vercel: Cloudinary** — durable public HTTPS URLs (`https://res.cloudinary.com/...`). Local `public/uploads` is ephemeral on serverless/filesystem deploys and is a poor fleet default.
+> **1. Cloudinary (recommended)** — durable public HTTPS URLs (`https://res.cloudinary.com/...`). Works out of the box with `@tomorrowos/sdk` auto-detection.
 >
-> Alternatives:
-> - **Local disk only** — `public/uploads` (OK for quick local tests; **not** for production Vercel fleets).
+> **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.
 >
-> Do you want me to set up **Cloudinary**? (yes / no)
+> **3. Local disk only** — `public/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
+>
+> Reply with **1**, **2**, or **3** (or “Cloudinary” / “Vercel Blob” / “local”).
+
+### Step B — If **1 / Cloudinary** (same Question 2 — sequential prompts)
+
+> **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.
+
+#### B1 — Cloud name (ask alone)
+
+**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)
 
-### Step B — If YES / Cloudinary (same Question 2)
+**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:**
 
-Immediately collect and store as **Vercel Environment Variables**:
+> Paste your Cloudinary **API Secret** only (`CLOUDINARY_API_SECRET`).  
+> This is the last Cloudinary credential.
 
-- `CLOUDINARY_CLOUD_NAME`
-- `CLOUDINARY_API_KEY`
-- `CLOUDINARY_API_SECRET`
-- Optional: `CLOUDINARY_FOLDER` (e.g. `tomorrowos`)
+Save as Vercel Env Var `CLOUDINARY_API_SECRET`.
 
-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.
+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.
 
-### If NO — local uploads
+### Step C — If **2 / Vercel Blob** (same Question 2)
+
+**Ask exactly:**
+
+> I will enable **Vercel Blob** for media uploads.
+>
+> 1. In the Vercel project: **Storage → Create → Blob** (or link an existing Blob store to this project).
+> 2. Confirm **`BLOB_READ_WRITE_TOKEN`** is available (Vercel usually injects it when Blob is linked).
+>
+> Paste the token only if it is not already set in your project Env Vars. Do you already have Blob linked on this Vercel project? (yes / no)
+
+**You must then:**
+
+1. Set Vercel Env Var: `BLOB_READ_WRITE_TOKEN=<token>` (if not auto-injected).
+2. `npm install @vercel/blob` (add to `dependencies`).
+3. Wire uploads so media returns **absolute HTTPS Blob URLs** stored in `uploaded_assets` (players need stable public URLs).
+   - The SDK **natively auto-detects Cloudinary** today. For Vercel Blob, add a thin upload bridge in the CMS project (e.g. custom route or middleware that calls `put()` from `@vercel/blob` and persists the returned `url` the same way Cloudinary URLs are stored).
+   - Minimum pattern:
+
+```ts
+import { put } from "@vercel/blob";
+
+// On upload: const blob = await put(filename, body, { access: "public", token: process.env.BLOB_READ_WRITE_TOKEN });
+// Store blob.url in uploaded_assets — same shape as Cloudinary secure URLs.
+```
+
+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).
+
+### 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 is strongly preferred for Vercel.
+2. Warn clearly: files may vanish on redeploy; players need stable HTTPS URLs — Cloudinary or Vercel Blob is strongly preferred for Vercel.
 
 ---
 
@@ -275,10 +459,17 @@ The SDK auto-detects these env vars.
 
 > Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or `server.ts` store wiring beyond what Q1–Q2 already required.
 
+### Step A — Ask branding input
+
 **Ask exactly:**
 
-> Let’s brand your TomorrowOS experience. Please provide:
+> Let’s brand your TomorrowOS experience. You can answer in either way:
+>
+> **Option A — Website URL only**  
+> Paste **one public website URL** (your company / venue site). I will infer colours, fonts, name, tagline, and logo from that page and write `brand.json` to match its look.
 >
+> **Option B — Manual fields**  
+> Provide:
 > 1. **Product / venue name**
 > 2. **Tagline** (optional)
 > 3. **Primary colour** (hex, e.g. `#FF8A3D`)
@@ -287,12 +478,33 @@ The SDK auto-detects these env vars.
 > 6. **Secondary / accent colour** (hex, optional)
 > 7. **Logo** — upload SVG/PNG into the project, or a URL I can fetch into `./assets/`
 
-Then write `brand.json` (validate mentally against `brand.schema.json`). Minimum:
+### Step B — If the user gives **only a website URL** (Option A)
+
+**You must:**
+
+1. **Fetch and inspect** the page (HTTP GET the URL; follow one redirect if needed). Do not invent colours.
+2. **Derive branding** using this priority order:
+   - **Name:** `<title>`, `og:site_name`, or prominent header / logo `alt` text (trim to ≤ 60 chars).
+   - **Tagline:** `meta[name="description"]`, `og:description`, or first hero subtitle (≤ 120 chars).
+   - **Primary colour:** `meta[name="theme-color"]`, CSS `--primary` / `--brand` variables, or dominant accent from linked stylesheets / inline styles (convert to `#RRGGBB`).
+   - **Background colour:** `body` / `:root` background (default `#FAFAF9` if light site).
+   - **Text colour:** main body text colour (default `#0A0908` if light site).
+   - **Secondary colour:** muted border / secondary button colour, or a tint of the primary.
+   - **Font:** first `font-family` on `body` (strip quotes; default `Inter` if generic system stack).
+   - **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.
+3. **Contrast check:** if background is dark, set `activationScreen.theme` to `"dark"` and add `logoPathOnDark` when a light logo variant exists.
+4. **Infer `cms.useCase`** from page content when obvious (restaurant / retail / corporate / etc.); otherwise `"other"`.
+5. **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. 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.
+
+### Step C — Write `brand.json`
+
+Validate mentally against `brand.schema.json`. Minimum:
 
 ```json
 {
-  "name": "<user name>",
-  "tagline": "<user tagline or Digital signage>",
+  "name": "<user name or site-derived name>",
+  "tagline": "<tagline or Digital signage>",
   "targetPlatforms": ["tizen"],
   "primaryColor": "#FF8A3D",
   "secondaryColor": "#F5F3EF",
@@ -315,7 +527,7 @@ Then write `brand.json` (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://`).
 
 ---
 
@@ -331,20 +543,27 @@ 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*`.
+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)
 
 | Name | Required | Notes |
 |------|----------|--------|
-| `SUPABASE_URL` | Yes (production) | **Session pooler** `:6543` |
-| `TOMORROWOS_STORE` | Yes | `supabase` |
+| `SUPABASE_URL` | If Q1 = Supabase | **Session pooler** `:6543` |
+| `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 |
-| `PORT` | Optional | Vercel injects as needed |
+| `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 |
+| `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.
 
@@ -353,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 configured
-3. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch `SUPABASE_URL` to **pooler `:6543`** 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.
 
 ---
 
@@ -388,13 +619,18 @@ Tell the user:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| `ENETUNREACH` / IPv6 / `:5432` | Direct Supabase DB URL | Use **Session pooler** `*.pooler.supabase.com:6543` |
-| Control Panel OK, devices never stay paired after restart | SQLite / ephemeral disk | Must use Supabase |
-| Uploads break / broken thumbs in prod | Local `public/uploads` | Cloudinary |
-| 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 |
+| 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 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 |
 
 ---
 
@@ -405,10 +641,11 @@ Tell the user:
 | Secrets | Replit Secrets | Vercel Environment Variables |
 | Deploy config | `.replit`, artifact `kind=web` | `vercel.json` + Fluid; **no** `.replit` |
 | `hostingTarget` | `"here"` | `"vercel"` |
-| Supabase URL | Prefer pooler; Preview DNS may fail | **Require pooler**; direct `:5432` often `ENETUNREACH` |
-| SQLite | Demo OK on persistent Repl disk | **Not** production on Vercel |
-| Object Storage option | Replit Object Storage | N/A — prefer Cloudinary |
-| WebSocket | Long-lived Node (Autoscale) | Fluid compute + Node server export |
+| Database | Supabase (primary) | Supabase **or Neon** (pooled); SQLite demo only |
+| 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 | **Node `TomorrowOS.listen` only** (not Next) |
+| Brand from URL | Not in Replit protocol | **Option A** in Question 3 — infer from website |
 
 ---
 
@@ -416,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 / SSL flags
-4. **Media:** Cloudinary or local (with warning)
-5. **Brand:** name + `hostingTarget: vercel`
-6. **Adaptations from Replit protocol:** list (e.g. skipped `.replit`, exported HTTP server, Fluid, pooler URL)
-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 pooler 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.21",
+  "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.21",
+  "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.21",
+    "@tomorrowos/sdk": "^0.9.23",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },