@tomorrowos/sdk 0.7.8 → 0.7.10

package/REPLIT_SETUP.md

@@ -3,7 +3,7 @@
 > **This file is a contract for Replit Agent / Replit AI.**  
 > Follow it literally. Ask questions in order. Do not invent answers. Do not write or rewrite application logic until the Q&A is complete. Prefer configuring Secrets, `.env`, `brand.json`, and `server.ts` store wiring over inventing a custom CMS.
 >
-> **On Replit, this file is the ONLY questionnaire.** Do **not** use `LLM_PROMPT.md` questions.
+> **On Replit, this file is the ONLY questionnaire.**
 
 ## User trigger (copy-paste)
 
@@ -12,6 +12,7 @@ When a human pastes a prompt like this, **read this file and start Question 1 im
 ```text
 Follow @tomorrowos/sdk REPLIT_SETUP.md and set up my TomorrowOS CMS.
 Ask only the questions listed in REPLIT_SETUP.md, in order. Do not use LLM_PROMPT.md.
+After the four answers, configure and start — minimal verification only (Web app type + Preview at /). No Supabase or WebSocket tests.
 Do not skip steps.
 ```
 
@@ -22,6 +23,8 @@ Alternate triggers that also activate this protocol:
 
 When any of these triggers fire, **ignore `LLM_PROMPT.md` entirely** for the Q&A phase.
 
+**Before Question 1:** ensure the Replit workspace is a **Web app** project (see **Deployability: Web app artifact**). If the project is API-only or not publishable, fix that first — do not continue the questionnaire on a broken project type.
+
 ---
 
 ## Questionnaire scope (STRICT — read before asking anything)
@@ -37,18 +40,6 @@ Replit Agent must ask **only** the questions defined in **this file**, in **this
 
 **That is the complete list.** There are no other setup questions.
 
-### Forbidden questions (never ask on Replit setup)
-
-Do **not** ask questions from `LLM_PROMPT.md` or improvise similar ones, including but not limited to:
-
-- ❌ “Which screen platform will you manage? … Tizen … BrightSign …” as a **standalone first question**
-- ❌ “What's the primary use case?” as a **standalone** question (use case is collected **inside Question 4** only)
-- ❌ “Where will the CMS server run? … here / vercel / railway …” — on Replit, hosting is always **`here`**; set `cms.hostingTarget: "here"` without asking
-- ❌ Separate “brand identity” interview before Question 4 (colours, logo, name belong in **Question 4** only)
-- ❌ “How many screens?” asked **again** after Question 1 (you already have `cms.expectedScreens`)
-- ❌ Any technical implementation question (WebSocket library, pairing format, etc.)
-
-**Target platform (`tizen` / `brightsign`):** collect only as **item 8 inside Question 4**, not as its own step.
 
 If the user volunteers extra info early (e.g. brand name before Q4), **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 (or Q1, Q3, Q4 if ≤5 screens) are complete.
 
@@ -68,10 +59,7 @@ Then ask **Question 1** — do not switch to `LLM_PROMPT.md`.
 4. **Do not use Replit’s reserved `DATABASE_URL` Secret for Supabase.** On Replit, `DATABASE_URL` is often pre-claimed. Always use **`SUPABASE_URL`** for TomorrowOS ↔ Supabase.
 5. **Prefer `npx @tomorrowos/sdk init`** (or the package’s `templates/cms-starter`) as the project seed. Do not rebuild pairing, WebSocket, or playlist APIs from scratch.
 6. **Never commit secrets** into git. Put credentials only in Replit **Secrets** (and optionally mirror non-secret flags in `.env` that reference env vars).
-7. After Q&A, apply configuration, install deps, start the server, and verify:
-   - HTTP Control Panel loads
-   - `GET /brand.json` returns 200
-   - WebSocket upgrade on `wss://<repl-host>/` succeeds (critical for TV pairing)
+7. After Q&A, **configure and start** — do **not** run a long test suite (see **Post-Q&A: minimal verification only**).
 8. **Follow the Runtime & Replit publish rules below exactly.** A project that cannot Deploy / Publish on Replit is incomplete.
 
 **Question order after Q1:**
@@ -83,6 +71,97 @@ Never insert extra questions between these steps.
 
 ---
 
+## Deployability: Web app artifact (mandatory — fixes “api-kind not deployable”)
+
+TomorrowOS CMS is a **user-facing Web app** (Control Panel at `/` + WebSocket for TVs). Replit must treat it as a **Web app** artifact, **not** an API-only / backend-library project.
+
+### Create the project correctly (do this first)
+
+When scaffolding a **new** Repl:
+
+1. On the Replit homepage, open the artifact-type dropdown and choose **Web app** (not API, not “Backend only”, not Agent & Automation-only).
+2. **Do not** create an “API server” artifact as the only publishable output.
+3. Describe the project as: *“TomorrowOS digital signage CMS — web Control Panel at `/` with WebSocket device pairing.”*
+4. Run `npx @tomorrowos/sdk init` at the project root (or merge the cms-starter template).
+
+**Forbidden setups that cause publish failure:**
+
+- ❌ Project / primary artifact classified as **API** (`api-kind` artifact)
+- ❌ Backend-only Express/Fastify service with **no** `staticRoot` / Control Panel at `/`
+- ❌ Splitting CMS into a non-publishable API artifact + separate unpublished frontend
+- ❌ **Static Deployment** as the publish type (TomorrowOS needs a **live Node server** for WebSocket)
+- ❌ `deploymentTarget` or publish mode that only serves static files without `tsx server.ts`
+
+### What “deployable” means for TomorrowOS
+
+Replit Publish must see:
+
+- A **Web app** that serves HTML at `GET /` (`public/index.html`)
+- 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
+
+### `.replit` (create or replace — required for publish)
+
+Use this **minimum** configuration (merge with existing Nix/modules if needed; **do not** remove `[[ports]]` or `deploymentTarget`):
+
+```toml
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
+hidden = [".config", "package-lock.json"]
+run = "npm run start"
+
+[nix]
+channel = "stable-24_11"
+
+[[ports]]
+localPort = 3000
+externalPort = 80
+
+[deployment]
+run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+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).
+- Keep exactly **one** primary `[[ports]]` entry with `externalPort = 80` for the CMS server.
+- If `.replit` contains `[[artifacts]]` with **only** `artifacts/api-server` and Publish fails, **convert to Web app layout** or create a **new Web app** Repl and migrate — do not tell the user publish succeeded.
+
+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`.
+
+### Publishing pane (human + Agent)
+
+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.
+
+After Publish, the public URL is:
+
+`https://YOUR-REPLIT-DOMAIN`
+
+### If Publish says “api-kind artifact … not deployable”
+
+**Do not** keep retrying publish unchanged. Fix in this order:
+
+1. Verify homepage artifact type is **Web app**; if the Repl was created as API-only, **create a new Web app Repl** and re-run this setup (fastest fix).
+2. Replace `.replit` with the template above (`entrypoint`, `modules`, `[[ports]]`, `deploymentTarget = "autoscale"`).
+3. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), host: "0.0.0.0", port: Number(process.env.PORT) || 3000 })`.
+4. Confirm `GET /` returns Control Panel HTML (not JSON-only API root).
+5. In Publishing, switch to **Autoscale** if currently Static.
+6. Restart workspace → `npm run start` → Publish again.
+
+Tell the user plainly if step 1 requires a new Repl — API-only projects cannot publish a browser CMS without reclassification.
+
+---
+
 ## Runtime & Replit publish rules (mandatory)
 
 These rules exist so the CMS can be **Run** and **Published/Deployed** on Replit without custom build steps.
@@ -119,7 +198,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.8",
+    "@tomorrowos/sdk": "^0.7.10",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -150,30 +229,34 @@ npm run start
 
 ### `.replit` (create or edit)
 
+Use the full template in **Deployability: Web app artifact** (not run/deployment lines only). Minimum:
+
 ```toml
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
 run = "npm run start"
 
+[[ports]]
+localPort = 3000
+externalPort = 80
+
 [deployment]
 run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+ignorePorts = false
 ```
 
-If the workspace already has a `.replit`, **merge** these keys — do not wipe unrelated Nix/modules config. Ensure the effective Run and Deployment commands remain `npm run start`.
+If the workspace already has a `.replit`, **merge** these keys — do not wipe unrelated Nix/modules config. Ensure Run, Deployment, **ports**, and **deploymentTarget** are correct.
 
 ### Publish readiness checklist (before telling the user “done”)
 
-1. Replit project type is **Web** (not API)
-2. `package.json` has `scripts.start` = `tsx server.ts`
-3. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
-4. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
-5. `.replit` Run + `[deployment].run` use `npm run start`
-6. Node is **20+**
-7. Preview at `/` shows the TomorrowOS Control Panel (not Canvas, not another app)
-8. Stale processes / port conflicts cleared before publish
-9. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
-10. Browser WebSocket test to `wss://<host>/` succeeds
-11. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
+**Only these three checks matter after setup.** Do not add more unless Publish fails.
 
-If any item fails, fix it before finishing.
+1. **Web app, not API** — project / primary artifact is **Web app** (not `api-kind` / API-only).
+2. **`.replit` is correct** — `entrypoint = "server.ts"`, `modules = ["nodejs-20"]`, `[[ports]]` with `externalPort = 80`, `deploymentTarget = "autoscale"`, Run/Deploy = `npm run start`.
+3. **Preview at `/`** — after `npm run start`, logs show `[TomorrowOS] listening on http://0.0.0.0:...` and Preview shows the Control Panel (HTML), not empty / API JSON.
+
+If all three pass, tell the user setup is complete. **Do not** block on extra tests below.
 
 ### Preview requirements (Replit workspace)
 
@@ -207,11 +290,37 @@ Tell the user their live CMS URLs:
 
 Replace `YOUR-REPLIT-DOMAIN` with the actual published hostname (e.g. `my-cms.replit.app`).
 
-Verify after publish:
+**Do not** run post-publish smoke tests unless the user reports a problem. Telling them the URL is enough.
+
+---
+
+## Post-Q&A: minimal verification only
+
+After Questions 1–4, **configure → `npm install` → `npm run start` → done.**
+
+### Do (maximum)
+
+1. Confirm **Web app** artifact (not API) — **most important**.
+2. Write Secrets / `.env` / `brand.json` / `server.ts` / `.replit` from answers.
+3. `npm install` && `npm run start`.
+4. Glance at logs for `[TomorrowOS] listening on http://0.0.0.0:...`.
+5. Glance at Preview — Control Panel visible at `/`.
+
+### Do NOT run after setup (unless user asks or Publish fails)
+
+- ❌ **Supabase connection test** (no `psql`, no DB ping, no “testing Supabase connection…”)
+- ❌ **Cloudinary upload test**
+- ❌ **`curl` / `fetch` on `/brand.json`** as a formal gate
+- ❌ **Browser WebSocket console snippet** as a formal gate
+- ❌ **Publishing dry-run** unless the user asked to publish now
+- ❌ **Long troubleshooting loops** when Preview already shows the Control Panel
+- ❌ Re-running the full **Publish readiness checklist** item-by-item in chat
+
+If Preview shows the Control Panel and the project is **Web app** type, **stop testing** and give the user their URL and next steps.
 
-1. `https://YOUR-REPLIT-DOMAIN/` shows the Control Panel (not empty, not API docs).
-2. `https://YOUR-REPLIT-DOMAIN/brand.json` returns 200.
-3. WebSocket to `wss://YOUR-REPLIT-DOMAIN/` succeeds.
+### Only if Preview is empty or Publish fails
+
+Then (and only then) check: API vs Web type → `.replit` ports/`deploymentTarget` → stale process / port conflict → see **Failure recovery cheat sheet**.
 
 ---
 
@@ -290,6 +399,7 @@ DATABASE_SSL=true
 ```
 
 5. **Do not** write the real password into committed files.
+6. **Do not** test the Supabase connection after saving the Secret — configuration only.
 
 If the user refuses Supabase but chose > 5 screens, warn them SQLite on Replit is fragile for fleets, then offer SQLite only after they confirm.
 
@@ -352,8 +462,7 @@ Tell the user:
 > 5. **Text colour** (hex, optional — default `#0A0908`)
 > 6. **Secondary / accent colour** (hex, optional)
 > 7. **Logo** — upload an SVG/PNG into the project, or give a URL I can fetch into `./assets/`
-> 8. **Target platforms** — `tizen`, `brightsign`, or both
-> 9. **Use case** — one of: `restaurant`, `retail`, `corporate`, `wayfinding`, `transit`, `other`
+
 
 If the user only gives a name and primary colour, use defaults for the rest and say what you assumed.
 
@@ -393,7 +502,9 @@ Set `cms.expectedScreens` from Question 1 (do not ask screen count again). Alway
 
 Run these steps in order. Tick mentally; do not skip.
 
-### A. Seed the project
+### A. Seed the project (Web app first)
+
+**If creating a new Repl:** choose **Web app** on the Replit homepage before `init`.
 
 ```bash
 npx @tomorrowos/sdk@latest init .
@@ -448,19 +559,10 @@ CLOUDINARY_API_SECRET=...
 
 2. Move / keep `tsx` in **`dependencies`** so Deploy works.
 3. Set `engines.node` to `>=20`.
-4. Create or update `.replit`:
-
-```toml
-run = "npm run start"
-
-[deployment]
-run = ["sh", "-c", "npm run start"]
-```
+4. Create or update `.replit` using the **Deployability** template (`entrypoint`, `modules`, `[[ports]]`, `deploymentTarget = "autoscale"`).
 
 ### E. Install and run
 
-**Before starting:** stop stale processes, clear old background tasks, free the port if needed, restart workspace if stuck.
-
 ```bash
 npm install
 npm run start
@@ -468,30 +570,15 @@ npm run start
 
 (Use `npm run dev` only for local edit/watch. **Publish / Deploy / Replit Run must use `npm run start`.**)
 
-Confirm logs contain something like:
-
-```text
-[TomorrowOS] listening on http://0.0.0.0:<PORT>
-```
-
-Confirm the **Web preview** (not Canvas) shows the Control Panel at `/`.
+**Minimal check:** logs contain `[TomorrowOS] listening on http://0.0.0.0:...` and Preview shows Control Panel at `/`. Then proceed to **G** — no further tests.
 
-### F. Verify before telling the user “done”
+### F. Done — skip extended verification
 
-1. Replit project type is **Web**; preview at `/` shows Control Panel (not empty, not Canvas-only).
-2. Open the Control Panel URL.
-3. `GET /brand.json` → 200 and correct `name` / colours.
-4. In browser console on the Control Panel origin:
-
-```javascript
-const ws = new WebSocket(location.origin.replace(/^http/, "ws") + "/");
-ws.onopen = () => console.log("WS OK");
-ws.onerror = (e) => console.log("WS ERR", e);
-```
+If the **three-item Publish readiness checklist** passes (especially **Web app, not API**), mark setup complete.
 
-5. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
+**Do not** run WebSocket console tests, Supabase connection tests, or `brand.json` curl checks here.
 
-If WebSocket fails, fix Run command / process crash / sleep **before** asking the user to pair a TV.
+Only investigate further if Preview is empty, server crashed, or user reports Publish failure.
 
 ### G. Tell the user next steps (no code)
 
@@ -528,6 +615,9 @@ Do **not**:
 - Leave `tsx` only in `devDependencies` if the Deploy pipeline installs production deps only
 - Use Canvas preview as the primary CMS verification surface
 - Serve a different app or API-only response at `/` instead of the Control Panel
+- Create the Repl as **API-only** or publish with **Static Deployment** only
+- Omit `[[ports]]` / `deploymentTarget` from `.replit` when setting up for Publish
+- Run **Supabase connection tests**, **WebSocket console tests**, or other post-setup smoke tests unless Preview fails or the user asks
 
 ---
 
@@ -553,7 +643,8 @@ TOMORROWOS_STORE=sqlite
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| Preview empty / wrong app at `/` | Project type API, wrong staticRoot, or stale process | Set project to **Web**; confirm `staticRoot: public`; stop old servers; restart workspace |
+| Publish: **api-kind artifact not deployable** | Repl created as API-only, or missing Web app + ports | New **Web app** Repl **or** fix `.replit` (`entrypoint`, `[[ports]]`, `deploymentTarget=autoscale`); serve Control Panel at `/` |
+| 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` |
 | Deploy runs wrong process | `.replit` / Deployment not `npm run start` | Set `run = "npm run start"` and `[deployment] run = ["sh", "-c", "npm run start"]` |
@@ -567,6 +658,6 @@ TOMORROWOS_STORE=sqlite
 
 ## Protocol version
 
-`replit-setup/1.1` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.3` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
 
-**Changelog 1.1:** strict questionnaire scope; Replit must not use `LLM_PROMPT.md` questions (e.g. standalone target-platform prompt).
+**Changelog 1.3:** minimal post-Q&A verification — no Supabase/WS smoke tests; prioritize **Web app vs API** only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "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/.replit

@@ -1,4 +1,17 @@
+entrypoint = "server.ts"
+modules = ["nodejs-20"]
+hidden = [".config", "package-lock.json"]
 run = "npm run start"
 
+[nix]
+channel = "stable-24_11"
+
+# Expose the CMS HTTP + WebSocket server (TomorrowOS Control Panel at /).
+[[ports]]
+localPort = 3000
+externalPort = 80
+
 [deployment]
 run = ["sh", "-c", "npm run start"]
+deploymentTarget = "autoscale"
+ignorePorts = false

package/templates/cms-starter/package.json

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

package/LLM_PROMPT.md

@@ -1,173 +0,0 @@
-# Elicitation Protocol for TomorrowOS CMS Projects
-
-> **This file is the contract between TomorrowOS and any LLM generating code using this package. You must follow it literally. Do not skip questions, do not infer answers, do not start writing code until the protocol is complete.**
-
-> **Replit Agent:** if the user is setting up a CMS on Replit (or pastes a prompt that mentions `REPLIT_SETUP.md`), follow **`REPLIT_SETUP.md` only** — not this file. Do **not** ask `LLM_PROMPT.md` questions (e.g. standalone “Which screen platform will you manage?”). Replit uses four questions: screen count → optional Supabase → media storage → brand (including platform and use case inside Question 4).
-
-You are generating a digital signage CMS using `@tomorrowos/sdk`. The user has asked you to build something like "a CMS for my restaurant" or "a signage dashboard for my retail network". Before you write any code, you must gather five pieces of information from the user.
-
-Ask each question in order. If the user answers multiple at once, record those and skip ahead. If the user hasn't given you an answer to a specific field, do not invent one — ask the question explicitly.
-
----
-
-## Question 1 — Target platform
-
-**Ask exactly:**
-
-> "Which screen platform will you manage? TomorrowOS V1 fully supports Samsung Tizen (commercial signage displays) and BrightSign (media players). Which would you like to target?"
-
-**Valid answers:** `tizen`, `brightsign`, or `both`
-
-**If the user names a platform not in V1** (webOS, Android, ChromeOS, Windows), respond:
-
-> "That platform is planned for a later release. For V1, the supported options are Tizen and BrightSign. Which would you like to use for now?"
-
-**Store answer as:** `targetPlatforms` array in `brand.json`
-
----
-
-## Question 2 — Brand identity
-
-**Ask exactly:**
-
-> "What's the name of the product or company this CMS is for? I'll also need:
->
-> - A logo file (SVG preferred, PNG acceptable — or a URL I can fetch)
-> - A primary brand colour (hex format, e.g. `#FF8A3D`)
-> - Optional: a secondary/accent colour"
-
-**Required fields:**
-
-- `brand.name` — string
-- `brand.primaryColor` — hex string matching `^#[0-9A-Fa-f]{6}$`
-- `brand.logoPath` — relative path to logo file the user will save to the project
-
-**If the user does not provide a logo**, proceed with a placeholder comment in the generated code noting that the logo must be added before production use. Do not fabricate a logo.
-
-**If the user provides a brand name but no colour**, ask:
-
-> "What's the primary colour for your brand? I need it as a hex code like `#FF8A3D`."
-
-Store answers in `brand.json`.
-
----
-
-## Question 3 — Use case
-
-**Ask exactly:**
-
-> "What's the primary use case for this CMS? For example: restaurant menu boards, retail promotions, corporate lobby displays, hospital wayfinding, transit information."
-
-**Use the answer to:**
-
-- Tailor the example content shown in the starter template (e.g. menu items vs retail promo templates)
-- Set the dashboard's default greeting and page titles
-- Suggest sensible default playlist names
-
-**Do NOT use the answer to:**
-
-- Change the SDK method signatures
-- Add or remove required components from `BUILD_GUARDRAILS.md`
-- Skip any mandatory pages
-
-The SDK contract is identical regardless of use case. Use case only affects content and copy.
-
-**Store answer as:** `cms.useCase` in `brand.json` (one of: `restaurant`, `retail`, `corporate`, `wayfinding`, `transit`, `other`)
-
----
-
-## Question 4 — Hosting target
-
-**Ask exactly:**
-
-> "Where will the CMS server run? Options:
->
-> - `here` — you're in Replit, Claude Code, or another hosted AI workspace (I'll configure it automatically)
-> - `vercel` — deploy to Vercel
-> - `railway` — deploy to Railway
-> - `self-hosted` — you'll run it on your own infrastructure"
-
-**If the user says `here`:**
-
-- Use environment variable `process.env.PORT` for the server port
-- Configure the WebSocket handler to bind to `0.0.0.0`
-- Include a comment in `server.ts` noting that Replit/Claude Code handles the hosting and HTTPS termination
-- Do NOT commit any secrets or keys to the generated code
-
-**If the user says `vercel`:**
-
-- Note that Vercel free tier has WebSocket limitations; recommend Railway for production
-- Generate `vercel.json` with appropriate WebSocket routing
-
-**If the user says `railway`:**
-
-- Generate `railway.toml` with port configuration
-- Include Dockerfile if appropriate
-
-**Store answer as:** `cms.hostingTarget` in `brand.json`
-
----
-
-## Question 5 — Expected number of screens
-
-**Ask exactly:**
-
-> "How many screens will you manage initially? (1-10 is fine for testing. For larger deployments I'll add pagination and grouping features.)"
-
-**If answer is 1-10:** generate simple list views without pagination.
-
-**If answer is 11-100:** include pagination on the screens list page (page size 20).
-
-**If answer is 100+:** include pagination, grouping, and tag filtering on the screens list. Note to user that fleet-level features (bulk commands, group broadcast) are recommended.
-
-**Store answer as:** `cms.expectedScreens` in `brand.json`
-
----
-
-## After all five answers collected
-
-Follow this sequence strictly:
-
-1. **Write `brand.json`** at the project root using the answers. Validate against `brand.schema.json`.
-2. **Run `npx tomorrowos init [dir]`** or copy `templates/cms-starter/` from the SDK package into the user's project as the seed.
-3. **Customise the starter:**
-   - Replace placeholder brand name, colour, logo references
-   - Rename example content to match the use case
-   - Remove any platform-specific notes for platforms the user didn't select
-4. **Read `BUILD_GUARDRAILS.md`** and verify every mandatory component is present in the generated code. Do not skip any.
-5. **Run `npm install`** and confirm dependencies resolve.
-6. **Start the dev server** (`npm run dev`) and confirm it runs without errors.
-7. **Show the user `PLAYER_INSTALL.md`** and explain what to do next to get a screen paired and controllable.
-
----
-
-## What not to ask
-
-Do not ask the user:
-
-- How WebSocket connections should be handled (the SDK handles this)
-- How to implement pairing (the SDK handles this)
-- How to format command messages (the SDK handles this)
-- Which WebSocket library to use (the SDK bundles this)
-- What TCP port to use (use `process.env.PORT` or `3000`)
-- Whether to use TypeScript or JavaScript (default to TypeScript; offer JS only if user explicitly asks)
-
-These are implementation details the SDK controls. The user cares about their brand, their platform, their use case. Everything else is the SDK's job.
-
----
-
-## When to re-prompt
-
-If the user's initial prompt already contains answers to some questions (e.g. "build me a CMS for my Acme Burger restaurant menu boards on Samsung Tizen"), record those answers and only ask the remaining questions. Do not re-ask what the user has already told you.
-
-If the user says "just build it, don't ask me questions," respond:
-
-> "I'd love to, but I need five quick answers to make sure the CMS you get actually works with your screens and looks like your brand. It'll take about sixty seconds. Ready?"
-
-Do not proceed without the answers. The SDK will not function without at minimum: `targetPlatforms`, `brand.name`, `brand.primaryColor`, and `cms.hostingTarget`.
-
----
-
-## Protocol version
-
-This elicitation protocol is version `1.0`, aligned with TomorrowOS wire protocol `1.0`. Future SDK versions may add questions; they will not remove existing ones without a major-version bump.