@tomorrowos/sdk 1.1.2 → 1.1.4

package/VERCEL_QUESTIONS.md

@@ -1,17 +1,21 @@
 # Vercel / v0 - Verbatim question bank
 
-> **Protocol:** `vercel-questions/1.6` (pairs with `VERCEL_SETUP.md` 1.17+ / `@tomorrowos/sdk` 0.9.70+)  
+> **Protocol:** `vercel-questions/1.8` (pairs with `VERCEL_SETUP.md` 1.19+ / `@tomorrowos/sdk` 0.9.70+)  
 > **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 and Q2 are choice questions. Q3 is a form only - never a multiple-choice question. Q4 is optional CMS password (`CMS_PASSWORD`).**  
+> **Q1 and Q2 are choice questions — present them as a clickable choice UI** (buttons / radio / option cards) using the exact option labels below. Do **not** ask the user to type `1` or `2` in chat when a choice UI is available (chat typing is fallback only).  
+> **Q3 is a form only - never a multiple-choice question.**  
+> **Q4 is optional CMS password (`CMS_PASSWORD`) — immediately after Q3, no yes/no prelude.** Open the password Env/Secret input; blank/skip is valid.  
 > **HARD STOP on Q3:** show the form, then **wait** for the user's reply. Optional fields do **not** mean you may auto-skip.  
 > **Q4 is optional:** blank/skip is valid; they can set `CMS_PASSWORD` later.  
 > **After Q4 (or after Q3 if you deferred Q4):** run `VERCEL_SETUP.md` **IRON GATE — v0 Preview hygiene** before debugging Neon/Postgres or Blob.
 
 ---
 
-## Q1 - Database (paste this entire block)
+## Q1 - Database (clickable choice UI — paste option text exactly)
+
+**UX:** Open a **clickable choice UI** (two option buttons / radio cards). Labels must match the bold titles below.
 
 Which database should TomorrowOS use on Vercel?
 
@@ -19,7 +23,7 @@ Which database should TomorrowOS use on Vercel?
 
 **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).
 
-Reply with **1** or **2** (or "Supabase" / "Neon").
+**Fallback only** (no choice UI available): Reply with **1** or **2** (or "Supabase" / "Neon").
 
 ---
 
@@ -34,7 +38,9 @@ Never show blank Env fields for `TOMORROWOS_STORE` or `DATABASE_SSL`.
 
 ---
 
-## Q2 - Media (paste this entire block)
+## Q2 - Media (clickable choice UI — same pattern as Q1)
+
+**UX:** Open a **clickable choice UI** (two option buttons / radio cards). **Forbidden when UI exists:** chat-only “Reply with **1** or **2**”.
 
 How should playlist media (images/videos) be stored?
 
@@ -42,7 +48,7 @@ How should playlist media (images/videos) be stored?
 
 **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.
 
-Reply with **1** or **2** (or "Cloudinary" / "Vercel Blob").
+**Fallback only** (no choice UI available): Reply with **1** or **2** (or "Cloudinary" / "Vercel Blob").
 
 **Forbidden replacements (never ask these):** Vercel Blob as recommended #1; Supabase Storage; S3 / R2 / B2 / `MEDIA_S3_*`; "no media storage" / disable uploads; local disk only.
 
@@ -88,18 +94,22 @@ Reply with **1** or **2** (or "Cloudinary" / "Vercel Blob").
 - Auto-continuing to init/scaffold/deploy without a user Q3 reply or explicit "skip"
 - Interpreting "do not re-ask" as "do not wait for the first reply"
 
-After the user submits (including all-blank) or says "skip": apply `brand.json`, then paste **Q4**. **Do not** re-ask Q3 a second time.
+After the user submits (including all-blank) or says "skip": apply `brand.json`, then open **Q4 immediately** (CMS_PASSWORD Env input — **no** yes/no prelude). **Do not** re-ask Q3 a second time.
 Blank fields -> keep existing `brand.json`. Logo blank -> `./assets/logo.svg`.
 
 ---
 
-## Q4 - Optional CMS password (paste this entire block)
+## Q4 - Optional CMS password (Env input immediately after Q3)
+
+**IRON RULE — no prelude:** Right after Q3, open the **CMS_PASSWORD** Env/Secret input. **Forbidden first:** "Do you want a password?", "Enable auth?", "Protect the CMS?", Option A/B yes/no.
+
+**UX (required):** One Env/Secret field labeled **`CMS_PASSWORD`** (password input). User may enter a password **or** leave blank / skip.
 
-Optional: set a CMS password now?
+**Title / helper:**
 
-If yes, reply with the password to store as Environment Variable **`CMS_PASSWORD`**.
+Optional CMS password — Environment Variable **`CMS_PASSWORD`**.
 
-Leave blank / reply **skip** / **later** / **no** to keep the panel open for now — you can add `CMS_PASSWORD` later in Vercel → Settings → Environment Variables and redeploy.
+Enter a password to lock the Control Panel, or leave blank / skip to keep the panel open. You can add `CMS_PASSWORD` later in Vercel → Settings → Environment Variables and redeploy.
 
 **Notes for the agent (do not invent extra UX):**
 - This is **optional**. Blank/skip is a valid complete answer.

package/VERCEL_SETUP.md

@@ -5,12 +5,15 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`).
 >
-> Protocol id: `vercel-setup/1.17` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+> Protocol id: `vercel-setup/1.19` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
 >
 > **Questions source of truth:** `VERCEL_QUESTIONS.md` - Agents must **open that file and paste each Q block verbatim**. Do not paraphrase.  
-> **Q1/Q2 = choice questions. Q3 = form only:** open **all seven optional inputs at once**, then **HARD STOP and WAIT** for submit or "skip". Never auto-skip because fields are optional. Never ask a branding choice first. Never show only Name + Primary colour. Logo = **Upload** above **Logo URL**.  
-> **Q4 = optional `CMS_PASSWORD`:** blank/skip is valid; can set later. Control Panel auth only — never Vercel Deployment Protection / whole-site password.  
+> **Q1/Q2 = clickable choice UI (same pattern):** open a **button / radio / option-card UI** with the two fixed choices. Do **not** ask the user to type `1` or `2` in chat when a choice UI is available. Chat “reply 1 or 2” is fallback only.  
+> **Q3 = form only:** open **all seven optional inputs at once**, then **HARD STOP and WAIT** for submit or "skip". Never auto-skip because fields are optional. Never ask a branding choice first. Never show only Name + Primary colour. Logo = **Upload** above **Logo URL**.  
+> **Q4 = optional `CMS_PASSWORD` (immediately after Q3, no prelude):** open the **CMS password Env/Secret input** right away. Blank/skip is valid. **Forbidden:** yes/no “Do you want a password / enable auth?” before the field. Control Panel auth only — never Vercel Deployment Protection / whole-site password.  
 > **After Q&A (before debugging DB):** run **IRON GATE — v0 Preview hygiene** (clear root Next leftovers, restart supervised `dev`, prove `GET /status` is TomorrowOS JSON). Do **not** spend turns “fixing Neon/Blob” while port 3000 is still a stale Next/Turbopack process.  
+> **Publish Output Directory:** must stay **empty / unset**.  
+> **Publish Build Command:** must be **empty / skip build** (`"buildCommand": ""` in `vercel.json` + dashboard). A defined build command (even a no-op `npm run build`) forces Vercel **static-build** mode and requires `public/` — that causes `Output Directory "public" is empty` / not found. Do **not** “fix” by stuffing `public/robots.txt`.  
 > **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.
 
@@ -20,6 +23,8 @@ The following rules are **mandatory acceptance criteria**, not suggestions. The
 
 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`.
+2a. **Build Command must be empty / skip build** (`"buildCommand": ""` in `vercel.json`, dashboard Build Command empty). Do **not** use a no-op `npm run build` / `node -e "process.exit(0)"` as the Production build command — any defined build command with Framework=Other puts Vercel in **static-build** mode and requires a `public/` output directory.
+2b. **Build errors `The Output Directory "public" is empty` or `public` not found:** First clear Output Directory if it is set to `public`. If Output is already null and the error remains, the cause is a **defined Build Command** — set Build Command / `buildCommand` to **empty string** and redeploy. Filling `public/` only papers over wrong static-output mode.
 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:**
@@ -39,12 +44,14 @@ When a human pastes a prompt like this, **read this file and start Question 1 im
 Follow @tomorrowos/sdk (an NPM package) VERCEL_SETUP.md and set up my TomorrowOS CMS from scratch.
 
 Open VERCEL_QUESTIONS.md first.
-For Q1, Q2, Q3: paste each question block VERBATIM. Do not rephrase options.
+For Q1 and Q2: open a **clickable choice UI** (buttons / radio / option cards) using the verbatim options from VERCEL_QUESTIONS.md. Do not ask me to type 1 or 2 in chat when UI is available.
+For Q1, Q2, Q3: use exact option wording from VERCEL_QUESTIONS.md. Do not rephrase options.
 For Q3: DO NOT ask a branding choice. Open one form with ALL SEVEN optional inputs at once, then HARD STOP and WAIT for my submit or "skip". Never auto-continue with defaults without my reply. Never only Name + Primary colour. Logo = Upload above Logo URL.
-After Q3, paste Q4 (optional CMS password). Blank/skip is valid.
+After Q3, open Q4 immediately: one Env/Secret input for CMS_PASSWORD (blank/skip OK). Do NOT ask yes/no "want a password?" first.
 After Q1 database choice, YOU set TOMORROWOS_STORE and DATABASE_SSL. Do not ask me to fill those.
 After Q2 media storage choice, YOU set TOMORROWOS_MEDIA. Do not ask me to fill those.
 After answers: run IRON GATE v0 Preview hygiene BEFORE debugging Postgres/media — clear root Next leftovers, restart supervised dev, prove GET /status is TomorrowOS JSON.
+Before Publish: Output Directory empty/unset (NOT public). Build Command EMPTY (buildCommand: "") — never a no-op npm run build (forces static public/ check). Do not stuff public/robots.txt.
 Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
 Keep cms-starter-v0 layout.
 Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
@@ -106,8 +113,8 @@ almost always means **Vercel still thinks this is a Next.js / static deploy**, n
    If it still says **Next.js**, patch it via Vercel API / CLI / dashboard **before** redeploying.  
    `"framework": null` in `vercel.json` alone is **not enough** if the dashboard still says Next.js.
 2. **Install Command** = `npm install` / `pnpm install` / `yarn` (normal install).
-3. **Build Command** = a **no-op that exits 0** (e.g. `node -e "process.exit(0)"` or `npm run build` where `build` is that no-op).  
-   **Never** run `next build` for Production.
+3. **Build Command** = **empty / skip build** (`""` in `vercel.json` and dashboard).  
+   **Never** run `next build` for Production. **Never** use a no-op `npm run build` / `node -e "process.exit(0)"` as the Production build command — that forces static-build mode and the `public/` output check.
 4. **Production entry** = Fluid **Vercel Function** `api/index.ts` that **`export default server`** from shared `cms-app.ts` (see [WebSockets docs](https://vercel.com/docs/functions/websockets)). Local `npm start` may still use root `server.ts`.
 5. **Output Directory** = **empty / unset**. Do **not** set `outputDirectory: "."` as a fake static site.
 6. **Do** use a single `api/index.ts` that exports the TomorrowOS `http.Server`. **Do not** create a second TomorrowOS in `api/ws.ts`, and **do not** use bare `(req, res)` handlers that drop upgrades.
@@ -117,18 +124,47 @@ almost always means **Vercel still thinks this is a Next.js / static deploy**, n
 
 **Setup is NOT complete** while Production `GET /` returns `404: NOT_FOUND` or WebSocket upgrade returns 200 HTML.
 
-### Publish static trap ??`public/` served without Node (read this)
+### Publish static trap — `public/` served without Node (read this)
 
-A common **worse** failure mode than `404: NOT_FOUND`:
-
-- `GET /` loads the Control Panel HTML (from static `public/index.html`)
+**Symptom A — wrong runtime (common worse failure than `404: NOT_FOUND`):**
+- `GET /` loads the Control Panel HTML (from static files)
 - `GET /status`, `/devices`, etc. return **HTML** (Vercel 404 page)
 - The panel shows **CMS unreachable** and console:  
   `Unexpected token 'T', "The page c"... is not valid JSON`
 
-**Root cause:** Vercel deployed `public/` as a **static site** (Output Directory = `public` or Framework=Other default *?public if it exists??). **No Function** is running TomorrowOS.
+**Root cause A:** Vercel deployed `public/` as a **static site** (Output Directory = `public` or Framework=Other default “public if it exists”). **No Function** is running TomorrowOS.
+
+**Symptom B — build fails before deploy:**
+```text
+Error: The Output Directory "public" is empty.
+```
+or (after deleting `public/`):
+```text
+No Output Directory named "public"
+```
+(wording may vary; both mean Vercel is in **static-build** mode looking for `public/`)
+
+**Root cause B (check in order):**
+1. Project Settings **Output Directory = `public`** (explicit override) — clear it.
+2. Output Directory is already **null**, but a **Build Command is defined** (`npm run build` or any no-op). With Framework=Other, a defined build command forces static-build mode and defaults the output check to `public/` — even when dashboard Output is unset.
+
+**Correct fix (mandatory for A and B):**
 
-**Fix (Scheme A):** use `cms-panel/` (not `public/`), Fluid Function `api/index.ts` + rewrites, Output Directory empty. Static UI is served **at runtime** via `staticRoot` in `listen()`.
+1. Set **Output Directory** = **empty / unset**.
+2. Set **Build Command** = **empty** (`"buildCommand": ""` in `vercel.json` + dashboard). This is a **functions-only** deploy; skip the static build step entirely.
+3. Framework Preset = **Other** / null; Fluid on; `api/index.ts` + rewrites per Scheme A.
+4. Redeploy. Verify `GET /status` is **JSON** and WebSocket is **101**.
+
+**Forbidden “fixes”:**
+
+- Adding `public/robots.txt` / `.gitkeep` **so a static Output Directory = `public` build passes** — that leaves Production on the static trap path.
+- Keeping a no-op `buildCommand: "npm run build"` while hoping Output=null is enough — the defined build command still triggers the `public/` check.
+- Setting Output Directory to `cms-panel`, `.`, or `public`.
+- Claiming Publish succeeded because the build log turned green while Output is still `public` or Build Command still runs a static check.
+
+**Optional:** If some tooling creates an empty `public/` folder, delete it or ignore it — **never** point Output Directory at it.
+
+**Scheme A reminder:** use `cms-panel/` (not `public/`), Fluid Function `api/index.ts` + rewrites, Output Directory empty. Static UI is served **at runtime** via `staticRoot` in `listen()`.
 
 **Publish gate (mandatory):** after deploy, `GET /status` must return **JSON** starting with `{`, not HTML starting with `<` or `The page`. **And** WebSocket upgrade on `/` or `/api` must return **101**.
 
@@ -168,10 +204,14 @@ Ask **only** these questions, in **this exact order**. **Copy the ?Ask exactly??
 | 1 | **Question 1** ? Database (Supabase ? Neon) | Always |
 | 2 | **Question 2** ? Media (**Cloudinary recommended** ? Vercel Blob) | Always (after Q1) |
 | 3 | **Question 3** - Brand form (`brand.json` only; **not a choice** - open all 7 optional inputs at once) | Always (after Q2) |
-| 4 | **Question 4** - Optional CMS password Env `CMS_PASSWORD` (**optional**; blank = skip, can set later) | Always last |
+| 4 | **Question 4** - Optional CMS password Env `CMS_PASSWORD` (**immediately after Q3**; blank = skip; **no** yes/no prelude) | Always last |
 
 **That is the complete list (Q1–Q4).** Do **not** ask how many screens / devices.
 
+| Step UX | Rule |
+|---------|------|
+| Q4 CMS password | **Immediately after Q3** — one Env/Secret input for `CMS_PASSWORD` (blank/skip allowed). **Never** ask a yes/no "do you want a password?" first. |
+
 **Forbidden invented Question 2 options (never offer these in chat or UI):**
 
 - ???Vercel Blob **(recommended)**??as option 1 ??Blob is option **2**, not recommended over Cloudinary
@@ -206,7 +246,9 @@ Then ask **Question 1**.
 
 ## Hard rules
 
-1. **Open `VERCEL_QUESTIONS.md` first.** Paste Q1 → configure → paste Q2 → configure → paste Q3 → paste Q4. Never paraphrase question options. Never use `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
+1. **Open `VERCEL_QUESTIONS.md` first.** Ask Q1 → configure → Q2 → configure → Q3 → Q4. Never paraphrase question options. Never use `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
+1a. **Q1 and Q2 UX:** Prefer a **clickable choice UI** (same pattern for both): two option buttons/cards matching the verbatim labels. **Forbidden when UI exists:** chat-only “Reply with 1 or 2”. Chat typing is fallback only if the platform cannot render choices.
+1b. **Q4 UX:** Immediately after Q3, open the **`CMS_PASSWORD` Env/Secret input**. **Forbidden:** yes/no “Do you want a password / enable auth?” prelude. Blank/skip is a complete answer.
 2. **Question 2 options are fixed:** (1) Cloudinary **(recommended)**, (2) Vercel Blob. Do not reorder; do not invent Supabase Storage, local disk, or 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`. **Do not offer SQLite as a questionnaire choice** ? it is ephemeral on Vercel and unsuitable for production.
@@ -227,7 +269,7 @@ Then ask **Question 1**.
 19. **Q3 is a form, not a question — and you must WAIT.** After Q2, open one dialog with **all seven** optional inputs visible together, then **stop and wait** for submit or explicit **"skip"**. **Never** auto-continue because fields are optional. **Never** ask a preliminary branding choice. **Never** show only Product Name + Primary colour. **Never** use multiple-choice / Option A-B for branding. Logo = **Upload** above **Logo URL**.
 20. **IRON GATE after Q&A:** Before blaming Neon / Blob / migrations, complete **IRON GATE — v0 Preview hygiene** below. Preview 500s are usually leftover root Next or a stale supervised `next-server`, not a bad Q1/Q2 choice.
 
-**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 optional `CMS_PASSWORD` -> **IRON GATE** -> execution checklist.
+**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 `CMS_PASSWORD` Env input (**no yes/no prelude**; blank/skip OK) -> **IRON GATE** -> execution checklist.
 
 ---
 
@@ -390,7 +432,7 @@ SDK behaviour (0.9.32+):
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build",
+  "buildCommand": "",
   "functions": {
     "api/index.ts": {
       "maxDuration": 300,
@@ -404,7 +446,7 @@ SDK behaviour (0.9.32+):
 }
 ```
 
-**`maxDuration` plan limits:** Hobby / many default plans allow **1??00** 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??.
+**`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.
 
@@ -414,19 +456,26 @@ SDK behaviour (0.9.32+):
 
 - `"fluid": true` is required for WebSockets
 - **Do not** set `outputDirectory` to `cms-panel` / `public`
-- `"buildCommand"` = no-op ??**never** `next build` for Production
-- Dashboard Output Directory must stay **empty**
+- `"buildCommand": ""` — **skip build entirely** (functions-only). **Never** `next build`. **Never** a no-op `npm run build` as Production build (forces static `public/` check)
+- Dashboard Output Directory must stay **empty**; dashboard Build Command must stay **empty** (or match `""`)
 
-### A4 ??Vercel Project Settings (dashboard ??mandatory)
+### A4 — Vercel Project Settings (dashboard — mandatory)
 
 | Setting | Required value |
 |---------|----------------|
-| Framework Preset | **Other** / null ??**not Next.js** |
+| Framework Preset | **Other** / null — **not Next.js** |
 | Install Command | `npm install` |
-| Build Command | `npm run build` (no-op) |
-| **Output Directory** | **empty** |
+| **Build Command** | **empty / skip** — **not** `npm run build` |
+| **Output Directory** | **empty / unset** — **never `public`** |
 | Fluid compute | **On** |
-| WebSockets | Account must allow Functions WebSockets (see docs ?Permissions Required?? |
+| WebSockets | Account must allow Functions WebSockets (see docs — Permissions Required) |
+
+**If Publish build fails with `The Output Directory "public" is empty` or `public` not found:**
+1. Clear Output Directory if set to `public`.
+2. If Output is already null: set **Build Command** / `vercel.json` `"buildCommand"` to **`""`** and redeploy. A defined build command (even no-op) forces static-build mode.
+3. Do **not** add `public/robots.txt` as the primary fix.
+
+**`vercel.json` must not set `outputDirectory`.** Leaving it out is correct. **`buildCommand` must be `""`** (empty string), not omitted if the dashboard still has a leftover `npm run build` — set both file and dashboard.
 
 ### A5 ??Publish acceptance (all must pass)
 
@@ -503,7 +552,7 @@ Adapt script names / process runners as needed. **Invariant:**
 
 - **Local `npm start`** = TomorrowOS Node with `server.listen`.
 - **Vercel Production** = Function `api/index.ts` (SDK `autoListen=false` when `VERCEL` is set).
-- **`build`** = no-op exit 0 (never `next build` for Production).
+- **`vercel.json` `"buildCommand"`** = `""` (skip build). Optional `package.json` `"build"` no-op is unused by Vercel Publish — **never** wire it as the Production Build Command.
 - **Preview / v0** = Next on public port + TomorrowOS on internal port + proxy.
 
 ### Minimal dependencies (Production)
@@ -620,23 +669,23 @@ Write `vercel.json` so Production cannot be mistaken for Next. Minimum:
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build"
+  "buildCommand": ""
 }
 ```
 
-Use `pnpm` / `yarn` variants of install/build if that is the project?s package manager.
+Use `pnpm` / `yarn` variants of install if that is the project's package manager. **`buildCommand` must be `""`** (skip build) — do **not** set `npm run build` even as a no-op.
 
-**Do not** add `startCommand`, `processes`, or `outputDirectory` to `vercel.json` when v0 schema rejects them. Start = `package.json` `"start": "tsx server.ts"`. Output Directory = **empty in dashboard**.
+**Do not** add `startCommand`, `processes`, or `outputDirectory` to `vercel.json` when v0 schema rejects them. Start = `package.json` `"start": "tsx server.ts"`. Output Directory = **empty in dashboard**. Build Command = **empty in dashboard**.
 
-**Also force Project Settings (dashboard or Vercel API) ??this is mandatory (see Scheme A4):**
+**Also force Project Settings (dashboard or Vercel API) — this is mandatory (see Scheme A4):**
 
 | Setting | Required value |
 |---------|----------------|
-| Framework Preset | **Other** / null ??**not Next.js** |
+| Framework Preset | **Other** / null — **not Next.js** |
 | Install Command | `npm install` (or pnpm/yarn) |
-| Build Command | `npm run build` (no-op exit 0) |
-| Output Directory | **empty / null** ??**NOT `public`** |
-| Start Command | `npm run start` ??`tsx server.ts` (or `.mts`) ??set in **dashboard**, not `vercel.json` |
+| **Build Command** | **empty / skip** — **not** `npm run build` |
+| Output Directory | **empty / null** — **NOT `public`** |
+| Start Command | `npm run start` — `tsx server.ts` (or `.mts`) — set in **dashboard**, not `vercel.json` |
 | Fluid compute | **On** |
 
 If `next` / `next.config.*` exist for Preview and the dashboard still auto-selects Next.js:
@@ -680,17 +729,26 @@ If Vercel?s UI and this file disagree on bundling, **prefer whatever keeps a sin
 
 If you open an Env configuration UI for Q1, fields visible to the user may include **only** `SUPABASE_URL` or `DATABASE_URL`. **Do not** show blank `TOMORROWOS_STORE` / `DATABASE_SSL` inputs ? write those yourself in the same step.
 
-### Step A ? Ask storage choice
+### Step A — Ask database choice (**clickable UI required**)
 
-**Ask exactly:**
+**UX:** Open a **choice UI** the user can **click** — two option buttons / radio cards / select list. Labels must match the verbatim options below. Same clickable pattern as Q2.
+
+| # | Exact option label (UI) |
+|---|-------------------------|
+| 1 | **Supabase Postgres (recommended)** |
+| 2 | **Neon Postgres** |
+
+Supporting copy under each option may match `VERCEL_QUESTIONS.md`. **Do not** default to a chat message that only says “Reply with 1 or 2” when the platform can render choices.
+
+**Ask exactly (wording / option text must match):**
 
 > 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).
+> **1. Supabase Postgres (recommended)** — durable pairing/playlists; use the **Session pooler** URL (`*.pooler.supabase.com:6543`).
 >
-> Reply with **1** or **2** (or "Supabase" / "Neon").
+> **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).
+
+**Fallback only** (no choice UI available): allow chat reply **1** / **2** / "Supabase" / "Neon".
 
 ### Step B ??If **1 / Supabase**
 
@@ -746,19 +804,26 @@ If you open an Env configuration UI for Q1, fields visible to the user may inclu
 > 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 two options below verbatim.** Wrong examples that must **never** appear: "Vercel Blob (recommended)", "Supabase Storage", "No media storage / disable uploads", "local disk only".
 
-### Step A ? Ask storage choice
+### Step A — Ask storage choice (**clickable UI required — same as Q1**)
+
+**UX:** Open a **choice UI** the user can **click** — two option buttons / radio cards. **Forbidden when UI exists:** chat-only “Reply with **1** or **2**”.
 
-**Ask exactly (wording must match ? Cloudinary is recommended):**
+| # | Exact option label (UI) |
+|---|-------------------------|
+| 1 | **Cloudinary (recommended)** |
+| 2 | **Vercel Blob** |
+
+**Ask exactly (wording must match — Cloudinary is recommended):**
 
 > 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.
+> **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.**
 >
-> Reply with **1** or **2** (or "Cloudinary" / "Vercel Blob").
+> **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.
 
-If you catch yourself about to offer Blob-as-recommended, Supabase Storage, local disk, or "no media" ? **stop and paste the block above instead**.
+**Fallback only** (no choice UI): chat reply **1** / **2** / "Cloudinary" / "Vercel Blob".
+
+If you catch yourself about to offer Blob-as-recommended, Supabase Storage, local disk, or "no media" — **stop and use the block above instead**.
 
 ### Step B ??If **1 / Cloudinary** (same Question 2 ??**one Env popup**)
 
@@ -922,9 +987,20 @@ Set `cmsEndpoint` only if they already know the public `https://?vercel.app` URL
 
 > **Optional.** Protect the Control Panel with app-level auth. You may **skip** and set Env Var `CMS_PASSWORD` later (then Redeploy).
 
-**Ask (Env input or one chat reply):**
+> **IRON RULE — no prelude:** As soon as Q3 is submitted/skipped, open **this** step next. Do **not** first ask whether they want a password / auth / lock. Open the password Env/Secret field (or one chat prompt) immediately; blank/skip is a complete Q4 answer.
+
+**UX (required):** Open **one** Env/Secret input labeled **`CMS_PASSWORD`** (password field). User may enter a password **or** leave blank / skip.
 
-> Optional: set a CMS password now? If yes, enter the password to store as Environment Variable **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now — you can add this later in Vercel → Settings → Environment Variables and redeploy.
+**Ask (Env input — preferred — or one chat reply):**
+
+> Optional CMS password — Environment Variable **`CMS_PASSWORD`**.
+>
+> Enter a password to lock the Control Panel, or leave blank / skip to keep the panel open. You can add `CMS_PASSWORD` later in Vercel → Settings → Environment Variables and redeploy.
+
+**Forbidden before / instead of this input:**
+- "Do you want to protect the CMS?"
+- "Add a password?" / "Enable auth?"
+- Option A/B or yes/no for password first
 
 **Why:**
 - Locks the **CMS Control Panel only** (not the whole deployment).
@@ -965,8 +1041,9 @@ Then (**Scheme A — mandatory for Publish**):
 
 1. Keep **`server.ts`** at **project root** with top-level `listen()` + `export default server`.
 2. **Immediately** move leftover v0 Next from root into **`preview/`** or delete root Next files (`next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts`, starter `components/`). Production must not see root Next.
-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.
+3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, `"buildCommand": ""` — **no** `startCommand`, **no** no-op `npm run build`).
+4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory **empty/unset**, Build Command **empty**, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js, Output = `public`, **or** Build = `npm run build`.
+4a. **Pre-Publish build/output check:** If build fails with `Output Directory "public" is empty` / not found: clear Output Directory **and** set Build Command / `buildCommand` to **`""`**. Do **not** add `public/robots.txt`. Do **not** keep a no-op build command.
 5. Do **not** add root `api/` catch-all for raw `http.Server`.
 6. Do **not** add `.replit*`.
 7. If Q2 = Vercel Blob: set `BLOB_READ_WRITE_TOKEN` + `TOMORROWOS_MEDIA=vercel-blob` (SDK-native; no custom bridge).
@@ -1013,15 +1090,16 @@ vercel --prod
 
 **Publish acceptance checklist (all must pass ??Scheme A5):**
 
-1. Framework Preset = **Other** / null (dashboard confirms ??not Next.js)
+1. Framework Preset = **Other** / null (dashboard confirms — not Next.js)
 2. Output Directory = **empty** (not `public`)
+2a. Build Command = **empty** (`"buildCommand": ""` — not `npm run build`)
 3. Start Command = Node `TomorrowOS.listen` (`npm run start` / `tsx server.ts`)
 4. Fluid compute on
 5. Env Vars present for Production
-6. Production `GET /status` returns **JSON** ??**not** HTML (`Unexpected token 'T'` means this failed)
-7. Production `GET /` returns Control Panel HTML ??**not** `404: NOT_FOUND`
+6. Production `GET /status` returns **JSON** — **not** HTML (`Unexpected token 'T'` means this failed)
+7. Production `GET /` returns Control Panel HTML — **not** `404: NOT_FOUND`
 
-If step 6 fails but step 7 passes: **static `public/` trap** ??Vercel is not running Node. Re-apply Scheme A3?A4; try **Path B** (Git / `vercel --prod`); do **not** invent `api/` + `rewrites`.
+If step 6 fails but step 7 passes: **static `public/` trap** — Vercel is not running Node. Re-apply Scheme A3–A4; try **Path B** (Git / `vercel --prod`); do **not** invent `api/` + `rewrites`.
 
 Tell the user:
 
@@ -1073,6 +1151,9 @@ More detail: https://docs.tomorrowos.org/docs/os/tizen and https://docs.tomorrow
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Build: `Output Directory "public" is empty` / public not found | (1) Output Directory = `public`, **or** (2) Output null but **Build Command defined** → static-build mode | Clear Output; set `"buildCommand": ""` + dashboard Build empty; Fluid `api/index.ts`. Do **not** primary-fix with `public/robots.txt` or keep no-op `npm run build` |
+| Agent asked Q2 as chat “type 1 or 2” while choice UI available | Off-protocol Q2 UX | Re-ask Q2 with **clickable** Cloudinary / Vercel Blob options (same pattern as Q1) |
+| Agent asked yes/no “want a CMS password?” before Q4 | Off-protocol Q4 UX | After Q3, open **CMS_PASSWORD** Env input immediately (blank/skip OK) |
 | Preview 500 / Turbopack / `ENOENT .../app` after Q1–Q3 | Leftover **root** Next from v0 starter; not Neon/Blob | **IRON GATE:** delete/move root `app/` + `next.config.*`; keep `preview/`; restart supervised `dev`; prove `/status` JSON |
 | `Internal Server Error` + logs blame missing `DATABASE_URL` in a **manual** Bash server | `dotenv` loaded `.env` only; secret is in `.env.development.local` / supervised env | Restart **supervised** Preview process; or load both env files — do **not** immediately change Neon URL |
 | `EADDRINUSE :3000` while debugging | Second `pnpm dev` / stale `next-server` after script rewrite | Kill stale Next/tsx; one process; let supervisor re-exec new `"dev"` |
@@ -1086,7 +1167,7 @@ More detail: https://docs.tomorrowos.org/docs/os/tizen and https://docs.tomorrow
 | `vercel.json` error: invalid `startCommand` | v0 schema rejects it | Remove from `vercel.json`; Function entry does not need startCommand |
 | 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 |
+| Build runs `next build` / missing routes-manifest | Next auto-detected from root `next.config` / `app/` | Move Next to `preview/`; Framework null/Other; `"buildCommand": ""` |
 | Preview blank but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy ??internal TomorrowOS port |
 | Preview works, Publish broken / Next-only | Production still on Next | Switch Production to Fluid Function `api/index.ts` |
 | `ENETUNREACH` / IPv6 / `:5432` | Direct Postgres URL | Use **pooled** URL (Supabase `:6543` or Neon pooler) |
@@ -1154,7 +1235,11 @@ Protocol complete when:
 
 ## Protocol version
 
-`vercel-setup/1.17` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.6.
+`vercel-setup/1.19` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.8.
+
+**Changelog 1.19:** Publish Build Command must be **empty** (`"buildCommand": ""`) — a defined no-op `npm run build` forces Vercel static-build mode and the `public/` output check (empty → “not found” after deleting `public/`). Q4 opens **immediately after Q3** as the `CMS_PASSWORD` Env input with **no** yes/no password prelude.
+
+**Changelog 1.18:** Q1/Q2 must use **clickable choice UI** (not chat “type 1 or 2” when UI exists). Publish build error `Output Directory "public" is empty` → **clear Output Directory** (forbidden primary fix: stuff `public/robots.txt` while Output stays `public`). Strengthens static-output trap docs.
 
 **Changelog 1.17:** After Q&A, agents **must** run **IRON GATE — v0 Preview hygiene** before DB rabbit holes: clear root Next leftovers, restart supervised `dev`, prove `GET /status` is TomorrowOS JSON. Documents `.env` vs `.env.development.local` / supervised-env trap. Preview decision tree + cheat-sheet rows for Turbopack/`ENOENT`, missing `DATABASE_URL` in manual Bash, `EADDRINUSE`, stale `next-server`. Neon/Blob choices are not the usual Preview failure cause.
 

package/VERCEL_UPGRADE.md

@@ -40,6 +40,7 @@ When any of these triggers fire:
 4. **Do NOT** blindly overwrite `cms-panel/methods.js`, `cms-panel/index.html`, `cms-panel/panel.css`, `server.ts`, `cms-app.ts`, or `api/index.ts` with template copies. Always **diff → report → merge only with user consent** (or apply surgical patches that preserve custom code).
 5. **Do NOT** create a second `new TomorrowOS(...)` in `api/ws.ts` or elsewhere. **One** shared instance only.
 6. **Do NOT** set Vercel Output Directory to `public/` or switch Production to Next/`next start` / static-only.
+6a. **Do NOT** keep a Production Build Command of `npm run build` (even no-op) — use `"buildCommand": ""` so Vercel does not enter static-build / `public/` output checks.
 7. Prefer **`npm install @tomorrowos/sdk@latest`** over pinning an older version unless the user named a specific version.
 8. Keep `tsx` available at runtime (`dependencies`, not only `devDependencies`) if local `npm run start` / Preview still relies on `tsx server.ts`.
 9. After upgrade, re-check Production gates: `GET /status` → JSON, `GET /` → Control Panel, WebSocket `/` or `/api` → **101**.
@@ -54,7 +55,7 @@ Capture and remember:
 |------|-----|
 | **Old SDK version** | `package.json` → `dependencies["@tomorrowos/sdk"]`, and/or `npm ls @tomorrowos/sdk --depth=0` |
 | **Layout** | Confirm `cms-starter-v0` shape: `cms-app.ts` / `api/index.ts` / `cms-panel/` (or equivalent shared TomorrowOS export) |
-| **Runtime** | Confirm Fluid Function + `vercel.json` rewrites; Output Directory empty |
+| **Runtime** | Confirm Fluid Function + `vercel.json` rewrites; Output Directory empty; **Build Command empty** (`"buildCommand": ""`) |
 
 If `@tomorrowos/sdk` is not a dependency, stop and tell the user this project does not look like a TomorrowOS CMS — offer `VERCEL_SETUP.md` instead. Do **not** run `init` unless they explicitly switch to setup.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Server SDK for building and self-hosting digital signage CMS products with TomorrowOS players.",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -1,14 +1,14 @@
 {
   "name": "my-cms",
-  "version": "1.1.0",
+  "version": "1.1.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "my-cms",
-      "version": "1.1.0",
+      "version": "1.1.4",
       "dependencies": {
-        "@tomorrowos/sdk": "^1.1.0",
+        "@tomorrowos/sdk": "^1.1.4",
         "dotenv": "^17.2.3",
         "tsx": "^4.19.0"
       },

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -12,7 +12,7 @@
     "start": "tsx server.ts"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^1.1.2",
+    "@tomorrowos/sdk": "^1.1.4",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

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

@@ -10,6 +10,11 @@ This starter is for **Vercel Publish** and **v0**. It follows
 - **`preview/`** — Next.js shell for v0 Preview only
 - **`vercel.json`** — `fluid`, rewrites → `/api`, `maxDuration`
 
+**Publish settings (critical):**
+- **Output Directory** = empty / unset (never `public/`)
+- **Build Command** = empty / skip (`"buildCommand": ""` in `vercel.json`) — a defined no-op `npm run build` forces Vercel static-build mode and requires `public/`
+- If the build fails with `The Output Directory "public" is empty` (or public not found): clear Output Directory **and** set Build Command to empty — do **not** add filler files under `public/`
+
 ## Scaffold
 
 ```bash

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

@@ -1,14 +1,14 @@
 {
   "name": "my-cms",
-  "version": "1.1.0",
+  "version": "1.1.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "my-cms",
-      "version": "1.1.0",
+      "version": "1.1.4",
       "dependencies": {
-        "@tomorrowos/sdk": "^1.1.0",
+        "@tomorrowos/sdk": "^1.1.4",
         "dotenv": "^17.2.3",
         "tsx": "^4.19.0"
       },

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

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "TomorrowOS CMS for Vercel / v0 Publish (Fluid Function + WebSockets + optional Next Preview).",
   "private": true,
   "type": "module",
@@ -16,7 +16,7 @@
     "build": "node -e \"process.exit(0)\""
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^1.1.2",
+    "@tomorrowos/sdk": "^1.1.4",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

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

@@ -3,7 +3,7 @@
   "fluid": true,
   "framework": null,
   "installCommand": "npm install",
-  "buildCommand": "npm run build",
+  "buildCommand": "",
   "functions": {
     "api/index.ts": {
       "maxDuration": 300,