@tomorrowos/sdk 0.9.24 → 0.9.26

package/README.md

@@ -73,8 +73,8 @@ IF any step contradicts Vercel, adapt to settings that Vercel can accept.
 
 That wizard asks: database (**Supabase** → **Neon** → SQLite demo), media (**Cloudinary** → **Vercel Blob** → local),
 branding (manual fields or **website URL → `brand.json` only**, no login unless asked). Preview may use a thin **Next.js reverse proxy**;
-**Publish stays pure Node** `TomorrowOS.listen` (not Next). Cloudinary credentials are collected one-at-a-time
-(cloud name → API key → API secret). Sets `cms.hostingTarget` to `"vercel"`.
+**Publish stays pure Node** `TomorrowOS.listen` (Framework Preset = Other — gate on no `404 NOT_FOUND`). Cloudinary uses **one Env popup** (all fields).
+Neon/Supabase: agent auto-sets `TOMORROWOS_STORE` + `DATABASE_SSL`. Sets `cms.hostingTarget` to `"vercel"`.
 
 ### Replit upgrade (existing CMS)
 

package/VERCEL_SETUP.md

@@ -5,7 +5,7 @@
 >
 > **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
 >
-> Protocol id: `vercel-setup/1.3` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> Protocol id: `vercel-setup/1.5` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
 
 ## User trigger (copy-paste)
 
@@ -14,10 +14,12 @@ When a human pastes a prompt like this, **read this file and start Question 1 im
 ```text
 Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
 Ask only the questions listed in VERCEL_SETUP.md, in order. Do not use LLM_PROMPT.md or REPLIT_SETUP.md.
+Do not ask for OpenAI / Anthropic / any LLM API keys — TomorrowOS CMS setup does not require them.
 If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation).
 After all setup questions are answered (including Cloudinary or Vercel Blob Env Vars if you chose those), configure and deploy — minimal verification only (Control Panel at /). Prefer Supabase Session pooler URL or Neon pooled URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when a pooler URL is configured for production.
 Question 3 only updates brand.json from colours/logo/name (a website URL is brand reference only — do not add CMS login/auth unless the user explicitly asks). Do not skip steps.
 Use Next.js only as a v0/Preview shell with a reverse proxy; Production Publish must remain pure Node TomorrowOS.listen (not Next).
+Before claiming Publish works: Framework Preset must be Other/null (not Next.js), startCommand must run TomorrowOS Node, and GET / on the production URL must return the Control Panel (not 404 NOT_FOUND).
 ```
 
 Alternate triggers:
@@ -43,6 +45,7 @@ TomorrowOS CMS is **one Node process** that serves:
 | Required | Forbidden |
 |----------|-----------|
 | Single **Node HTTP server** entry (`tsx server.ts` / exported `http.Server` from `listen()`) | **Next.js as the Production CMS** (`next start`, Next App Router as the live app) |
+| **Framework Preset = Other / `null`** (dashboard **and** project settings API) | Leaving Framework Preset as **Next.js** (causes `404: NOT_FOUND`) |
 | **Fluid compute** enabled (needed for WebSockets on Vercel) | Classic short-lived serverless with no WebSocket / no Fluid |
 | Durable store = **Postgres** (Supabase or Neon, pooled URL) | **SQLite / `data/*.db` as production store** on Vercel (ephemeral filesystem) |
 | Media = **Cloudinary** or **Vercel Blob** (durable HTTPS URLs) | Relying on local `public/uploads` alone for production fleets |
@@ -51,6 +54,34 @@ TomorrowOS CMS is **one Node process** that serves:
 
 **Publish / Production Deploy** must run **`TomorrowOS.listen(...)`** directly. Do **not** put Next.js in front of Production traffic.
 
+### Publish `404: NOT_FOUND` — mandatory prevention (read before every deploy)
+
+The production URL showing:
+
+```text
+404: NOT_FOUND
+Code: NOT_FOUND
+```
+
+almost always means **Vercel still thinks this is a Next.js / static deploy**, not a Node TomorrowOS server.
+
+**Before every Production deploy, you MUST verify all of the following:**
+
+1. **Project → Settings → General → Framework Preset = Other** (or unset / null).  
+   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.
+4. **Start / Dev Command for Production** = `npm run start` / `pnpm start` → **`tsx server.ts`** (or `.mts`) that calls `TomorrowOS.listen` and **`export default server`**.
+5. **Output Directory** = **empty / unset**. Do **not** set `outputDirectory: "."` as a fake static site.
+6. **Do not** create a root `api/index.ts` that exports a raw `http.Server` and catch-all `routes` to “fix” 404 — Vercel Fluid does **not** treat that as a supported handler for this CMS. That pattern causes more 404s.
+7. If Preview needs Next, keep Next files **isolated** so Production auto-detect cannot latch onto them:
+   - Prefer `preview/` (or similar) for `next.config.*`, `app/`, `pages/` used only by v0 Preview, **or**
+   - Ensure Production Framework Preset is forced to **Other** and Start Command never runs `next`.
+
+**Setup is NOT complete** while Production `GET /` returns `404: NOT_FOUND`. Fix Framework Preset + Start Command and redeploy.
+
 ### Preview (v0 / Vercel Agent sandbox) — Next.js shell allowed
 
 v0 Preview is often a **Next.js runtime** hardwired to `next dev`. A raw `tsx server.ts` may listen successfully while Preview still shows a blank page, because the sandbox intercepts the public port with Next before requests reach TomorrowOS.
@@ -82,6 +113,17 @@ Ask **only** these questions, in **this exact order**:
 
 **That is the complete list.** Do **not** ask how many screens / devices.
 
+**Forbidden extra questions (never ask, even if the user skips a step):**
+
+- ❌ OpenAI / Anthropic / Gemini / any LLM API key (`sk-…`, etc.)
+- ❌ “AI pairing”, “AI feature logic”, or inventing auth that needs an LLM key
+- ❌ Asking the user to type `TOMORROWOS_STORE` or `DATABASE_SSL` after they already chose Neon/Supabase — **you set those automatically**
+- ❌ Any secret not listed in Questions 1–3 (DB URL, media credentials, brand)
+
+TomorrowOS pairing and Control Panel logic live in `@tomorrowos/sdk`. They do **not** call OpenAI.
+
+If the user **skips** a Question 2 option, do **not** invent a substitute question. Re-state Question 2 choices, or proceed with a documented default (e.g. local uploads with a warning) — never pivot to LLM keys.
+
 If the user says “just set it up, don’t ask questions,” respond:
 
 > I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage, and branding). It takes about a minute and ensures the CMS works on Vercel.
@@ -92,10 +134,10 @@ Then ask **Question 1**.
 
 ## Hard rules
 
-1. **Ask only VERCEL_SETUP.md questions 1–3.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire.
-2. **One question / one credential at a time.** For Cloudinary: ask **cloud name**, then **API key alone**, then **API secret alone** — never one message that mixes key + secret.
-3. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, or brand colours.
-4. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** (or `NEON_DATABASE_URL`) when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
+1. **Ask only VERCEL_SETUP.md questions 1–3.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire. **Never** ask for OpenAI or other LLM API keys.
+2. **Cloudinary:** open **one** Vercel Env configuration popup / form with **all** Cloudinary fields together (cloud name + API key + API secret). Do **not** quiz the user one credential at a time in chat.
+3. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
+4. **Postgres env naming:** prefer **`SUPABASE_URL`** when using Supabase; prefer **`DATABASE_URL`** when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
 5. **Always prefer pooled connection strings** (Supabase Session pooler port **6543**; Neon pooled host). Direct `:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
 6. **Prefer `npx @tomorrowos/sdk init`** (or `templates/cms-starter`) as the seed. Do not rebuild pairing / WebSocket / playlist APIs.
 7. **Never commit secrets.** Use Vercel Environment Variables (+ optional non-secret flags in committed `.env.example`).
@@ -106,6 +148,9 @@ Then ask **Question 1**.
 12. **Preview:** if the environment is v0 / Next-hardwired, install the Next reverse-proxy shell (see **Preview adapter**). Do not leave Preview broken.
 13. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/`). Do not run a long test suite.
 14. **No inventing CMS login.** A branding URL never means “build auth.” Only add login if the user **explicitly** requests it.
+15. **Skip ≠ invent.** If the user skips media choice or a credential, do not replace it with OpenAI/auth/login questions. Stay on Q1–Q3 only.
+16. **Neon / Supabase helpers are agent-owned.** After the user pastes the DB URL, **you** set `TOMORROWOS_STORE` and `DATABASE_SSL` automatically — **do not** ask the user to fill those two.
+17. **Publish gate:** do not mark setup complete while Production returns `404: NOT_FOUND`. Fix Framework Preset + Start Command first (see **Publish 404** section).
 
 **Question order:** Q1 → Q2 → Q3 → execution checklist.
 
@@ -115,11 +160,11 @@ Then ask **Question 1**.
 
 ### Production runtime (Publish)
 
-- Serve with **`tsx server.ts`** (or compiled Node that still calls `TomorrowOS.listen` with `staticRoot`).
+- Serve with **`tsx server.ts`** (or `server.mts` / compiled Node that still calls `TomorrowOS.listen` with `staticRoot`).
 - Keep **`@tomorrowos/sdk`** and put **`tsx` in `dependencies`** (not only `devDependencies`) if production runs via `tsx`.
 - Node **20+**.
 - **Do not** replace the SDK with a hand-rolled server that drops WebSocket upgrades.
-- **Forbidden as the Production Deploy entrypoint:** `next start`, static export only, or any command that does not start `TomorrowOS.listen(...)`.
+- **Forbidden as the Production Deploy entrypoint:** `next start`, static export only, root `api/` fake catch-all for raw `http.Server`, or any command that does not start `TomorrowOS.listen(...)`.
 
 ### Expected `package.json` scripts
 
@@ -131,7 +176,7 @@ Then ask **Question 1**.
     "dev:tomorrowos": "cross-env PORT=3001 TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
     "dev:next": "next dev -p 3000",
     "start": "tsx server.ts",
-    "build": "echo \"Production is Node — no Next production build required\""
+    "build": "node -e \"process.exit(0)\""
   }
 }
 ```
@@ -139,6 +184,7 @@ Then ask **Question 1**.
 Adapt script names / process runners as needed. **Invariant:**
 
 - **`npm start` / Production** = TomorrowOS Node only.
+- **`build`** = no-op exit 0 (never `next build` for Production).
 - **Preview / v0** = Next on public port + TomorrowOS on internal port + proxy.
 
 ### Minimal dependencies (Production)
@@ -160,7 +206,8 @@ Adapt script names / process runners as needed. **Invariant:**
   },
   "scripts": {
     "dev": "tsx watch server.ts",
-    "start": "tsx server.ts"
+    "start": "tsx server.ts",
+    "build": "node -e \"process.exit(0)\""
   }
 }
 ```
@@ -173,6 +220,8 @@ For Preview shell only, add as needed: `next`, `react`, `react-dom`, and a proce
 
 ### `server.ts` pattern (Vercel-adapted — Production)
 
+Keep the server at **project root** (e.g. `server.ts` / `server.mts`). Do **not** move Production into `api/` solely to satisfy Vercel routing myths.
+
 ```ts
 import "dotenv/config";
 import { readFileSync } from "fs";
@@ -218,12 +267,12 @@ Load env with `dotenv` for local/`vercel dev`. On production Deploy, Vercel inje
 
 Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs “listening”). Then:
 
-1. Keep a **minimal** Next app (App Router or Pages — whichever the sandbox expects).
+1. Keep a **minimal** Next app **isolated when possible** (e.g. under `preview/`) so Production Framework detection does not latch onto root `next.config.*`.
 2. TomorrowOS listens on **`127.0.0.1:TOMORROWOS_INTERNAL_PORT`** (default **3001**).
 3. Add a **catch-all** Next route (or middleware) that proxies HTTP to TomorrowOS:
 
 ```ts
-// Example: app/api/tomorrowos-proxy/[...path]/route.ts or a rewrite + route handler
+// Example: preview app proxy handler
 // Forward method, headers, and body to http://127.0.0.1:3001/<path>
 // Return the upstream status, headers, and body to the browser.
 ```
@@ -238,24 +287,41 @@ Preferred UX: proxy **`/`** itself (rewrites) so the Preview URL shows the Contr
 - Making Next the Production CMS or the only server after Publish.
 - Deleting TomorrowOS `server.ts` because Preview needed Next.
 - Claiming setup complete if Production entrypoint is still `next start`.
+- Claiming setup complete if Production `GET /` is `404: NOT_FOUND`.
+- Creating root `api/index.*` + `routes` catch-all that exports a raw `http.Server` “to fix 404”.
 
-### `vercel.json` (recommended minimum — Production)
+### `vercel.json` (Production — explicit Node, not Next)
 
-Adapt to the project’s current Vercel Node-server / Fluid conventions. At minimum ensure:
+Write `vercel.json` so Production cannot be mistaken for Next. Minimum:
 
 ```json
 {
-  "fluid": true
+  "fluid": true,
+  "framework": null,
+  "installCommand": "npm install",
+  "buildCommand": "npm run build",
+  "outputDirectory": null
 }
 ```
 
-Also:
+Use `pnpm` / `yarn` variants of install/build if that is the project’s package manager.
+
+**Also force Project Settings (dashboard or Vercel API) — this is mandatory:**
+
+| Setting | Required value |
+|---------|----------------|
+| 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** |
+| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) |
+| Fluid compute | **On** |
+
+If `next` / `next.config.*` exist for Preview and the dashboard still auto-selects Next.js:
 
-1. Project → **Fluid compute** enabled (required for WebSockets on Publish).
-2. Framework Preset for **Production:** **Other** (or Node) — **not** Next.js as the live CMS.
-3. Install / Start commands for **Production** must end in running the CMS Node server (e.g. `npm run start` → `tsx server.ts`).
-4. Do **not** enable “Output Directory” static-only hosting for this CMS.
-5. If the project also contains a Next Preview shell, configure Vercel so **Production Deploy ignores Next as the app** (Node `server.ts` / `export default server` remains the capture path). Document any dashboard setting you change.
+1. Patch Framework Preset to **Other** via API/CLI/dashboard.
+2. Redeploy.
+3. Hit Production `GET /` — must be Control Panel HTML, not `404: NOT_FOUND`.
 
 If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a single long-lived Node HTTP server with WebSocket upgrade on `/` for Production**. Document the adaptation in the final summary.
 
@@ -270,6 +336,7 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 - ❌ `.replit`, `.replit-artifact`
 - ❌ Next.js as the **Production** CMS (App Router replacing TomorrowOS)
+- ❌ Root `api/` catch-all exporting raw `http.Server` to “fix” Publish 404
 - ❌ Separate “API project” without the Control Panel
 - ❌ Committing database passwords, Cloudinary secrets, or Blob tokens
 
@@ -295,52 +362,47 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 ### Step B — If **1 / Supabase**
 
-**Ask exactly:**
+**Ask exactly (connection string only):**
 
-> Paste your Supabase Postgres connection string. I will store it as the Vercel Environment Variable **`SUPABASE_URL`**.
+> Paste your Supabase Postgres connection string. I will store it as **`SUPABASE_URL`**.
 >
 > In Supabase: **Project Settings → Database → Connection string → Connection pooling** (Session mode).  
 > Preferred shape:  
 > `postgresql://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres`
 >
-> **Do not** use the direct host `db.*.supabase.co:5432` for Vercel — sandbox/serverless often fails with `ENETUNREACH` (commonly on IPv6).
->
-> Confirm SSL is required (usually **yes** for Supabase).
+> **Do not** use the direct host `db.*.supabase.co:5432` for Vercel.
 
-**You must then:**
+**You must then (automatic — do NOT ask the user to type these):**
 
-1. Set Vercel Env Vars (Production + Preview + Development as appropriate):
-   - `SUPABASE_URL=<pooler string>`
-   - `TOMORROWOS_STORE=supabase`
-   - `DATABASE_SSL=true` (unless user explicitly disables SSL)
+1. Set Vercel Env Vars:
+   - `SUPABASE_URL=<user pooler string>`
+   - `TOMORROWOS_STORE=supabase` ← **agent sets this**
+   - `DATABASE_SSL=true` ← **agent sets this** (unless user already said SSL is off)
 2. Wire `server.ts` as in **Runtime & Vercel deploy rules**.
-3. Optional committed `.env.example` with **placeholders only** (no real password).
+3. Optional committed `.env.example` with **placeholders only**.
 4. **Do not** commit the real connection string.
-5. **Configuration over probing:** if local/`vercel dev` still shows `ENETUNREACH` / IPv6 errors, verify the string is the **pooler** (`pooler.supabase.com` + `:6543`). Treat remaining sandbox DNS issues as non-fatal when Production deploy Env Vars are correct — but **do** fix an obvious direct `:5432` URL before finishing.
+5. **Do not** open a second form asking for `TOMORROWOS_STORE` or `DATABASE_SSL`.
 
 ### Step C — If **2 / Neon**
 
-**Ask exactly:**
+**Ask exactly (connection string only):**
 
-> Paste your **Neon pooled** Postgres connection string. I will store it as **`DATABASE_URL`** (or `NEON_DATABASE_URL` if you prefer — wire whichever you set in `server.ts`).
+> Paste your **Neon pooled** Postgres connection string. I will store it as **`DATABASE_URL`**.
 >
-> In Neon: **Dashboard → Connection details → Pooled connection** (enable pooling).  
+> In Neon: **Dashboard → Connection details → Pooled connection**.  
 > Typical shape:  
-> `postgresql://[user]:[password]@[endpoint].pooler.[region].aws.neon.tech/[dbname]?sslmode=require`
->
-> **Do not** use the direct (non-pooled) connection string for Vercel serverless unless Neon docs explicitly say otherwise for your plan.
->
-> Confirm SSL (`sslmode=require`) is on (usually **yes**).
+> `postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require`
 
-**You must then:**
+**You must then (automatic — do NOT ask the user to type these):**
 
 1. Set Vercel Env Vars:
-   - `DATABASE_URL=<pooled Neon string>` (or `NEON_DATABASE_URL` + read it in `server.ts`)
-   - `TOMORROWOS_STORE=postgres`
-   - `DATABASE_SSL=true` (unless user explicitly disables SSL)
+   - `DATABASE_URL=<user pooled string>`
+   - `TOMORROWOS_STORE=postgres` ← **agent sets this**
+   - `DATABASE_SSL=true` ← **agent sets this**
 2. Wire `server.ts` — `createTomorrowOSStore` uses `PostgresStore` for `postgres` / `supabase` drivers.
 3. **Do not** commit the real connection string.
-4. Same pooler guidance as Supabase: if you see `ENETUNREACH` on `:5432`, switch to Neon’s **pooled** URL.
+4. **Do not** ask the user to fill `TOMORROWOS_STORE` or `DATABASE_SSL` in chat or in an Env popup. Those are derived from choosing Neon.
+5. If you see `ENETUNREACH` on `:5432`, switch to Neon’s **pooled** URL.
 
 ### Step D — If **3 / SQLite**
 
@@ -350,9 +412,9 @@ If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a s
 
 Only proceed after the user explicitly confirms.
 
-**You must then:**
+**You must then (automatic):**
 
-1. Set `TOMORROWOS_STORE=sqlite` (or omit `DATABASE_URL` / `SUPABASE_URL` so the factory defaults to SQLite).
+1. Set `TOMORROWOS_STORE=sqlite` yourself (do not ask the user to type it).
 2. Keep `sqlitePath` in `server.ts` for `data/tomorrowos.db`.
 3. Warn again in the final summary that they should move to Supabase or Neon for real devices.
 
@@ -362,6 +424,9 @@ Only proceed after the user explicitly confirms.
 
 ## Question 2 — Media storage
 
+> **This question is only about media files (images/videos).**  
+> 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.
+
 ### Step A — Ask storage choice
 
 **Ask exactly:**
@@ -376,46 +441,33 @@ Only proceed after the user explicitly confirms.
 >
 > Reply with **1**, **2**, or **3** (or “Cloudinary” / “Vercel Blob” / “local”).
 
-### Step B — If **1 / Cloudinary** (same Question 2 — sequential prompts)
-
-> **Critical UX rule:** Collect Cloudinary credentials in **separate messages**. Never ask for API key and API secret in the same message or the same form field group.
-
-#### B1 — Cloud name (ask alone)
-
-**Ask exactly:**
-
-> Paste your Cloudinary **Cloud name** only (`CLOUDINARY_CLOUD_NAME`).  
-> Find it at [cloudinary.com/console](https://cloudinary.com/console) → Dashboard.
-
-Save as Vercel Env Var `CLOUDINARY_CLOUD_NAME`. Do **not** ask for key or secret yet.
+### Step B — If **1 / Cloudinary** (same Question 2 — **one Env popup**)
 
-#### B2 — API key (ask alone — after B1 is saved)
+> **Critical UX rule:** Immediately open the **Vercel Environment Variables configuration popup / form** with **all Cloudinary fields in one UI**. Do **not** ask for cloud name, then key, then secret in separate chat messages.
 
-**Ask exactly:**
-
-> Paste your Cloudinary **API Key** only (`CLOUDINARY_API_KEY`).  
-> Do not paste the API Secret in this step.
-
-Save as Vercel Env Var `CLOUDINARY_API_KEY`. Do **not** ask for the secret in this message.
-
-#### B3 — API secret (ask alone — after B2 is saved)
-
-**Ask exactly:**
+**Preferred:** Vercel Env Vars UI (or Agent secrets form) with these fields together:
 
-> Paste your Cloudinary **API Secret** only (`CLOUDINARY_API_SECRET`).  
-> This is the last Cloudinary credential.
+| Field | Env name | Required |
+|-------|----------|----------|
+| Cloud name | `CLOUDINARY_CLOUD_NAME` | Yes |
+| API Key | `CLOUDINARY_API_KEY` | Yes |
+| API Secret | `CLOUDINARY_API_SECRET` | Yes |
+| Folder (optional) | `CLOUDINARY_FOLDER` | No (e.g. `tomorrowos`) |
 
-Save as Vercel Env Var `CLOUDINARY_API_SECRET`.
+**If a multi-field popup is unavailable, ask once in a single message** (still not three turns):
 
-Optional fourth message (only if useful):
-
-> Optional: Cloudinary folder name (`CLOUDINARY_FOLDER`, e.g. `tomorrowos`). Press Enter to skip.
+> Paste Cloudinary credentials from [cloudinary.com/console](https://cloudinary.com/console) (I will store them as Vercel Env Vars):
+>
+> 1. `CLOUDINARY_CLOUD_NAME`
+> 2. `CLOUDINARY_API_KEY`
+> 3. `CLOUDINARY_API_SECRET`
+> 4. optional `CLOUDINARY_FOLDER`
 
 **You must then:**
 
-1. Confirm all three required Env Vars exist: `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`.
+1. Save all three required Env Vars for Production + Preview + Development as appropriate.
 2. **Do not** invent placeholders.
-3. **Do not** proceed to Question 3 until all three exist.
+3. **Do not** proceed to Question 3 until all three required vars exist.
 4. **Do not** run a formal Cloudinary upload test unless the user asks.
 
 The SDK auto-detects these env vars.
@@ -433,7 +485,7 @@ The SDK auto-detects these env vars.
 
 **You must then:**
 
-1. Set Vercel Env Var: `BLOB_READ_WRITE_TOKEN=<token>` (if not auto-injected).
+1. Set Vercel Env Var: `BLOB_READ_WRITE_TOKEN=<token>` (if not auto-injected). Prefer the Env popup when available.
 2. `npm install @vercel/blob` (add to `dependencies`).
 3. Wire uploads so media returns **absolute HTTPS Blob URLs** stored in `uploaded_assets` (players need stable public URLs).
    - The SDK **natively auto-detects Cloudinary** today. For Vercel Blob, add a thin upload bridge in the CMS project (e.g. custom route or middleware that calls `put()` from `@vercel/blob` and persists the returned `url` the same way Cloudinary URLs are stored).
@@ -561,26 +613,26 @@ npx @tomorrowos/sdk@latest init .
 
 Then:
 
-1. Keep TomorrowOS `server.ts` as the **Production** app (**export `listen()` HTTP server**).
-2. If the environment is **v0 / Next Preview**, add the **Preview adapter** (Next shell + reverse proxy + internal TomorrowOS port). Do **not** make Next the Production CMS.
-3. Add/adjust `vercel.json` with **`fluid: true`** (or enable Fluid in the dashboard) for Publish.
-4. Ensure Production start command is **`npm run start` → `tsx server.ts`** (or equivalent Node), **not** `next start`.
-5. Do **not** add `.replit*`.
-6. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
+1. Keep TomorrowOS `server.ts` / `server.mts` at **root** as the **Production** app (**export `listen()` HTTP server**).
+2. If the environment is **v0 / Next Preview**, add the **Preview adapter** (Next shell + reverse proxy + internal TomorrowOS port). Isolate Next configs when possible. Do **not** make Next the Production CMS.
+3. Write `vercel.json` with **`fluid: true`**, **`framework: null`**, no-op **`buildCommand`**, and **empty outputDirectory**.
+4. **Force Project Settings:** Framework Preset = **Other**, Start Command = `npm run start` (Node), Fluid on.
+5. Ensure Production start command is **`tsx server.ts`** (or `.mts`), **not** `next start`.
+6. Do **not** add root `api/` catch-all for raw `http.Server`.
+7. Do **not** add `.replit*`.
+8. If Q2 = Vercel Blob: install `@vercel/blob` and wire the upload bridge.
 
 ### B. Environment Variables (Vercel dashboard + local)
 
-| Name | Required | Notes |
-|------|----------|--------|
-| `SUPABASE_URL` | If Q1 = Supabase | **Session pooler** `:6543` |
-| `DATABASE_URL` | If Q1 = Neon | **Pooled** Neon string |
-| `TOMORROWOS_STORE` | Yes | `supabase`, `postgres`, or `sqlite` |
-| `DATABASE_SSL` | Yes (typical) | `true` |
-| `CLOUDINARY_CLOUD_NAME` | If Q2 = Cloudinary | Collected alone (B1) |
-| `CLOUDINARY_API_KEY` | If Q2 = Cloudinary | Collected alone after cloud name (B2) |
-| `CLOUDINARY_API_SECRET` | If Q2 = Cloudinary | Collected alone after API key (B3) |
-| `BLOB_READ_WRITE_TOKEN` | If Q2 = Vercel Blob | From Vercel Blob store |
-| `TOMORROWOS_INTERNAL_PORT` | Preview only | e.g. `3001` when Next owns `:3000` |
+| Name | Required | Who fills it |
+|------|----------|--------------|
+| `SUPABASE_URL` | If Q1 = Supabase | User pastes URL |
+| `DATABASE_URL` | If Q1 = Neon | User pastes URL |
+| `TOMORROWOS_STORE` | Yes | **Agent auto-sets** (`supabase` / `postgres` / `sqlite`) |
+| `DATABASE_SSL` | Yes for Postgres | **Agent auto-sets** `true` |
+| `CLOUDINARY_*` | If Q2 = Cloudinary | User via **one Env popup** (all fields) |
+| `BLOB_READ_WRITE_TOKEN` | If Q2 = Vercel Blob | User / Blob link |
+| `TOMORROWOS_INTERNAL_PORT` | Preview only | Agent (e.g. `3001`) |
 | `PORT` | Optional | Vercel injects for Production |
 
 Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit secrets.
@@ -606,12 +658,15 @@ vercel --prod
 # or git push → Vercel Git integration
 ```
 
-Before finishing, verify Production settings:
+**Publish acceptance checklist (all must pass):**
 
-1. Start / entry = **Node `TomorrowOS.listen`** (`npm run start` / exported `server`)
-2. **Not** `next start` as Production
+1. Framework Preset = **Other** / null (dashboard confirms — not Next.js)
+2. Start Command = Node `TomorrowOS.listen` (`npm run start`)
 3. Fluid compute on
-4. Env Vars present for Production environment
+4. Env Vars present for Production
+5. Production `GET /` returns Control Panel HTML — **not** `404: NOT_FOUND`
+
+If step 5 fails: do **not** invent `api/` + `routes`. Patch Framework Preset + Start Command, redeploy, re-check `/`.
 
 Tell the user:
 
@@ -624,7 +679,7 @@ Tell the user:
 **Do:**
 
 1. Preview: Control Panel HTML at `/` (via Next proxy if applicable)
-2. Publish: Control Panel HTML at `/` from **Node** TomorrowOS
+2. Publish: Control Panel HTML at `/` from **Node** TomorrowOS (block on `404: NOT_FOUND`)
 3. Server status: Media OK when Cloudinary or Blob configured
 4. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
 5. Fluid compute on for Production
@@ -637,6 +692,8 @@ Tell the user:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Node start | Set Framework = **Other**, Start = `npm run start`, Fluid on; redeploy. Do **not** add root `api/` catch-all |
+| Build runs `next build` / missing routes-manifest | Next auto-detected from `next.config` / deps | Force Framework null/Other; `build` = no-op; isolate Preview Next files |
 | Preview blank but logs show TomorrowOS listening | v0 Next intercepts public port | Add Next reverse proxy → internal TomorrowOS port |
 | Preview works, Publish broken / Next-only | Production still on Next | Switch Production entry to `tsx server.ts` / `export default server` |
 | `ENETUNREACH` / IPv6 / `:5432` | Direct Postgres URL | Use **pooled** URL (Supabase `:6543` or Neon pooler) |
@@ -645,11 +702,12 @@ Tell the user:
 | Blob uploads 401 / missing token | Blob not linked | Vercel Storage → Blob + `BLOB_READ_WRITE_TOKEN` |
 | WebSocket fails on Publish | Fluid off / static-only / Next as Production | Enable Fluid; sole Node `listen()` for Publish |
 | Devices fail only on Preview | Next proxy cannot upgrade `wss` | Expected — pair on Publish URL |
-| Agent mixed Cloudinary key+secret in one prompt | Violated Step B | Re-ask key alone, then secret alone |
+| Agent asked user to fill `TOMORROWOS_STORE` / `DATABASE_SSL` | Off-protocol | Agent must auto-set those after Neon/Supabase choice |
+| Agent asked Cloudinary key/secret in three chat turns | Off-protocol | Use **one Env popup** with all Cloudinary fields |
+| Agent asked for OpenAI / `sk-` key during setup | Hallucinated “AI pairing” requirement | **Refuse.** TomorrowOS does not need LLM keys. Return to Q2 media choices only |
+| Agent built a login page after user pasted a URL | Misread brand reference as product scope | Remove login; keep starter Control Panel; apply URL only to `brand.json` |
 | Secrets in git | Mistake | Rotate keys; move to Vercel Env Vars |
 | Replit files present | Copied wrong protocol | Delete `.replit*`; use this file |
-| Brand colours wrong from URL | SPA / blocked fetch | Manual Option B for colours + logo |
-| Agent built a login page after user pasted a URL | Misread brand reference as product scope | Remove login; keep starter Control Panel; apply URL only to `brand.json` |
 
 ---
 
@@ -658,12 +716,12 @@ Tell the user:
 | Topic | Replit | Vercel |
 |-------|--------|--------|
 | Secrets | Replit Secrets | Vercel Environment Variables |
-| Deploy config | `.replit`, artifact `kind=web` | `vercel.json` + Fluid; **no** `.replit` |
+| Deploy config | `.replit`, artifact `kind=web` | `vercel.json` + Fluid; **Framework = Other**; **no** `.replit` |
 | `hostingTarget` | `"here"` | `"vercel"` |
 | Database | Supabase (primary) | Supabase **or Neon** (pooled); SQLite demo only |
 | Media | Cloudinary or Replit Object Storage | Cloudinary **or Vercel Blob** |
 | Preview | Replit Preview / Autoscale Node | **Next shell + proxy** when v0 hardwires Next |
-| Publish | Long-lived Node | **Node `TomorrowOS.listen` only** (not Next) |
+| Publish | Long-lived Node | **Node `TomorrowOS.listen` only** (not Next); gate on no `404 NOT_FOUND` |
 | Brand from URL | Not in Replit protocol | **Option A** — infer **`brand.json` only**; never invent login |
 
 ---
@@ -673,18 +731,19 @@ Tell the user:
 After setup, report:
 
 1. **Live URL** (Production Publish)
-2. **Preview note:** Next proxy shell used / not needed
-3. **Env Vars set** (names only — never values)
-4. **Store:** Supabase pooler / Neon pooled / SQLite (with warning)
-5. **Media:** Cloudinary, Vercel Blob, or local (with warning)
-6. **Brand:** name + `hostingTarget: vercel` (+ note if derived from website URL)
-7. **Runtime split:** Preview = … ; Publish = Node TomorrowOS (confirm **not** Next)
-8. **Open action:** if Database still ERROR, paste the pooler instruction again
+2. **Publish health:** Framework Preset = Other; Start = Node; `GET /` OK (not 404)
+3. **Preview note:** Next proxy shell used / not needed
+4. **Env Vars set** (names only — never values); note which were auto-set (`TOMORROWOS_STORE`, `DATABASE_SSL`)
+5. **Store:** Supabase pooler / Neon pooled / SQLite (with warning)
+6. **Media:** Cloudinary, Vercel Blob, or local (with warning)
+7. **Brand:** name + `hostingTarget: vercel` (+ note if derived from website URL)
+8. **Runtime split:** Preview = … ; Publish = Node TomorrowOS (confirm **not** Next)
+9. **Open action:** if Database still ERROR, paste the pooler instruction again
 
 Protocol complete when:
 
 - **Preview** shows the Control Panel at `/` (via Next proxy if required), **and**
-- **Publish** is configured for pure Node `TomorrowOS.listen` with Fluid, **and**
+- **Publish** returns Control Panel at `/` from pure Node `TomorrowOS.listen` with Fluid (not `404: NOT_FOUND`), **and**
 - Q1–Q3 configuration is saved
 
 — even if a sandbox DB probe still flakes **after** the pooled URL is correctly set for Production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "description": "TomorrowOS CMS server SDK - WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

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