@tomorrowos/sdk 1.1.1 → 1.1.3

package/VERCEL_QUESTIONS.md

@@ -1,16 +1,20 @@
 # Vercel / v0 - Verbatim question bank
 
-> **Protocol:** `vercel-questions/1.6` (pairs with `VERCEL_SETUP.md` 1.16+ / `@tomorrowos/sdk` 0.9.70+)  
+> **Protocol:** `vercel-questions/1.7` (pairs with `VERCEL_SETUP.md` 1.18+ / `@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`).**  
 > **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.
+> **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?
 
@@ -18,7 +22,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").
 
 ---
 
@@ -33,7 +37,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?
 
@@ -41,7 +47,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.
 

package/VERCEL_SETUP.md

@@ -5,11 +5,14 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`).
 >
-> Protocol id: `vercel-setup/1.16` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
+> Protocol id: `vercel-setup/1.18` - 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**.  
+> **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`:** blank/skip is valid; can set later. 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**. Build error `Output Directory "public" is empty` means the dashboard still points at `public/` — **clear it**; do **not** “fix” by stuffing `public/robots.txt` while leaving Output = `public`.  
 > **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.
 
@@ -19,6 +22,7 @@ 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 error `The Output Directory "public" is empty`:** This is **not** fixed by adding `public/robots.txt` as the primary solution. It means Project Settings still has Output Directory = `public`. **Clear/unset Output Directory**, confirm Framework = Other, Fluid Function `api/index.ts` + rewrites, then redeploy. Filling `public/` only papers over a wrong static-output setting.
 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:**
@@ -38,10 +42,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 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 must be empty/unset (NOT public). If build says Output Directory public is empty, CLEAR Output Directory — do not stuff public/robots.txt as the fix.
 Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
 Keep cms-starter-v0 layout.
 Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
@@ -114,18 +122,37 @@ 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.
+```
+**Root cause B:** Project Settings **Output Directory is still `public`**, but this CMS has **no** (or empty) static export folder — UI lives in `cms-panel/` and is served by the Fluid Function.
+
+**Correct fix (mandatory for A and B):**
+
+1. Set **Output Directory** = **empty / unset** (dashboard and/or project settings API).
+2. Framework Preset = **Other** / null; Fluid on; `api/index.ts` + rewrites per Scheme A.
+3. Redeploy. Verify `GET /status` is **JSON** and WebSocket is **101**.
 
-**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()`.
+**Forbidden “fixes”:**
+
+- Adding `public/robots.txt` / `.gitkeep` **so a static Output Directory = `public` build passes** — that leaves Production on the static trap path.
+- Setting Output Directory to `cms-panel`, `.`, or `public`.
+- Claiming Publish succeeded because the build log turned green while Output is still `public`.
+
+**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**.
 
@@ -203,7 +230,8 @@ 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.
 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.
@@ -221,13 +249,76 @@ Then ask **Question 1**.
 16. **No inventing CMS login** from a branding URL.
 17. **Skip → invent.** Stay on Q1–Q4 only.
 18. **Publish gate:** `/status` JSON + WebSocket 101; no static `public/` trap.
-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**.
+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.
+
+---
+
+## IRON GATE — v0 Preview hygiene (run after Q&A, before DB rabbit holes)
+
+> **Why this exists:** On v0, agents often answer Q1–Q3, run `init`, then spend a long time “fixing Postgres” while port **3000** is still the original **Next/Turbopack** starter (or a manually spawned `tsx` without injected env). Neon vs Blob choices are **not** the usual cause.
+
+### Do this in order — stop when each check passes
+
+1. **Identify what owns `:3000` (empirical, 30 seconds)**  
+   - If process/logs look like `next-server` / Turbopack / `ENOENT .../app` → you are **not** talking to TomorrowOS yet.  
+   - If `GET /status` returns TomorrowOS **JSON** (`{"status":...}`) → proceed.  
+   - **Forbidden:** debugging `DATABASE_URL` / Neon pooler while `/status` is HTML, Next error overlay, or Turbopack crash.
+
+2. **Clear forbidden root Next leftovers (from the original v0 starter)**  
+   Remove from **project root** (keep the SDK shell under `preview/`):  
+   `app/`, `pages/`, root `next.config.*`, root `next-env.d.ts`, root `postcss.config.*`, leftover `components/` / `lib/` from the starter, `components.json` — anything that makes Framework detection or v0 Preview latch onto Next at root.  
+   **Do not** delete `preview/` (that is the sanctioned Next reverse-proxy shell).  
+   Empty leftover dirs after deleting files.
+
+3. **Confirm scripts + layout**  
+   - Root `package.json` `"dev"` / `"start"` run TomorrowOS (`tsx` …), not `next dev` at root.  
+   - `preview/` exists if Preview stays Next-hardwired; use `dev:preview` (Next public + TomorrowOS on **3001**) when required.  
+   - `cms-panel/` (or template static root) is TomorrowOS UI — **not** Vercel Output Directory `public/`.
+
+4. **Restart the platform-supervised `dev` — do not double-bind**  
+   - After rewriting `package.json` scripts, the **old** supervised `next-server` may still hold `:3000`. Kill/restart so the supervisor re-execs the **new** `dev` script.  
+   - **Forbidden:** spawning a second manual `pnpm dev` / `tsx` that fights the supervised process (`EADDRINUSE`) **and** lacks v0-injected env.  
+   - Prefer the **v0/Vercel managed** process (it inherits injected secrets). Only start TomorrowOS yourself if you also load the same env (see **Env loading trap**).
+
+5. **Prove TomorrowOS before touching DB**  
+   - `GET /status` → **200 JSON** from TomorrowOS (not Next HTML, not `The page could not be found`).  
+   - `GET /` → Control Panel HTML (or CMS login HTML if `CMS_PASSWORD` set).  
+   - Only **then** interpret Database/Media connector errors as real store/media issues.
+
+### Env loading trap (v0 / Preview vs Production)
+
+| Context | How secrets arrive | What `import "dotenv/config"` sees |
+|---------|-------------------|-------------------------------------|
+| **Production Deploy** | Vercel injects into `process.env` | N/A — platform env wins |
+| **v0 / Agent Preview** | Often written to **`.env.development.local`** (and/or injected only into the **supervised** Node process) | **Only `.env`** by default — **not** `.env.development.local` |
+| **Manual Bash `pnpm dev`** | Usually **no** injected `DATABASE_URL` / Blob token unless you export them | Easy false “Postgres broken” |
+
+**Rules:**
+
+- Non-secret flags may live in committed `.env` (`TOMORROWOS_STORE`, `DATABASE_SSL`, `TOMORROWOS_MEDIA`).  
+- Secrets (`DATABASE_URL`, `SUPABASE_URL`, `BLOB_READ_WRITE_TOKEN`, `CMS_PASSWORD`, Cloudinary keys) belong in **Vercel Env** / v0 injection — never commit them.  
+- If logs say store=`postgres` but `DATABASE_URL` is missing in a **manual** process: load `.env` **and** `.env.development.local`, or restart the **supervised** server — do **not** immediately change Neon URLs.  
+- Preview flakes ≠ Production failure. Fix Preview hygiene first; do not “repair” Production Framework because Preview 500’d.
 
-**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 optional `CMS_PASSWORD` -> execution checklist.
+### Preview decision tree (after hygiene)
+
+```
+Is GET /status TomorrowOS JSON on the Preview URL?
+  YES → continue checklist (Publish gates still required).
+  NO → What owns the public port?
+        next-server / Turbopack / ENOENT app/ → clear root Next + restart supervised dev (steps 2–4).
+        tsx TomorrowOS listening but Preview blank → v0 still hardwires Next: use preview/ reverse-proxy + TOMORROWOS_INTERNAL_PORT=3001 + dev:preview.
+        EADDRINUSE :3000 → kill stale Next/tsx; one process only.
+```
+
+**Reminder:** Q1 Neon / Q2 Blob are valid protocol choices. A long Preview outage after those answers is almost always **process/layout/env injection**, not “wrong database/media product.”
 
 ---
 
-## Scheme A ??Vercel Functions + WebSockets (mandatory for Production)
+## Scheme A — Vercel Functions + WebSockets (mandatory for Production)
 
 > **Goal:** Preview may use Next + proxy; **Publish** runs TomorrowOS as a **Vercel Function** (`api/index.ts`) on **Fluid**, with WebSocket support per [Vercel WebSockets docs](https://vercel.com/docs/functions/websockets).  
 > **Scope:** Layout + `vercel.json` + dashboard. Prefer `npx @tomorrowos/sdk@latest init --hosting v0` (`cms-starter-v0`).  
@@ -351,16 +442,20 @@ SDK behaviour (0.9.32+):
 - `"buildCommand"` = no-op ??**never** `next build` for Production
 - Dashboard Output Directory must stay **empty**
 
-### 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** |
+| **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`:** the dashboard still has Output = `public`. **Clear/unset it** via Project Settings (or settings API), then redeploy. Do **not** add `public/robots.txt` (or any static filler) as the primary fix while Output stays `public`.
+
+**`vercel.json` must not set `outputDirectory`.** Leaving it out is correct; dashboard Output must still be forced empty because Framework=Other may default to “public if it exists”.
 
 ### A5 ??Publish acceptance (all must pass)
 
@@ -511,12 +606,14 @@ const server = tomorrowos.listen({
 export default server;
 ```
 
-- **Production:** `PORT` from Vercel ??TomorrowOS listens on that port (no Next).
+- **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.
+Load env with `dotenv` for local/`vercel dev` (loads **`.env` only**). On production Deploy, Vercel injects Environment Variables natively.
+
+**v0 / Preview caveat:** platform secrets often land in **`.env.development.local`** or only in the **supervised** process env. TomorrowOS `import "dotenv/config"` does **not** auto-load `.env.development.local`. See **IRON GATE — Env loading trap**. Never treat a manual Bash server missing `DATABASE_URL` as proof that Neon is misconfigured.
 
-### Preview adapter (v0 / Next reverse proxy) ??required when Preview is Next-hardwired
+### 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:
 
@@ -612,17 +709,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`).
+> **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).
->
-> 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**
 
@@ -678,19 +784,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.
+
+**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 paste the block above instead**.
+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**)
 
@@ -874,26 +987,36 @@ Set `cmsEndpoint` only if they already know the public `https://?vercel.app` URL
 
 ---
 
-## After all answers ? execution checklist
+## After all answers — execution checklist
+
+### A0. IRON GATE first (mandatory)
+
+Complete **IRON GATE — v0 Preview hygiene** before long Postgres/media debugging:
+
+1. Prove `GET /status` is TomorrowOS JSON (or clear root Next + restart supervised `dev` until it is).
+2. Remove root `app/` / `next.config.*` leftovers; keep `preview/` only for the proxy shell.
+3. Do not spawn a second manual server that lacks injected env / fights `:3000`.
+4. Only then treat Database/Media connector errors as real.
 
 ### A. Seed the project
 
 ```bash
-npx @tomorrowos/sdk@latest init .
+npx @tomorrowos/sdk@latest init . --hosting v0
 # If not empty and user confirms starter overwrite:
-# npx @tomorrowos/sdk@latest init . --force
+# npx @tomorrowos/sdk@latest init . --hosting v0 --force
 ```
 
-Then (**Scheme A ??mandatory for Publish**):
+Then (**Scheme A — mandatory for Publish**):
 
 1. Keep **`server.ts`** at **project root** with top-level `listen()` + `export default server`.
-2. If Preview needs Next: **move** `next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts` into **`preview/`** ??remove them from root so Production is not mistaken for Next/static.
-3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, no-op `buildCommand` ??**no** `startCommand`).
-4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory empty, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js.
+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/unset**, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js **or** Output = `public`.
+4a. **Pre-Publish Output check:** If settings show Output Directory = `public` (or build fails with `Output Directory "public" is empty`), **clear Output Directory** and redeploy. Do **not** add `public/robots.txt` to satisfy a static output path.
 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).
-
+8. **Restart** the platform-supervised Preview `dev` after script/layout changes (stale `next-server` is the #1 false “DB failure”).
 ### B. Environment Variables (Vercel dashboard + local)
 
 | Name | Required | Who fills it |
@@ -909,14 +1032,16 @@ Then (**Scheme A ??mandatory for Publish**):
 | `PORT` | Optional | Vercel injects for Production |
 | `CMS_PASSWORD` | Optional (Q4) | User if set; blank/skip = omit (can add later) |
 
-Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit secrets.
+Mirror non-secrets in `.env` for local `npm run start` if helpful; never commit secrets.  
+On v0 Preview, secrets may exist only in **`.env.development.local`** / supervised env — see **Env loading trap**. Do not “fix Neon” until the process that serves `/status` actually has `DATABASE_URL` / `SUPABASE_URL`.
 
 ### C. Install and run
 
 ```bash
 npm install
 npm run start
-# Preview / v0: npm run dev:preview  (Next + TomorrowOS internal)
+# Preview / v0 when Next-hardwired: npm run dev:preview  (Next :3000 + TomorrowOS :3001)
+# After changing package.json "dev": restart the supervised process — do not leave stale next-server on :3000
 ```
 
 Confirm logs: `[TomorrowOS] listening on http://0.0.0.0:?`  
@@ -994,6 +1119,14 @@ More detail: https://docs.tomorrowos.org/docs/os/tizen and https://docs.tomorrow
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Build: `Output Directory "public" is empty` | Dashboard Output Directory still = `public` on a Function/CMS app | **Unset Output Directory**; Framework Other; Fluid `api/index.ts`; redeploy. Do **not** primary-fix with `public/robots.txt` |
+| 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) |
+| 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"` |
+| Preview still Next after `package.json` `"dev"` → `tsx` | Supervised process never restarted | Kill old tree; wait for supervisor / restart Preview |
+| Agent spent many turns on Postgres before `/status` JSON | Skipped IRON GATE | Stop; run hygiene steps 1–5; only then debug store |
+| Q1=Neon / Q2=Blob then long Preview outage | Usually **not** the product choice | Same as root-Next / env-injection failures; choices are valid |
 | Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Function | Scheme A: Framework = **Other**, Fluid on, `api/index.ts` + rewrites; redeploy |
 | Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** ??no Function | Rename to `cms-panel/`; Output empty; Scheme A Function entry; **Path B** if needed |
 | Only `/api/status` returns JSON, `/status` is 404 | Missing **rewrites** to `/api` | Add Scheme A3 rewrite `/(.*) ??/api` (exclude existing `/api/`); redeploy |
@@ -1069,7 +1202,11 @@ Protocol complete when:
 
 ## Protocol version
 
-`vercel-setup/1.16` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.6.
+`vercel-setup/1.18` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.7.
+
+**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.
 
 **Changelog 1.16:** Question 4 is optional Control Panel Env `CMS_PASSWORD` (blank/skip allowed; can set later). Do not use Vercel Deployment Protection / whole-site password for devices.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "my-cms",
-      "version": "1.1.0",
+      "version": "1.1.3",
       "dependencies": {
-        "@tomorrowos/sdk": "^1.1.0",
+        "@tomorrowos/sdk": "^1.1.3",
         "dotenv": "^17.2.3",
         "tsx": "^4.19.0"
       },

package/templates/cms-starter/package.json

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

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

@@ -10,6 +10,8 @@ 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 setting (critical):** Vercel **Output Directory** must stay **empty / unset**. If the build fails with `The Output Directory "public" is empty`, clear Output Directory in Project Settings — do **not** add filler files under `public/` while Output is still set to `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.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "my-cms",
-      "version": "1.1.0",
+      "version": "1.1.3",
       "dependencies": {
-        "@tomorrowos/sdk": "^1.1.0",
+        "@tomorrowos/sdk": "^1.1.3",
         "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.1",
+  "version": "1.1.3",
   "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.1",
+    "@tomorrowos/sdk": "^1.1.3",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },