@tomorrowos/sdk 1.1.0 → 1.1.2

package/REPLIT_SETUP.md

@@ -78,7 +78,7 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 | Q1 + Supabase | Database choice ?**immediately** one Secrets input for `SUPABASE_URL` (still Question 1) |
 | Q2 + Cloudinary | Media choice ?**immediately** one multi-field Secrets dialog for all `CLOUDINARY_*` keys (still Question 2) |
 | Q3 branding | **One** multi-field dialog with **all seven** branding inputs stacked (name, tagline, primary, background, text, secondary, logo) |
-| Q4 CMS password | Optional single Secrets input for `CMS_PASSWORD` (blank/skip allowed; can set later) |
+| Q4 CMS password | **Immediately after Q3** ? one Secrets input for `CMS_PASSWORD` (blank/skip allowed). **Never** ask a yes/no "do you want a password?" first. |
 
 **Critical ?Question 1 option order (exact):** Present database choices in **this order only**:
 1. **Supabase Postgres (Recommended)**
@@ -88,13 +88,15 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 
 **Critical:** Question 2 is **not complete** when the user says Cloudinary?or **1**. You **must immediately** open the **multi-field** Cloudinary Secrets dialog (same Question 2 ?**not** ?b? **not** one key per message) and collect `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, and `CLOUDINARY_API_SECRET` **before** Question 3.
 
-**Critical ?Question 3:** All seven branding fields are **optional** and must appear in **one stacked multi-input dialog**. Empty / skip / use defaults??keep starter **`brand.json`**. **Never** ask name, then colours, then logo across separate turns.
+**Critical ? Question 3:** All seven branding fields are **optional** and must appear in **one stacked multi-input dialog**. Empty / skip / use defaults ? keep starter **`brand.json`**. **Never** ask name, then colours, then logo across separate turns.
+
+**Critical ? Question 4 (right after Q3, no warm-up):** As soon as Q3 is submitted/skipped, open the **CMS password** Secrets input (or one chat prompt). **Forbidden before Q4:** "Do you want to protect the CMS?", "Add a password?", "Enable auth?", Option A/B for password yes/no. The password field itself is optional ? blank/skip is a complete Q4 answer.
 
 If the user volunteers extra info early (e.g. brand name before Q3), **record it** and still ask the current question's required fields you do not yet have. Do not skip ahead to execution until Q1?Q4 are complete (Question 2 includes Cloudinary Secrets when applicable; Q4 may be blank/skip). For Q3, "complete" includes the user skipping or leaving fields blank.
 
 If the user says just set it up, dont ask questions,?respond:
 
-> I need a few quick answers from REPLIT_SETUP.md (database choice ? Supabase recommended, then Replit Postgres ? media storage ? plus Cloudinary credentials if you choose Cloudinary ? optional branding ? and optional Control Panel password). It takes about a minute and ensures the CMS deploys correctly on Replit.
+> I need a few quick answers from REPLIT_SETUP.md (database choice ? Supabase recommended, then Replit Postgres ? media storage ? plus Cloudinary credentials if you choose Cloudinary ? optional branding ? and optional CMS password). It takes about a minute and ensures the CMS deploys correctly on Replit.
 
 Then ask **Question 1** ?stay on this file.
 
@@ -107,7 +109,7 @@ Then ask **Question 1** ?stay on this file.
 2a. **Q1 Supabase:** choice ?**immediately** `SUPABASE_URL` input (same Question 1).
 2b. **Q2 Cloudinary:** choice ?**immediately** multi-field `CLOUDINARY_*` Secrets dialog (same Question 2).
 2c. **Q3:** one dialog, **seven inputs stacked** (all optional).
-2d. **Q4:** Optional CMS password. If blank/skip ? omit `CMS_PASSWORD`. If set ? store as Secret `CMS_PASSWORD` (Control Panel only; never enable Replit whole-site password).
+2d. **Q4:** Right after Q3 ? open the CMS password input immediately. **No** yes/no prelude. Blank/skip ? omit `CMS_PASSWORD`. If set ? Secret `CMS_PASSWORD` (app login only; never Replit whole-site password). Ensure Publish readiness uses **`GET /status`** (see **Publish health check**).
 3. **Do not invent** Cloudinary credentials, Supabase URLs, or brand colours. **Do not ask** screen / device count.
 4. **Do not use Replits reserved `DATABASE_URL` Secret for Supabase.** On Replit, `DATABASE_URL` is often the **built-in Replit PostgreSQL** URL. For Supabase always use **`SUPABASE_URL`**. For built-in Replit Postgres, use **`DATABASE_URL`** with `TOMORROWOS_STORE=postgres`.
 4a. **If Supabase is chosen: never collect `SUPABASE_URL` twice.** One capture right after the choice is enough.
@@ -161,7 +163,24 @@ Replit Publish must see:
 - A Node process started by `npm run start` ?`tsx server.ts`
 - `host: "0.0.0.0"` and `port: Number(process.env.PORT) || 3000`
 - An exposed port with `externalPort = 80` in `.replit` (see template below)
-- **Autoscale** (or Reserved VM) deployment ?**not** Static-only
+- **Reserved VM** deployment preferred for TomorrowOS (persistent WebSockets) ? Autoscale is a fallback; **not** Static-only
+
+### Publish health check / readiness probe (IRON RULE)
+
+Replit Publish readiness must **not** treat a password-gated Control Panel redirect as healthy.
+
+**Cause of a common Publish failure:** build OK, then readiness hits `GET /`. With `CMS_PASSWORD` set, older auth wrappers **303 ? `/login`**, and the checker follows redirects until it fails.
+
+**Required agent behavior before / during Publish:**
+
+1. Prefer the public JSON endpoint: configure the production **startup / health / readiness probe** to **`GET /status`** (returns HTTP 200, no auth, no redirect).
+2. Confirm starter `cms-auth` serves unauthenticated panel HTML at `/` with **HTTP 200** (login page ? **no 303 redirect loop**). Do **not** revert to redirecting `/` ? `/login`.
+3. Verify before telling the user Publish is ready:
+   - `GET /status` ? **200** JSON, **no** `Location` redirect
+   - `GET /` with `CMS_PASSWORD` set ? **200** (login HTML) or authenticated panel ? **not** a redirect chain
+4. In Publishing, choose **Reserved VM** (preferred for WebSocket pairing). Autoscale may drop long-lived sockets; Static is forbidden.
+
+If Publish fails with redirect / readiness errors after setting `CMS_PASSWORD`: switch the probe to **`/status`**, confirm `cms-auth` uses 200-at-`/` (not 303), then republish.
 
 ### `.replit` (create or replace ?required for publish)
 
@@ -189,10 +208,11 @@ ignorePorts = false
 **Agent rules for `.replit`:**
 
 - Set `entrypoint = "server.ts"` (not `index.js` unless that file exists and starts TomorrowOS).
-- Set `deploymentTarget = "autoscale"` (WebSocket + long-lived connections; Static Deploy is wrong).
+- Prefer **Reserved VM** in the Publishing UI for TomorrowOS WebSockets. Keep `deploymentTarget = "autoscale"` in `.replit` only if that is what the workspace template requires ? still choose **Reserved VM** when the Publish dialog offers it (see Replit Publishing pane).
 - Keep exactly **one** primary `[[ports]]` entry with `externalPort = 80` for the CMS server.
 - Ensure `.replit-artifact/artifact.toml` has **`kind = "web"`** (shipped in cms-starter). If `kind = "api"`, change to **`web`** before Publish.
-- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, set artifact **`kind = "web"`** or create a **new Web app** Repl and migrate ?do not tell the user publish succeeded.
+- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, set artifact **`kind = "web"`** or create a **new Web app** Repl and migrate ? do not tell the user publish succeeded.
+- **Always** set Publish readiness / health probe to **`/status`** when the UI allows (see **Publish health check**). Never leave the probe on `/` if it follows auth redirects.
 
 If Replit assigns a different `localPort` via `PORT`, update `localPort` to match the port in `[TomorrowOS] listening on http://0.0.0.0:<PORT>` logs, but keep `externalPort = 80`.
 
@@ -201,9 +221,10 @@ If Replit assigns a different `localPort` via `PORT`, update `localPort` to matc
 Before Publish:
 
 1. Confirm project filter / type shows **Web** (not API-only).
-2. In Publishing, choose **Autoscale** (recommended) or **Reserved VM** ?**not Static**.
-3. Stop stale processes; clear port conflicts; restart workspace if needed.
-4. `npm run start` ?Preview at `/` shows Control Panel.
+2. In Publishing, choose **Reserved VM** (preferred for WebSockets) or Autoscale ? **not Static**.
+3. Set readiness / health check path to **`/status`** when the UI exposes it (mandatory if `CMS_PASSWORD` is set).
+4. Stop stale processes; clear port conflicts; restart workspace if needed.
+5. `npm run start` ? Preview at `/` shows Control Panel (or CMS login HTML with HTTP 200 if password set).
 
 After Publish, the public URL is:
 
@@ -706,14 +727,16 @@ Do **not** ask for screen count. Keep a default `cms.expectedScreens` (e.g. `5`)
 
 ## Question 4 ? Optional CMS password (`CMS_PASSWORD`)
 
-> **Optional.** Protect the Control Panel with app-level auth. You may **skip** and set Secret `CMS_PASSWORD` later (then Redeploy / restart).
+> **Optional.** Protect the CMS with app-level auth. You may **skip** and set Secret `CMS_PASSWORD` later (then Redeploy / restart).
+>
+> **IRON RULE ? no prelude:** After Q3 finishes, ask **this** question next. Do **not** first ask whether they want a password / auth / lock. Open the password field (or one chat prompt) immediately; blank/skip is valid.
 
-**Ask (Secrets input or one chat reply):**
+**Ask (Secrets input or one chat reply) ? copy this intent:**
 
-> Optional: set a Control Panel password now? If yes, enter the password to store as Secret **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now ? you can add this Secret later and redeploy.
+> Optional: set a CMS password now? If yes, enter the password to store as Secret **`CMS_PASSWORD`**. Leave blank / skip to keep the CMS open for now ? you can add this Secret later and redeploy.
 
 **Why:**
-- Locks the **CMS Control Panel only** (not the whole Repl).
+- Locks the **CMS Control Panel** only (not the whole Repl).
 - Devices still reach WebSocket / brand / uploads without that password.
 - Safer than Replit **whole-site** password protection (that breaks Tizen/BrightSign).
 - Leaving it blank is fine; add `CMS_PASSWORD` later when you want the login page.
@@ -725,6 +748,9 @@ Do **not** ask for screen count. Keep a default `cms.expectedScreens` (e.g. `5`)
 **Reject / clarify:**
 - Do **not** enable Replit **site-wide** password / auth gate for this project.
 - Do **not** put the password in committed source (git, README, pasted into files).
+- Do **not** ask a separate "enable password protection?" question before this step.
+
+**Publish note (mandatory when `CMS_PASSWORD` is set or may be set):** See **Publish health check / readiness probe** ? probe **`/status`**, never rely on `/` redirecting. Starter `cms-auth` serves login at `/` with **HTTP 200** (no redirect loop); still configure the probe to `/status`.
 
 ---
 
@@ -807,6 +833,8 @@ Link an App Storage bucket in the Replit UI. Do **not** set Cloudinary Secrets f
 - If Q4 set a password: create Replit Secret `CMS_PASSWORD` (never commit it).
 - If Q4 blank/skipped: omit it ? panel stays open until they add the Secret later and Redeploy / restart.
 - Do **not** enable Replit whole-site password protection.
+- **Before Publish:** set readiness probe to **`/status`**. Confirm `GET /status` is 200 with no redirects. Do **not** leave Publish probing `/` if auth redirects would break readiness (starter serves login at `/` with 200; still prefer `/status`).
+- Prefer **Reserved VM** for published WebSocket pairing.
 
 ### C. Wire `server.ts`
 
@@ -921,7 +949,9 @@ Do **not**:
 - Omit `[[ports]]` / `deploymentTarget` from `.replit` when setting up for Publish
 - Run **database connection tests**, **WebSocket console tests**, or other post-setup smoke tests unless Preview fails or the user asks
 - **Debug or fix?Supabase** because dev logs show `getaddrinfo ENOTFOUND` or `database connection failure` ?save config and finish setup instead
-- Ask how many screens / devices (? vs >5)
+- Ask a yes/no "do you want a CMS password / enable auth?" **before** Q4 ? after Q3 go **straight** to the CMS password field (blank/skip allowed)
+- Leave Publish readiness probing `/` when `CMS_PASSWORD` is set if that path 303-redirects (use **`/status`**; serve login at `/` with **200**)
+- Enable Replit **whole-site** password instead of `CMS_PASSWORD`
 
 ---
 
@@ -930,7 +960,8 @@ Do **not**:
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
 | Agent installs older SDK for supply-chain safety window?| Agent age-gated `@latest` | **Override:** `npm install @tomorrowos/sdk@latest` in Shell until local version = `npm view @tomorrowos/sdk version` |
-| Publish: **api-kind artifact not deployable** | CMS artifact `kind = "api"` or API-only Repl | Set **`kind = "web"`** in `.replit-artifact/artifact.toml`; new **Web app** Repl if needed; `.replit` ports + `deploymentTarget=autoscale` |
+| Publish fails after build: too many redirects / readiness on `/` | Health probe hit password-gated `/` (303 ? `/login` loop) | Set probe to **`GET /status`**; ensure `cms-auth` returns **200** login HTML at `/` (no 303); prefer **Reserved VM**; republish |
+| Publish: **api-kind artifact not deployable** | CMS artifact `kind = "api"` or API-only Repl | Set **`kind = "web"`** in `.replit-artifact/artifact.toml`; new **Web app** Repl if needed; `.replit` ports + Reserved VM / autoscale |
 | Preview empty / wrong app at `/` | Project type API, wrong staticRoot, or stale process | Set project to **Web app**; confirm `staticRoot: public`; stop old servers; restart workspace |
 | TV / browser: WebSocket handshake timeout | Node CMS not running or crash-loop | Fix Run ?`npm run start`; check logs for `listening` |
 | Deploy/Publish fails / `tsx: not found` | `tsx` only in devDependencies | Move `tsx` to `dependencies`, reinstall, keep `start`: `tsx server.ts` |
@@ -946,7 +977,9 @@ Do **not**:
 
 ## Protocol version
 
-`replit-setup/1.17` - aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.18` - aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+
+**Changelog 1.18:** Q4 is asked **immediately after Q3** with no yes/no password prelude. Publish readiness must use **`GET /status`** (and `cms-auth` serves login at `/` with HTTP 200 ? no redirect loop). Prefer **Reserved VM** for WebSockets.
 
 **Changelog 1.17:** Question 4 is optional Control Panel Secret `CMS_PASSWORD` (blank/skip allowed; can set later). Do not use Replit whole-site password. Devices stay reachable without it.
 

package/VERCEL_QUESTIONS.md

@@ -1,12 +1,13 @@
 # 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.6` (pairs with `VERCEL_SETUP.md` 1.17+ / `@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`).**  
 > **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.
 
 ---
 
@@ -94,7 +95,7 @@ Blank fields -> keep existing `brand.json`. Logo blank -> `./assets/logo.svg`.
 
 ## Q4 - Optional CMS password (paste this entire block)
 
-Optional: set a Control Panel password now?
+Optional: set a CMS password now?
 
 If yes, reply with the password to store as Environment Variable **`CMS_PASSWORD`**.
 

package/VERCEL_SETUP.md

@@ -5,11 +5,12 @@
 >
 > **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.17` - pairs with `@tomorrowos/sdk` **0.9.70+** (`templates/cms-starter-v0`, Fluid Functions WebSockets).
 >
 > **Questions source of truth:** `VERCEL_QUESTIONS.md` - Agents must **open that file and paste each Q block verbatim**. Do not paraphrase.  
 > **Q1/Q2 = choice questions. Q3 = form only:** open **all seven optional inputs at once**, then **HARD STOP and WAIT** for submit or "skip". Never auto-skip because fields are optional. Never ask a branding choice first. Never show only Name + Primary colour. Logo = **Upload** above **Logo URL**.  
 > **Q4 = optional `CMS_PASSWORD`:** blank/skip is valid; can set later. Control Panel auth only — never Vercel Deployment Protection / whole-site password.  
+> **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.  
 > **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.
 
@@ -40,8 +41,10 @@ Follow @tomorrowos/sdk (an NPM package) VERCEL_SETUP.md and set up my TomorrowOS
 Open VERCEL_QUESTIONS.md first.
 For Q1, Q2, Q3: paste each question block VERBATIM. 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.
 Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
 Keep cms-starter-v0 layout.
 Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
@@ -195,7 +198,7 @@ If the user **skips** a Question 2 option, do **not** invent a substitute questi
 
 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 with Cloudinary recommended, branding, and optional Control Panel password). It takes about a minute and ensures the CMS works on Vercel.
+> I need a few quick answers from VERCEL_SETUP.md (database — Supabase or Neon preferred — media storage with Cloudinary recommended, branding, and optional CMS password). It takes about a minute and ensures the CMS works on Vercel.
 
 Then ask **Question 1**.
 
@@ -221,13 +224,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` -> execution checklist.
+**Question order:** Q1 -> (auto-set store env) -> Q2 -> Q3 form (**wait for user**) -> Q4 optional `CMS_PASSWORD` -> **IRON GATE** -> execution checklist.
 
 ---
 
-## Scheme A ??Vercel Functions + WebSockets (mandatory for Production)
+## 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.
+
+### 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)
 
 > **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`).  
@@ -511,12 +577,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.
 
-### Preview adapter (v0 / Next reverse proxy) ??required when Preview is Next-hardwired
+**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
 
 Detect Preview / v0 (Next already present, or Preview blank while TomorrowOS logs ?listening??. Then:
 
@@ -856,7 +924,7 @@ Set `cmsEndpoint` only if they already know the public `https://?vercel.app` URL
 
 **Ask (Env input or one chat reply):**
 
-> Optional: set a Control Panel password now? If yes, enter the password to store as Environment Variable **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now — you can add this later in Vercel → Settings → Environment Variables and redeploy.
+> Optional: set a CMS password now? If yes, enter the password to store as Environment Variable **`CMS_PASSWORD`**. Leave blank / skip to keep the panel open for now — you can add this later in Vercel → Settings → Environment Variables and redeploy.
 
 **Why:**
 - Locks the **CMS Control Panel only** (not the whole deployment).
@@ -874,26 +942,35 @@ 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`).
+2. **Immediately** move leftover v0 Next from root into **`preview/`** or delete root Next files (`next.config.*`, `app/`, Next `tsconfig` / `postcss` / `next-env.d.ts`, starter `components/`). Production must not see root Next.
+3. Write `vercel.json` per **Scheme A3** (`fluid`, `framework: null`, no-op `buildCommand` — **no** `startCommand`).
 4. **Force Project Settings** per **Scheme A4** (Framework = Other, Output Directory empty, Start = `npm run start`, Fluid on). Patch dashboard via API if it still says Next.js.
 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 +986,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 +1073,12 @@ More detail: https://docs.tomorrowos.org/docs/os/tizen and https://docs.tomorrow
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
+| 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 +1154,9 @@ 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.17` - pairs with `@tomorrowos/sdk` 0.9.70+ and `VERCEL_QUESTIONS.md` 1.6.
+
+**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.0",
+  "version": "1.1.2",
   "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/.replit

@@ -7,6 +7,7 @@ run = "npm run start"
 channel = "stable-24_11"
 
 # Expose the CMS HTTP + WebSocket server (TomorrowOS Control Panel at /).
+# Publish readiness: probe GET /status (public). Do not rely on auth redirects from /.
 [[ports]]
 localPort = 3000
 externalPort = 80
@@ -15,3 +16,5 @@ externalPort = 80
 run = ["sh", "-c", "npm run start"]
 deploymentTarget = "autoscale"
 ignorePorts = false
+# Prefer Reserved VM in the Publishing UI for persistent WebSockets.
+# If the UI allows a health/readiness path, set it to /status.

package/templates/cms-starter/cms-auth.ts

@@ -200,12 +200,16 @@ export async function handleCmsAuth(
 
   if (isDevicePublicPath(method, pathname)) return false;
 
-  if (method === "GET" && pathname === "/login") {
+  if ((method === "GET" || method === "HEAD") && pathname === "/login") {
     res.writeHead(200, {
       "Content-Type": "text/html; charset=utf-8",
       "Cache-Control": "no-store"
     });
-    res.end(loginPageHtml());
+    if (method === "HEAD") {
+      res.end();
+    } else {
+      res.end(loginPageHtml());
+    }
     return true;
   }
 
@@ -244,16 +248,25 @@ export async function handleCmsAuth(
   const cookies = parseCookies(req);
   if (verifySession(password, cookies[COOKIE_NAME])) return false;
 
-  if (wantsHtml(req) && method === "GET") {
-    res.writeHead(303, { Location: "/login" });
-    res.end();
+  // Serve login with HTTP 200 (no 303). Replit Publish readiness probes `/` and
+  // fails if it follows a redirect chain to /login.
+  if (wantsHtml(req) && (method === "GET" || method === "HEAD")) {
+    res.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store"
+    });
+    if (method === "HEAD") {
+      res.end();
+    } else {
+      res.end(loginPageHtml());
+    }
     return true;
   }
 
   sendJson(res, 401, {
     status: "failed",
     error:
-      "Control Panel authentication required. Sign in at /login or set cookie after POST /login."
+      "CMS authentication required. Sign in at /login or set cookie after POST /login."
   });
   return true;
 }