@tomorrowos/sdk 0.7.6 → 0.7.8

package/LLM_PROMPT.md

@@ -2,7 +2,7 @@
 
 > **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`** instead of this file. That protocol covers SQLite vs Supabase by screen count, `SUPABASE_URL`, Cloudinary vs Object Storage, and `brand.json`.
+> **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.
 

package/REPLIT_SETUP.md

@@ -2,6 +2,8 @@
 
 > **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.
 
 ## User trigger (copy-paste)
 
@@ -9,7 +11,8 @@ 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 me the questions in order. Do not skip steps.
+Ask only the questions listed in REPLIT_SETUP.md, in order. Do not use LLM_PROMPT.md.
+Do not skip steps.
 ```
 
 Alternate triggers that also activate this protocol:
@@ -17,20 +20,66 @@ Alternate triggers that also activate this protocol:
 - “Set up TomorrowOS on Replit using REPLIT_SETUP.md”
 - “Configure my TomorrowOS CMS (Replit wizard)”
 
+When any of these triggers fire, **ignore `LLM_PROMPT.md` entirely** for the Q&A phase.
+
+---
+
+## Questionnaire scope (STRICT — read before asking anything)
+
+Replit Agent must ask **only** the questions defined in **this file**, in **this exact order**:
+
+| Step | Section | When |
+|------|---------|------|
+| 1 | **Question 1** — How many screens / devices? | Always |
+| 2 | **Question 2** — Supabase connection | Only if answer to Q1 is **> 5** |
+| 3 | **Question 3** — Media storage (Cloudinary vs Object Storage) | Always (after Q1 or Q2) |
+| 4 | **Question 4** — Brand / TomorrowOS app look | Always last, before execution |
+
+**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.
+
+If the user says “just set it up, don’t ask questions,” respond:
+
+> I need four quick answers from REPLIT_SETUP.md (screen count, media storage, and branding). It takes about a minute and ensures the CMS deploys correctly on Replit.
+
+Then ask **Question 1** — do not switch to `LLM_PROMPT.md`.
+
 ---
 
 ## Hard rules
 
-1. **One question at a time.** Wait for the user’s answer before asking the next question (unless they already answered several in one message).
-2. **Do not invent** screen counts, Cloudinary credentials, Supabase URLs, or brand colours.
-3. **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.
-4. **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.
-5. **Never commit secrets** into git. Put credentials only in Replit **Secrets** (and optionally mirror non-secret flags in `.env` that reference env vars).
-6. After Q&A, apply configuration, install deps, start the server, and verify:
+1. **Ask only REPLIT_SETUP.md questions 1–4** (see **Questionnaire scope**). Never use `LLM_PROMPT.md` on Replit.
+2. **One question at a time.** Wait for the user’s answer before asking the next question (unless they already answered several in one message).
+3. **Do not invent** screen counts, Cloudinary credentials, Supabase URLs, or brand colours.
+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. **Follow the Runtime & Replit publish rules below exactly.** A project that cannot Deploy / Publish on Replit is incomplete.
+8. **Follow the Runtime & Replit publish rules below exactly.** A project that cannot Deploy / Publish on Replit is incomplete.
+
+**Question order after Q1:**
+
+- If **≤ 5 screens:** Q1 → Q3 → Q4 → execution checklist
+- If **> 5 screens:** Q1 → Q2 → Q3 → Q4 → execution checklist
+
+Never insert extra questions between these steps.
 
 ---
 
@@ -70,7 +119,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.7.6",
+    "@tomorrowos/sdk": "^0.7.8",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -112,22 +161,65 @@ If the workspace already has a `.replit`, **merge** these keys — do not wipe u
 
 ### Publish readiness checklist (before telling the user “done”)
 
-1. `package.json` has `scripts.start` = `tsx server.ts`
-2. `tsx` is listed under `dependencies` (runtime-safe for Deploy)
-3. Dependency is `@tomorrowos/sdk` (not a fork or vendored rewrite)
-4. `.replit` Run + `[deployment].run` use `npm run start`
-5. Node is **20+**
-6. `npm run start` prints `[TomorrowOS] listening on http://0.0.0.0:...`
-7. Browser WebSocket test to `wss://<host>/` succeeds
-8. Secrets required by the Q&A answers are set (`SUPABASE_URL`, Cloudinary, etc.)
+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.)
 
 If any item fails, fix it before finishing.
 
+### Preview requirements (Replit workspace)
+
+The Replit **Preview** must show the **TomorrowOS Control Panel** at `/` (root URL).
+
+- `GET /` must serve the CMS Control Panel (`public/index.html` via `staticRoot: public`).
+- **Do not** serve another app, API-only landing page, or placeholder at `/`.
+- **Do not** use or rely on the **Canvas** preview for this CMS — use the normal **Web** preview in the browser.
+- If the preview is **empty** or shows the wrong thing:
+  1. Confirm the Replit project type is **Web**, not **API**.
+  2. Confirm `npm run start` is running and logs show `[TomorrowOS] listening on http://0.0.0.0:...`
+  3. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), ... })`
+  4. Open the preview URL directly (not Canvas) and hard-refresh.
+
+### Before publishing / deploying
+
+Do this **before** clicking Publish / Deploy:
+
+1. **Stop** stale running processes (old `tsx` / `node` servers from prior attempts).
+2. **Clear** old background tasks from previous failed projects (Replit Shell / Processes panel).
+3. **Ensure no old process is holding the port** (`EADDRINUSE` in logs = something still bound to `PORT`).
+4. **Restart the Replit workspace** if the port is stuck or preview still shows a ghost app.
+5. Run `npm run start` once cleanly and confirm Control Panel loads at `/` in preview.
+
+### After publishing / deploying
+
+Tell the user their live CMS URLs:
+
+- **Control Panel (browser):** `https://YOUR-REPLIT-DOMAIN`
+- **TV / player CMS endpoint:** same HTTPS origin, e.g. `https://YOUR-REPLIT-DOMAIN/` (player converts `https://` → `wss://` for WebSocket)
+
+Replace `YOUR-REPLIT-DOMAIN` with the actual published hostname (e.g. `my-cms.replit.app`).
+
+Verify after publish:
+
+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.
+
 ---
 
 ## Question 1 — How many screens / devices?
 
-**Ask exactly:**
+> **This is the first and only “screen count” question.** Do not re-ask later.
+
+**Ask exactly (copy wording; do not substitute LLM_PROMPT questions):**
 
 > How many TomorrowOS screens (devices) do you expect to manage with this CMS?
 >
@@ -247,7 +339,9 @@ Tell the user:
 
 ## Question 4 — Brand / TomorrowOS app look
 
-**Ask exactly:**
+> **This is the only branding / platform / use-case question block.** Do not ask separate LLM_PROMPT “target platform”, “use case”, or “hosting” questions before this.
+
+**Ask exactly (one message; user may answer in one reply):**
 
 > Let’s brand your TomorrowOS experience. Please provide:
 >
@@ -291,7 +385,7 @@ If the user only gives a name and primary colour, use defaults for the rest and
 }
 ```
 
-Set `cms.expectedScreens` from Question 1. Set `cmsEndpoint` only if the user already knows their public `wss://…replit.app` URL; otherwise leave it out and tell them to pair TVs using the published HTTPS URL (player converts `https://` → `wss://`).
+Set `cms.expectedScreens` from Question 1 (do not ask screen count again). Always set `cms.hostingTarget` to `"here"` on Replit without asking. Set `cmsEndpoint` only if the user already knows their public `wss://…replit.app` URL; otherwise leave it out and tell them to pair TVs using the published HTTPS URL (player converts `https://` → `wss://`).
 
 ---
 
@@ -365,6 +459,8 @@ run = ["sh", "-c", "npm run start"]
 
 ### 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
@@ -378,11 +474,14 @@ Confirm logs contain something like:
 [TomorrowOS] listening on http://0.0.0.0:<PORT>
 ```
 
+Confirm the **Web preview** (not Canvas) shows the Control Panel at `/`.
+
 ### F. Verify before telling the user “done”
 
-1. Open the Control Panel URL.
-2. `GET /brand.json` → 200 and correct `name` / colours.
-3. In browser console on the Control Panel origin:
+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") + "/");
@@ -390,22 +489,28 @@ ws.onopen = () => console.log("WS OK");
 ws.onerror = (e) => console.log("WS ERR", e);
 ```
 
-4. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
+5. Confirm the **Publish readiness checklist** in **Runtime & Replit publish rules**.
 
 If WebSocket fails, fix Run command / process crash / sleep **before** asking the user to pair a TV.
 
 ### G. Tell the user next steps (no code)
 
 1. Keep this Repl **running** (Always On if available).
-2. On the TomorrowOS player, enter the CMS URL: `https://<your-repl>.replit.app/`
-3. Enter the 6-character pairing code from the screen into the Control Panel.
-4. Create a playlist, upload media, Publish to the device.
-5. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
+2. **Published Control Panel URL:** `https://YOUR-REPLIT-DOMAIN`
+3. On the TomorrowOS player, enter the CMS URL: `https://YOUR-REPLIT-DOMAIN/`
+4. Enter the 6-character pairing code from the screen into the Control Panel.
+5. Create a playlist, upload media, Publish to the device.
+6. Point them at `PLAYER_INSTALL.md` in the SDK for player install details.
 
 ---
 
 ## What not to ask / change
 
+### Forbidden questionnaire sources
+
+- **`LLM_PROMPT.md`** — not used on Replit setup; its five questions are **replaced** by REPLIT_SETUP Questions 1–4
+- Standalone “target platform” / “hosting target” / “use case” prompts outside Question 4
+
 Do **not** ask the user how to implement:
 
 - WebSocket framing
@@ -421,6 +526,8 @@ Do **not**:
 - Skip Cloudinary recommendation without stating the persistence tradeoff
 - Claim uploads are “permanent” on Replit local disk without Object Storage or Cloudinary
 - 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
 
 ---
 
@@ -446,9 +553,11 @@ 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 |
 | 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"]` |
+| `EADDRINUSE` on start | Old process holding port | Stop stale processes, clear background tasks, restart Repl |
 | Upload: `storage.objects.create` denied | Replit Object Storage IAM | Fix Object Storage permissions **or** switch to Cloudinary |
 | Upload OK then thumbnails vanish later | Non-persistent `public/uploads` | Object Storage or Cloudinary |
 | Supabase connection errors | Wrong URL or using reserved `DATABASE_URL` | Use `SUPABASE_URL` + `TOMORROWOS_STORE=supabase` |
@@ -458,4 +567,6 @@ TOMORROWOS_STORE=sqlite
 
 ## Protocol version
 
-`replit-setup/1.0` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.1` — 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).

package/package.json

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