@tomorrowos/sdk 0.8.2 → 0.8.3

package/REPLIT_SETUP.md

@@ -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.
+Artifact kind must be **web** (never **api**). Question 4 only updates **brand.json**.
 After all setup questions are answered (including Cloudinary Secrets if you chose Cloudinary), configure and start — minimal verification only (Web app type + Preview at /). **Never test Supabase connection** — save `SUPABASE_URL` and move on. No Supabase or WebSocket tests.
 Do not skip steps.
 ```
@@ -23,7 +24,31 @@ 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.
+**Before Question 1:** ensure the Replit workspace primary artifact **`kind` is `web`** (see **IRON RULE: `web` kind only**). If the project is `api` / API-only or not publishable, **fix artifact kind first** — do not continue the questionnaire on a broken project type.
+
+---
+
+## IRON RULE: `web` kind only (Publish will fail on `api`)
+
+> **This is the #1 deployability rule. Non-negotiable.**
+
+TomorrowOS CMS serves a **browser Control Panel at `/`** plus WebSocket for TVs. Replit’s publish detector treats **`kind = "api"`** artifacts as **not deployable** as a user-facing app — Publish may only see design mockups / libs and fail with *“api-server artifact isn't being recognized as deployable”*.
+
+| Required | Forbidden |
+|----------|-----------|
+| Primary artifact **`kind = "web"`** | **`kind = "api"`** on the CMS artifact |
+| Homepage / project type: **Web app** | **API server** as the only publishable artifact |
+| `GET /` → Control Panel HTML (`public/index.html`) | `artifacts/api-server` with `kind = "api"` for this CMS |
+| `.replit` + `npm run start` → live Node (`tsx server.ts`) | Splitting CMS into a non-publishable API artifact |
+
+**Agent must enforce before and after Q&A:**
+
+1. If `.replit-artifact/artifact.toml` (or artifact metadata) shows **`kind = "api"`** → change to **`kind = "web"`** immediately (validated temp-file flow). **Never** leave the CMS on `api` kind.
+2. **Do not** scaffold TomorrowOS CMS under `artifacts/api-server` with `kind = "api"`. The CMS lives at the **project root** (or a **`web`** artifact at `/`).
+3. **Do not** create a separate `api` artifact “for the backend” — TomorrowOS is one **web** app (HTTP + WebSocket in `server.ts`).
+4. After setup, confirm publish detector sees a **web** artifact serving `/` — not api-only.
+
+**If Publish says api-kind / api-server not deployable:** fix `kind` to **`web`** first, then `.replit` ports + `deploymentTarget = "autoscale"`. Creating a **new Web app** Repl is the fastest fix if Agent locked the project as API-only.
 
 ---
 
@@ -64,6 +89,7 @@ Then ask **Question 1** — do not switch to `LLM_PROMPT.md`.
 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.
 9. **Supabase: configure only — never test.** Save `SUPABASE_URL` + `TOMORROWOS_STORE=supabase` and proceed. **Do not** ping Postgres, run `psql`, start the server solely to verify DB connectivity, or treat log errors like `ENOTFOUND` / `database connection failure` in **Replit dev / Preview** as a failed setup. Supabase often works only after **Publish** (production networking), not in the dev shell.
+10. **Artifact kind = `web` only.** **`kind = "api"` is forbidden** for the TomorrowOS CMS artifact. See **IRON RULE** above. Setup is incomplete if Publish would still see an `api` artifact.
 
 **Question order after Q1:**
 
@@ -76,7 +102,9 @@ Never insert extra questions between these steps. When the user chooses Cloudina
 
 ## 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.
+> **Reminder:** Re-read **IRON RULE: `web` kind only** — `api` kind is never acceptable for this CMS.
+
+TomorrowOS CMS is a **user-facing Web app** (Control Panel at `/` + WebSocket for TVs). Replit must treat it as a **`web`** artifact, **not** `api` / API-only.
 
 ### Create the project correctly (do this first)
 
@@ -89,6 +117,7 @@ When scaffolding a **new** Repl:
 
 **Forbidden setups that cause publish failure:**
 
+- ❌ **`kind = "api"`** on the CMS artifact (`api-server`, `artifacts/api-server`, etc.)
 - ❌ 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
@@ -133,7 +162,8 @@ ignorePorts = false
 - 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.
+- 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 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`.
 
@@ -154,14 +184,15 @@ After Publish, the public URL is:
 
 **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.
+1. Open `.replit-artifact/artifact.toml` (or artifact config) — set **`kind = "web"`** (never `api`). This is the most common fix.
+2. 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).
+3. Replace `.replit` with the template above (`entrypoint`, `modules`, `[[ports]]`, `deploymentTarget = "autoscale"`).
+4. Confirm `server.ts` calls `tomorrowos.listen({ staticRoot: join(__dirname, "public"), host: "0.0.0.0", port: Number(process.env.PORT) || 3000 })`.
+5. Confirm `GET /` returns Control Panel HTML (not JSON-only API root).
+6. In Publishing, switch to **Autoscale** if currently Static.
+7. 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.
+Tell the user plainly if step 2 requires a new Repl — API-only projects cannot publish a browser CMS without **`kind = "web"`**.
 
 ---
 
@@ -201,7 +232,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.8.2",
+    "@tomorrowos/sdk": "^0.8.3",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -255,7 +286,7 @@ If the workspace already has a `.replit`, **merge** these keys — do not wipe u
 
 **Only these three checks matter after setup.** Do not add more unless Publish fails.
 
-1. **Web app, not API** — project / primary artifact is **Web app** (not `api-kind` / API-only).
+1. **Web app, not API** — primary artifact **`kind = "web"`** (not `api` / 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.
 
@@ -486,7 +517,11 @@ The SDK auto-detects these env vars and uploads media to Cloudinary. New uploads
 
 ---
 
-## Question 4 — Brand / TomorrowOS app look
+## Question 4 — Brand / TomorrowOS app look (`brand.json` only)
+
+> **Scope:** Question 4 answers **only** update **`brand.json`** — colours, name, tagline, logo path, `cms.expectedScreens`, etc. They configure how the **TomorrowOS player app** looks and metadata flags.
+>
+> **Question 4 does NOT affect:** Replit Publish, artifact `kind`, `.replit`, `server.ts`, Secrets, Supabase, Cloudinary, ports, deployment target, or CMS server wiring. **Never** change deploy/runtime config based on branding answers.
 
 > **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.
 
@@ -505,7 +540,7 @@ The SDK auto-detects these env vars and uploads media to Cloudinary. New uploads
 
 If the user only gives a name and primary colour, use defaults for the rest and say what you assumed.
 
-**Then write / update `brand.json`** at the project root (validate mentally against `brand.schema.json` in the SDK). Minimum example:
+**Then write / update `brand.json` only** at the project root (validate mentally against `brand.schema.json` in the SDK). **Do not** modify `.replit`, `server.ts`, Secrets, or deployment settings from these answers. Minimum example:
 
 ```json
 {
@@ -541,9 +576,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 (Web app first)
+### A. Seed the project (Web app + `kind = "web"` first)
 
-**If creating a new Repl:** choose **Web app** on the Replit homepage before `init`.
+**If creating a new Repl:** choose **Web app** on the Replit homepage before `init`. Confirm `.replit-artifact/artifact.toml` has **`kind = "web"`** after init.
 
 ```bash
 npx @tomorrowos/sdk@latest init .
@@ -657,6 +692,8 @@ Do **not**:
 - 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
+- Set or leave artifact **`kind = "api"`** for the TomorrowOS CMS
+- Change `.replit`, `server.ts`, Secrets, or deployment config based on **Question 4** branding answers (those go in **`brand.json` 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
 - **Debug or “fix” Supabase** because dev logs show `getaddrinfo ENOTFOUND` or `database connection failure` — save config and finish setup instead
@@ -685,7 +722,7 @@ TOMORROWOS_STORE=sqlite
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| 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 `/` |
+| 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` |
 | 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` |
@@ -701,11 +738,13 @@ TOMORROWOS_STORE=sqlite
 
 ## Protocol version
 
-`replit-setup/1.6` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.7` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+
+**Changelog 1.7:** **IRON RULE** — artifact **`kind = "web"` only** (never `api`); Question 4 **only** writes `brand.json` (no deploy/server changes).
 
-**Changelog 1.6:** **Never test Supabase** in Replit dev — `ENOTFOUND` / connection errors in Preview logs are expected; setup completes when Control Panel loads.
+**Changelog 1.6:** **Never test Supabase** in Replit dev — `ENOTFOUND` in Preview logs is expected.
 
-**Changelog 1.5:** Cloudinary Secrets collected **inside Question 3** — no separate “3b” step; show Secrets form immediately when user picks Cloudinary.
+**Changelog 1.5:** Cloudinary Secrets inside Question 3 — no “3b” step.
 
 **Changelog 1.4:** mandatory Cloudinary credential collection before Question 4 (superseded by 1.5 flow).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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-artifact/artifact.toml

@@ -0,0 +1,5 @@
+# TomorrowOS CMS — must be "web" for Replit Publish (never "api").
+kind = "web"
+previewPath = "/"
+title = "TomorrowOS CMS"
+version = "1.0.0"

package/templates/cms-starter/package.json

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