@tomorrowos/sdk 0.9.25 → 0.9.27

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` (Scheme A: root `server.ts`, Next in `preview/`, `GET /status` must be JSON). 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.4` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+> Protocol id: `vercel-setup/1.6` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
 
 ## User trigger (copy-paste)
 
@@ -19,6 +19,7 @@ If any step contradicts Vercel, adapt to settings Vercel can accept (document th
 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, GET /status on the production URL must return JSON (not HTML), and GET / must return the Control Panel (not 404 NOT_FOUND).
 ```
 
 Alternate triggers:
@@ -44,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 |
@@ -52,6 +54,57 @@ 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.
+
+### 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`)
+- `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 Node process** is running `tsx server.ts`, so API routes never hit `TomorrowOS`.
+
+**Fix (Scheme A — see dedicated section below):** force Vercel to run the **root `server.ts` Node entry** with Fluid. `public/` must be served **at runtime** via `staticRoot` in `listen()`, **not** as the build output directory.
+
+**Publish gate (mandatory):** after deploy, `GET /status` must return **JSON** starting with `{`, not HTML starting with `<` or `The page`.
+
+```bash
+curl -s https://YOUR-PROJECT.vercel.app/status | head -c 80
+# Expected: {"status":"success",...}
+# Failure:  The page could not be found  OR  <!DOCTYPE html>
+```
+
+**Setup is NOT complete** while `/status` returns HTML or the panel shows the JSON parse error.
+
 ### 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.
@@ -87,6 +140,7 @@ Ask **only** these questions, in **this exact order**:
 
 - ❌ 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.
@@ -104,9 +158,9 @@ 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. **Never** ask for OpenAI or other LLM API keys.
-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.
+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`** (or `NEON_DATABASE_URL`) when using Neon. `createTomorrowOSStore` accepts `SUPABASE_URL` then `DATABASE_URL`.
+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`).
@@ -118,20 +172,148 @@ Then ask **Question 1**.
 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` **or** `/status` returns HTML (static `public/` trap).
+18. **Scheme A is doc-driven:** achieve Production Node Publish by **project layout + `vercel.json` + dashboard settings** during setup — **no SDK code changes** required (see **Scheme A** section).
 
 **Question order:** Q1 → Q2 → Q3 → execution checklist.
 
 ---
 
+## Scheme A — Standard Node Publish (mandatory for Production)
+
+> **Goal:** Preview may use Next + proxy; **Publish** runs **only** root `server.ts` + `TomorrowOS.listen` on Vercel Fluid.  
+> **Scope:** This section is implemented entirely during setup (move files, write `vercel.json`, patch dashboard). **Do not** change `@tomorrowos/sdk` source.
+
+### Why Scheme A exists
+
+| Layer | Preview (v0) | Publish (Production) |
+|-------|----------------|----------------------|
+| Host | Next.js shell + HTTP proxy | **Node `server.ts`** only |
+| `public/` | Proxied from TomorrowOS | Served by **`staticRoot`** inside `listen()` — **not** as Vercel Output Directory |
+| WebSocket | Optional / may fail in Preview | Required on same origin (`wss://`) |
+| Next files | Allowed under `preview/` | **Must not** live at project root |
+
+### A1 — Project layout (Agent must enforce)
+
+**At project root (Production):**
+
+```
+server.ts          ← REQUIRED name at root (or server.mts)
+vercel.json
+package.json
+brand.json
+public/            ← CMS static UI; NOT the Vercel output directory
+```
+
+**Preview only (when v0 needs Next) — move ALL of these under `preview/`:**
+
+```
+preview/
+  next.config.mjs
+  app/               ← Next proxy routes
+  postcss.config.mjs
+  next-env.d.ts
+  tsconfig.json      ← Next/tsconfig if separate from server
+```
+
+**Remove from project root after move:** `next.config.mjs`, `app/`, root Next `tsconfig` plugin config, `postcss.config.mjs`, `next-env.d.ts`.
+
+**Do NOT:**
+
+- ❌ Leave `next.config.mjs` + `app/` at root while claiming Production is Node-only
+- ❌ Create root `api/index.ts` exporting `http.Server` + `routes` catch-all
+- ❌ Set Output Directory to `public` or `.`
+
+**Update `package.json` scripts when Preview uses `preview/`:**
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "dev:preview": "concurrently -k \"npm:dev:tomorrowos\" \"npm:dev:next\"",
+    "dev:tomorrowos": "cross-env TOMORROWOS_INTERNAL_PORT=3001 tsx watch server.ts",
+    "dev:next": "cd preview && next dev -p 3000",
+    "start": "tsx server.ts",
+    "build": "node -e \"process.exit(0)\""
+  }
+}
+```
+
+### A2 — `server.ts` entry (Vercel zero-config Node detection)
+
+Vercel detects a **root** `server.ts` / `server.mts` and routes traffic to it when:
+
+1. The file lives at **project root** (not only under `api/`)
+2. **`listen()` runs at module load** (top-level, not inside an unexported function)
+3. The file **`export default server`** (the `http.Server` from `tomorrowos.listen`)
+
+Use the pattern in **Runtime & Vercel deploy rules** below. On Publish, **do not** set `TOMORROWOS_INTERNAL_PORT` — let Vercel inject `PORT`.
+
+### A3 — `vercel.json` (Production)
+
+```json
+{
+  "fluid": true,
+  "framework": null,
+  "installCommand": "npm install",
+  "buildCommand": "npm run build",
+  "startCommand": "npm run start",
+  "outputDirectory": null
+}
+```
+
+Use `pnpm` / `yarn` equivalents if the project uses them.
+
+**Critical:**
+
+- `"outputDirectory": null` — **never** `"public"`, `"."`, or `"public if exists"`
+- `"startCommand"` must be explicit when the dashboard keeps defaulting to static
+- `"buildCommand"` must be the no-op `npm run build` — **never** `next build` for Production
+
+### A4 — Vercel Project Settings (dashboard or API — mandatory)
+
+`vercel.json` alone is **not enough** if the dashboard still shows Framework = **Next.js** or Output = `public`.
+
+| 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 / null** — **NOT `public`** |
+| **Start Command** | `npm run start` → `tsx server.ts` |
+| Fluid compute | **On** |
+
+If Framework Preset still shows **Next.js** after `vercel.json`: **patch via Vercel API / CLI / dashboard**, then redeploy.
+
+### A5 — Publish acceptance (all must pass before “setup complete”)
+
+1. Deploy logs show Node starting / `[TomorrowOS] listening on ...` (not only “Uploading static files”)
+2. `curl -s https://PROD/status` → JSON (`{"status":...}`)
+3. `curl -s https://PROD/` → Control Panel HTML
+4. Control Panel **does not** show `Unexpected token 'T'` / CMS unreachable
+5. Framework Preset = Other; Fluid on
+
+If (2) fails but (3) passes → **static `public/` trap**. Re-apply A3 + A4; confirm `startCommand`; redeploy. **Do not** add `api/` catch-all.
+
+### A6 — What Scheme A does **not** require
+
+- ❌ No changes to `@tomorrowos/sdk` package code
+- ❌ No `(req, res)` handler refactor
+- ❌ No `next build` / `next start` on Production
+- ❌ No root `api/` directory for the CMS server
+
+---
+
 ## Runtime & Vercel deploy rules (mandatory)
 
 ### 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
 
@@ -143,7 +325,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)\""
   }
 }
 ```
@@ -151,6 +333,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)
@@ -172,7 +355,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)\""
   }
 }
 ```
@@ -185,6 +369,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";
@@ -230,12 +416,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.
 ```
@@ -250,24 +436,43 @@ 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",
+  "startCommand": "npm run start",
+  "outputDirectory": null
 }
 ```
 
-Also:
+Use `pnpm` / `yarn` variants of install/build/start if that is the project’s package manager.
 
-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.
+**Also force Project Settings (dashboard or Vercel API) — this is mandatory (see Scheme A4):**
+
+| 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 / null** — **NOT `public`** |
+| Start Command | `npm run start` → `tsx server.ts` (or `.mts`) — **explicit in `vercel.json` too** |
+| Fluid compute | **On** |
+
+If `next` / `next.config.*` exist for Preview and the dashboard still auto-selects Next.js:
+
+1. Patch Framework Preset to **Other** via API/CLI/dashboard.
+2. Redeploy.
+3. Hit Production `GET /status` — must be **JSON**, not HTML.
+4. 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.
 
@@ -282,6 +487,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
 
@@ -307,52 +513,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**
 
@@ -362,9 +563,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.
 
@@ -391,46 +592,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.
+### Step B — If **1 / Cloudinary** (same Question 2 — **one Env popup**)
 
-#### B1 — Cloud name (ask alone)
+> **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 **Cloud name** only (`CLOUDINARY_CLOUD_NAME`).  
-> Find it at [cloudinary.com/console](https://cloudinary.com/console) → Dashboard.
-
-Save as Vercel Env Var `CLOUDINARY_CLOUD_NAME`. Do **not** ask for key or secret yet.
-
-#### B2 — API key (ask alone — after B1 is saved)
-
-**Ask exactly:**
+**Preferred:** Vercel Env Vars UI (or Agent secrets form) with these fields together:
 
-> Paste your Cloudinary **API Key** only (`CLOUDINARY_API_KEY`).  
-> Do not paste the API Secret in this step.
+| 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_KEY`. Do **not** ask for the secret in this message.
+**If a multi-field popup is unavailable, ask once in a single message** (still not three turns):
 
-#### B3 — API secret (ask alone — after B2 is saved)
-
-**Ask exactly:**
-
-> Paste your Cloudinary **API Secret** only (`CLOUDINARY_API_SECRET`).  
-> This is the last Cloudinary credential.
-
-Save as Vercel Env Var `CLOUDINARY_API_SECRET`.
-
-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.
@@ -448,7 +636,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).
@@ -574,28 +762,27 @@ npx @tomorrowos/sdk@latest init .
 # npx @tomorrowos/sdk@latest init . --force
 ```
 
-Then:
+Then (**Scheme A — mandatory for Publish**):
 
-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 **`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`, `startCommand`, `outputDirectory: null`).
+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.
+5. Do **not** add root `api/` catch-all for raw `http.Server`.
+6. Do **not** add `.replit*`.
+7. 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.
@@ -621,12 +808,17 @@ vercel --prod
 # or git push → Vercel Git integration
 ```
 
-Before finishing, verify Production settings:
+**Publish acceptance checklist (all must pass — Scheme A5):**
+
+1. Framework Preset = **Other** / null (dashboard confirms — not Next.js)
+2. Output Directory = **empty** (not `public`)
+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`
 
-1. Start / entry = **Node `TomorrowOS.listen`** (`npm run start` / exported `server`)
-2. **Not** `next start` as Production
-3. Fluid compute on
-4. Env Vars present for Production environment
+If step 6 fails but step 7 passes: **static `public/` trap** — Vercel is not running Node. Re-apply Scheme A3–A4; do **not** invent `api/` + `routes`.
 
 Tell the user:
 
@@ -638,11 +830,12 @@ Tell the user:
 
 **Do:**
 
-1. Preview: Control Panel HTML at `/` (via Next proxy if applicable)
-2. Publish: Control Panel HTML at `/` from **Node** TomorrowOS
-3. Server status: Media OK when Cloudinary or Blob configured
-4. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch to **pooled** URL (Supabase `:6543` or Neon pooler) and redeploy — call this out explicitly to the user
-5. Fluid compute on for Production
+1. Preview: Control Panel HTML at `/` (via Next proxy in `preview/` if applicable)
+2. Publish: `GET /status` → JSON; `GET /` → Control Panel from **Node** TomorrowOS
+3. Publish: panel does **not** show `Unexpected token 'T'` / CMS unreachable
+4. Server status: Media OK when Cloudinary or Blob configured
+5. 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
+6. Fluid compute on for Production
 
 **Do not block** on long WebSocket/device pairing tests unless the user asks. Prefer pairing against **Publish**, not Preview.
 
@@ -652,6 +845,10 @@ Tell the user:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| Publish `404: NOT_FOUND` | Framework Preset still **Next.js** / no Node start | Scheme A: Framework = **Other**, Start = `npm run start`, Output empty, Fluid on; redeploy |
+| Panel loads but **CMS unreachable** / `Unexpected token 'T', "The page c"...` | **`public/` deployed as static site** — no Node running | Scheme A: `outputDirectory: null`, explicit `startCommand`, move Next to `preview/`; verify `GET /status` returns JSON |
+| `vercel inspect` shows Output = `public if it exists` | Framework=Other static default | Force Output Directory **empty** in dashboard + `outputDirectory: null`; ensure root `server.ts` + `startCommand` |
+| 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 |
 | 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) |
@@ -660,12 +857,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 |
-| 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 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 |
 
 ---
 
@@ -674,12 +871,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 |
 
 ---
@@ -689,18 +886,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 = Other; Output ≠ `public`; `GET /status` → JSON; `GET /` OK
+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 `/` **and** `/status` JSON from pure Node `TomorrowOS.listen` with Fluid (not static `public/`, not `404: NOT_FOUND`, not `Unexpected token 'T'`), **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.25",
+  "version": "0.9.27",
   "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.25",
+  "version": "0.9.27",
   "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.25",
+    "@tomorrowos/sdk": "^0.9.27",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },