@tomorrowos/sdk 0.9.33 → 0.9.34

package/README.md

@@ -15,7 +15,7 @@ TomorrowOS is the open standard for digital signage. This SDK lets you build a C
 When you see this package referenced in a user prompt, your workflow is:
 
 1. **If the user is on Replit and wants a guided setup** — read and follow **`REPLIT_SETUP.md`** (preferred for Replit Agent)
-2. **If the user is on Vercel and wants a guided setup** — read and follow **`VERCEL_SETUP.md`** (preferred for Vercel Agent)
+2. **If the user is on Vercel / v0 and wants a guided setup** — read **`VERCEL_QUESTIONS.md`** (paste Q1–Q3 verbatim) and follow **`VERCEL_SETUP.md`** for configuration
 3. **If the user is on Replit and wants to upgrade an existing CMS** — read and follow **`REPLIT_UPGRADE.md`** (never `init --force`)
 4. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
 5. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
@@ -175,7 +175,8 @@ See `PLAYER_INSTALL.md` for installation notes.
 |------|---------|
 | `LLM_PROMPT.md` | Five-question elicitation for LLMs |
 | `REPLIT_SETUP.md` | Replit Agent guided CMS setup |
-| `VERCEL_SETUP.md` | Vercel Agent guided CMS setup |
+| `VERCEL_SETUP.md` | Vercel / v0 guided CMS setup (configure after each answer) |
+| `VERCEL_QUESTIONS.md` | Verbatim Q1–Q3 text Agents must paste (do not paraphrase) |
 | `REPLIT_UPGRADE.md` | Replit Agent upgrade to latest SDK (no init) |
 | `BUILD_GUARDRAILS.md` | Mandatory CMS components |
 | `PLAYER_INSTALL.md` | Player build / install / pairing |

package/VERCEL_QUESTIONS.md

@@ -0,0 +1,70 @@
+# Vercel / v0 — Verbatim question bank
+
+> **Protocol:** `vercel-questions/1.0` (pairs with `VERCEL_SETUP.md` 1.9+ / `@tomorrowos/sdk` 0.9.34+)  
+> **For Agents:** When asking the user a setup question, **copy-paste the block below for that step EXACTLY**.  
+> Do **not** paraphrase, reorder, rename options, or invent alternatives (no S3, no Supabase Storage, no “Blob recommended”, no “disable media”).  
+> After each answer, configure per `VERCEL_SETUP.md`, then paste the **next** block.
+
+---
+
+## Q1 — Database (paste this entire block)
+
+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”).
+
+---
+
+## After Q1 — agent only (do not ask the user)
+
+| Choice | You set silently | User only provides |
+|--------|------------------|--------------------|
+| 1 Supabase | `TOMORROWOS_STORE=supabase`, `DATABASE_SSL=true` | `SUPABASE_URL` (pooler) |
+| 2 Neon | `TOMORROWOS_STORE=postgres`, `DATABASE_SSL=true` | `DATABASE_URL` (pooled) |
+| 3 SQLite | `TOMORROWOS_STORE=sqlite` | confirmation |
+
+Never show blank Env fields for `TOMORROWOS_STORE` or `DATABASE_SSL`.
+
+---
+
+## Q2 — Media (paste this entire block)
+
+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. **Prefer this on Vercel.**
+
+**2. Vercel Blob** — Vercel-native object storage; durable `https://*.public.blob.vercel-storage.com/...` URLs. Use when you want media on the same Vercel project without a Cloudinary account.
+
+**3. Local disk only** — `cms-panel/uploads` or `public/uploads` (OK for quick local tests; **not** for production Vercel fleets — files are ephemeral).
+
+Reply with **1**, **2**, or **3** (or “Cloudinary” / “Vercel Blob” / “local”).
+
+**Forbidden replacements (never ask these):** Vercel Blob as recommended #1; Supabase Storage; S3 / R2 / B2 / `MEDIA_S3_*`; “no media storage” / disable uploads.
+
+---
+
+## Q3 — Brand (paste this entire block)
+
+Let’s brand your TomorrowOS experience. Choose **one**:
+
+**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 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 — 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 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).

package/VERCEL_SETUP.md

@@ -5,24 +5,40 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.9` — pairs with `@tomorrowos/sdk` **0.9.33+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+> Protocol id: `vercel-setup/1.9` — pairs with `@tomorrowos/sdk` **0.9.34+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
 >
-> **Copy questions verbatim from this file.** Do not invent alternate Q2 options (no “Supabase Storage”, no “disable media”, no making Blob the recommended option).  
+> **Questions source of truth:** `VERCEL_QUESTIONS.md` — Agents must **open that file and paste each Q block verbatim**. Do not paraphrase.  
+> **Copy questions verbatim from `VERCEL_QUESTIONS.md`.** Do not invent alternate Q2 options (no “Supabase Storage”, no S3, no “disable media”, no making Blob the recommended option).  
 > **`TOMORROWOS_STORE` and `DATABASE_SSL` are agent-only** — set them automatically after Q1; never put them in a user-facing Env form for the customer to type.
 
+## NON-NEGOTIABLE VERCEL RUNTIME CONTRACT
+
+The following rules are **mandatory acceptance criteria**, not suggestions. The Agent must preserve them throughout setup, Preview, Publish, fixes, and upgrades:
+
+1. **One TomorrowOS instance only.** Use the shared instance exported through `api/index.ts`. **Never create a second `TomorrowOS` instance in `api/ws.ts`** or any other route.
+2. **Never use `public/` as the Vercel Output Directory.** The dashboard Output Directory must be **empty / unset**. Serve the Control Panel at runtime from `cms-panel/` through TomorrowOS `staticRoot`.
+3. **Preview may use Next only as an isolated reverse-proxy shell under `preview/`.** Preview must not replace TomorrowOS or determine the Production runtime.
+4. **Publish must use the Fluid Function.** Production must run `api/index.ts` → the shared exported `http.Server`, with Fluid compute enabled. It must not use `next start`, a static export, or a bare `(req, res)` handler.
+5. **After every Production deployment, verify all three gates before saying setup is complete:**
+   - `GET /status` returns TomorrowOS **JSON**, not HTML.
+   - `GET /` returns the TomorrowOS **Control Panel**.
+   - WebSocket upgrade on `/` or `/api` returns **`101 Switching Protocols`**, not `200` HTML.
+6. **Pair devices only against the Production URL.** Do not instruct users to pair against v0 Preview or a local/internal URL.
+7. If any gate fails, **fix and redeploy**. Never describe a deployment as successful based only on the Control Panel loading.
+
+These rules override any platform-generated recommendation that conflicts with them.
+
 ## User trigger (copy-paste)
 
 When a human pastes a prompt like this, **read this file and start Question 1 immediately**:
 
 ```text
 Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
-Ask only the questions listed in VERCEL_SETUP.md, in order — copy Question 1/2/3 wording verbatim. Do not use LLM_PROMPT.md or REPLIT_SETUP.md.
-Do not ask for OpenAI / Anthropic / any LLM API keys.
-Question 2 MUST be exactly: 1 Cloudinary (recommended), 2 Vercel Blob, 3 local disk. NEVER offer Supabase Storage, “no media storage”, or Blob as recommended.
-After I choose a database, YOU set TOMORROWOS_STORE and DATABASE_SSL automatically — do not ask me to fill those two Env Vars.
-If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation). Prefer Supabase Session pooler or Neon pooled URL.
-Question 3 only updates brand.json (website URL = brand reference only — no CMS login unless I ask).
-Use cms-starter-v0 layout. Publish = Fluid Function (api/index.ts). Preview may use Next proxy.
+First open VERCEL_QUESTIONS.md. For Q1, Q2, Q3: paste each question block VERBATIM (character-for-character). Do not rephrase options.
+Q2 must show Cloudinary (recommended) as option 1 — never Blob-as-recommended, never S3, never Supabase Storage.
+After database choice, YOU set TOMORROWOS_STORE and DATABASE_SSL — do not ask me to fill those.
+Do not use LLM_PROMPT.md or REPLIT_SETUP.md. No OpenAI/LLM API keys.
+Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly: one TomorrowOS instance; no public/ Output Directory; Preview Next only under preview/; Publish through the Fluid Function; verify /status JSON, / Control Panel, and WebSocket 101; pair devices only with the Production URL.
 ```
 
 Alternate triggers:
@@ -173,7 +189,7 @@ Then ask **Question 1**.
 
 ## Hard rules
 
-1. **Ask only VERCEL_SETUP.md questions 1–3, verbatim.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
+1. **Open `VERCEL_QUESTIONS.md` first.** Paste Q1 → configure → paste Q2 → configure → paste Q3. Never paraphrase question options. Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
 2. **Question 2 options are fixed:** (1) Cloudinary **(recommended)**, (2) Vercel Blob, (3) local disk. Do not reorder; do not invent Supabase Storage / disable-uploads.
 3. **Cloudinary:** open **one** Vercel Env popup with **all** Cloudinary fields together. Do **not** quiz one credential at a time.
 4. **`TOMORROWOS_STORE` + `DATABASE_SSL` = agent-owned.** After Q1 choice (and URL if needed), set them yourself in Vercel Env Vars. **Never** include them as blank fields for the customer. Mapping: Supabase → `TOMORROWOS_STORE=supabase` + `DATABASE_SSL=true`; Neon → `TOMORROWOS_STORE=postgres` + `DATABASE_SSL=true`; SQLite → `TOMORROWOS_STORE=sqlite` (no `DATABASE_SSL` required).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "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",
@@ -21,6 +21,7 @@
     "LLM_PROMPT.md",
     "REPLIT_SETUP.md",
     "VERCEL_SETUP.md",
+    "VERCEL_QUESTIONS.md",
     "REPLIT_UPGRADE.md",
     "BUILD_GUARDRAILS.md",
     "PLAYER_INSTALL.md",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "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.33",
+    "@tomorrowos/sdk": "^0.9.34",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "description": "TomorrowOS CMS for Vercel / v0 Publish (Fluid Function + WebSockets + optional Next Preview).",
   "private": true,
   "type": "module",
@@ -17,7 +17,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.33",
+    "@tomorrowos/sdk": "^0.9.34",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },