@tomorrowos/sdk 0.9.59 → 0.9.60

package/README.md

@@ -98,9 +98,9 @@ Supported hosts: **Replit** and **Vercel / v0**.
 1. Follow the host setup doc for this request (`REPLIT_SETUP.md` / `REPLIT_UPGRADE.md`, or `VERCEL_SETUP.md` + `VERCEL_QUESTIONS.md`).
 2. On Vercel: paste Q1–Q3 **verbatim** from `VERCEL_QUESTIONS.md`; after database choice set `TOMORROWOS_STORE` and `DATABASE_SSL` yourself; after media choice set `TOMORROWOS_MEDIA` yourself.
 3. Read `brand.schema.json` for the validated shape of `brand.json`.
-4. Scaffold with the correct template:
-   - Replit / self-host style: `npx @tomorrowos/sdk init` (default `cms-starter`)
-   - Vercel / v0: `npx @tomorrowos/sdk init . --hosting v0 --force` (`cms-starter-v0`)
+4. Scaffold with the correct template (**always `@latest`**):
+   - Replit / self-host style: `npx @tomorrowos/sdk@latest init .` (default `cms-starter`)
+   - Vercel / v0: `npx @tomorrowos/sdk@latest init . --hosting v0 --force` (`cms-starter-v0`)
 5. Apply the user’s answers — brand and use case. Validate `brand.json`. On Vercel, apply the **NON-NEGOTIABLE VERCEL RUNTIME CONTRACT** from `VERCEL_SETUP.md`.
 6. Point the user at `PLAYER_INSTALL.md` and the Control Panel **Download Players** UI once the CMS is running.
 
@@ -115,17 +115,17 @@ Do not write WebSocket transport, pairing wire format, or platform-specific play
 ## 2. Build it yourself
 
 ```bash
-npm install @tomorrowos/sdk
+npm install @tomorrowos/sdk@latest
 ```
 
 Scaffold, install, run:
 
 ```bash
 # Default template (good for Replit, Railway, Render, Fly.io, self-host)
-npx tomorrowos init my-cms
+npx @tomorrowos/sdk@latest init my-cms
 
 # Vercel / v0 Publish (cms-panel + vercel.json + optional Next preview)
-npx tomorrowos init my-cms --hosting v0
+npx @tomorrowos/sdk@latest init my-cms --hosting v0
 
 cd my-cms
 npm install

package/REPLIT_SETUP.md

@@ -18,6 +18,7 @@ If Supabase: show the SUPABASE_URL Secrets input immediately after the choice (s
 If Cloudinary: show all CLOUDINARY_* Secrets inputs immediately after the choice (same Question 2 — one multi-field dialog).
 Question 3: one multi-field dialog with all seven branding inputs stacked (all optional; blanks keep brand.json defaults). Never ask branding fields one-by-one with Next.
 After all setup questions are answered, configure and start — minimal verification only (Web app type + Preview at /). **Never test database connection** in Preview — configure and move on. No DB or WebSocket tests.
+Seed with **`npx @tomorrowos/sdk@latest init .`** only (never untagged `npx @tomorrowos/sdk init` — that can install a stale cached version).
 Do not skip steps.
 ```
 
@@ -108,7 +109,7 @@ Then ask **Question 1** — stay on this file.
 4a. **If Supabase is chosen: never collect `SUPABASE_URL` twice.** One capture right after the choice is enough.
 4b. **Question 3 fields are all optional.** Missing values → keep starter `brand.json` defaults; do not block or re-prompt.
 4c. **`TOMORROWOS_STORE` + `DATABASE_SSL` are agent-owned.** After the Q1 choice (and URL if needed), set them yourself. Never ask the user to type those names/values.
-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.
+5. **Always seed with `npx @tomorrowos/sdk@latest init .`** (or merge `templates/cms-starter` from that same `@latest` install). **Never** run untagged `npx @tomorrowos/sdk init` — npx may reuse a stale cache and pin an old SDK. 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, **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.
@@ -136,7 +137,7 @@ 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).
+4. Run `npx @tomorrowos/sdk@latest init .` at the project root (or merge the cms-starter template from that install).
 
 **Forbidden setups that cause publish failure:**
 
@@ -255,7 +256,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
     "node": ">=20"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.12",
+    "@tomorrowos/sdk": "^0.9.60",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -270,7 +271,7 @@ Allowed extras (optional): `"build-player": "tomorrowos build --platform tizen"`
 }
 ```
 
-Bump `@tomorrowos/sdk` to the latest published version when scaffolding.
+**IRON RULE — always latest SDK:** Scaffold only via `npx @tomorrowos/sdk@latest init .`. After init, confirm `node_modules/@tomorrowos/sdk/package.json` `"version"` matches current npm `latest` (or newer). If older, run `npm install @tomorrowos/sdk@latest` and fix `package.json` to `^<that version>`.
 
 ### Replit Run command
 
@@ -671,11 +672,21 @@ Run these steps in order. Tick mentally; do not skip.
 **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
+# REQUIRED: @latest — untagged `npx @tomorrowos/sdk init` can install a stale cached SDK.
 npx @tomorrowos/sdk@latest init .
 # If the directory is not empty and the user confirms overwrite of starter files only:
 # npx @tomorrowos/sdk@latest init . --force
 ```
 
+Then verify:
+
+```bash
+node -p "require('./node_modules/@tomorrowos/sdk/package.json').version"
+# or: npm ls @tomorrowos/sdk --depth=0
+```
+
+If not the current npm latest, run `npm install @tomorrowos/sdk@latest` before continuing.
+
 If `init` is inappropriate (existing customised project), merge carefully:
 
 - Keep `data/tomorrowos.db` and `public/uploads/`
@@ -775,6 +786,7 @@ Do **not** ask the user how to implement:
 
 Do **not**:
 
+- Run untagged `npx @tomorrowos/sdk init` (always use `npx @tomorrowos/sdk@latest init .`)
 - Replace `@tomorrowos/sdk` with a hand-rolled server
 - Change the production start command away from `tsx server.ts` / `npm run start`
 - Point Supabase at Replit’s reserved `DATABASE_URL` when `SUPABASE_URL` should be used
@@ -823,7 +835,9 @@ Do **not**:
 
 ## Protocol version
 
-`replit-setup/1.12` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+`replit-setup/1.13` — aligned with TomorrowOS protocol `1.0` and `@tomorrowos/sdk` store drivers `sqlite` | `supabase` | `postgres` | `memory`.
+
+**Changelog 1.13:** Seed / upgrade commands **must** use `@latest` (`npx @tomorrowos/sdk@latest init .`, `npm install @tomorrowos/sdk@latest`). Untagged `npx @tomorrowos/sdk init` is forbidden (stale npx cache pinned old SDKs such as 0.9.51).
 
 **Changelog 1.12:** Q1 no longer offers SQLite (Supabase or Replit Postgres only). Q2 no longer offers local disk (Cloudinary or Replit Object Storage only).
 

package/REPLIT_UPGRADE.md

@@ -32,7 +32,7 @@ When any of these triggers fire:
 
 ## Hard rules (non-negotiable)
 
-1. **Do NOT** run `npx @tomorrowos/sdk init` or `npx @tomorrowos/sdk init --force` (or any command that re-scaffolds / overwrites the project from the starter). That would wipe customisations.
+1. **Do NOT** run `npx @tomorrowos/sdk init`, `npx @tomorrowos/sdk@latest init`, or any `init --force` (or any command that re-scaffolds / overwrites the project from the starter). That would wipe customisations. Upgrade = **`npm install @tomorrowos/sdk@latest` only**.
 2. **Do NOT** delete `data/` or `public/uploads/` (or move them aside permanently). Pairings, playlists, and local media must survive the upgrade.
 3. **Do NOT** invent or rotate Secrets (`SUPABASE_URL`, Cloudinary keys, etc.). Keep existing Secrets / `.env`.
 4. **Do NOT** blindly overwrite `public/methods.js`, `public/index.html`, `public/panel.css`, or `server.ts` with template copies. Always **diff → report → merge only with user consent** (or apply surgical patches that preserve custom code).
@@ -79,10 +79,14 @@ Record the **backup path** for the final report.
 
 ### 3. Install latest SDK
 
+**REQUIRED — always `@latest`:**
+
 ```bash
 npm install @tomorrowos/sdk@latest
 ```
 
+Do **not** run `npm install @tomorrowos/sdk` without `@latest` (may keep a stale lockfile / range).
+
 ### 4. Verify `package.json` dependency
 
 Confirm `dependencies["@tomorrowos/sdk"]` reflects a newer / latest range (or exact version after install).
@@ -90,10 +94,17 @@ Confirm `dependencies["@tomorrowos/sdk"]` reflects a newer / latest range (or ex
 - If `package.json` did not update, set `"@tomorrowos/sdk": "^<installed version>"` (or `@latest` resolution result) and run:
 
 ```bash
-npm install
+npm install @tomorrowos/sdk@latest
+```
+
+- Confirm `node_modules/@tomorrowos/sdk/package.json` `"version"` is the **current npm latest** (not an older pin such as 0.9.51).
+
+```bash
+node -p "require('./node_modules/@tomorrowos/sdk/package.json').version"
+npm view @tomorrowos/sdk version
 ```
 
-- Confirm `node_modules/@tomorrowos/sdk/package.json` `"version"` is the **new** version.
+If local version < npm latest, re-run Step 3 until they match.
 
 Record **new SDK version** for the final report.
 
@@ -176,7 +187,7 @@ Tell the user clearly:
 
 ## What not to do
 
-- ❌ `npx @tomorrowos/sdk init` / `init --force`
+- ❌ `npx @tomorrowos/sdk init` / `npx @tomorrowos/sdk@latest init` / `init --force` (upgrade must not re-scaffold)
 - ❌ Delete or empty `data/`, `public/uploads/`, or SQLite DB files
 - ❌ Blind overwrite of customised panel / `server.ts`
 - ❌ Re-run full `REPLIT_SETUP.md` questionnaire during upgrade
@@ -200,6 +211,8 @@ Tell the user clearly:
 
 ## Protocol version
 
-`replit-upgrade/1.0` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+`replit-upgrade/1.1` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+
+**Changelog 1.1:** Emphasize **`npm install @tomorrowos/sdk@latest` only**; verify against `npm view @tomorrowos/sdk version`; forbid untagged installs that leave stale pins (e.g. 0.9.51).
 
 **Changelog 1.0:** Initial upgrade-only Agent contract: install `@latest`, backup, template diff/merge (no init, no data wipe), restart, report versions + smoke.

package/VERCEL_SETUP.md

@@ -39,7 +39,7 @@ Open VERCEL_QUESTIONS.md first.
 For Q1, Q2, Q3: paste each question block VERBATIM. Do not rephrase options.
 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.
-Run: npx @tomorrowos/sdk@0.9.58 init . --hosting v0 --force
+Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
 Keep cms-starter-v0 layout.
 Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
 one TomorrowOS instance only
@@ -206,7 +206,7 @@ Then ask **Question 1**.
 5. **Do not invent** Cloudinary credentials, database URLs, Vercel Blob tokens, brand colours, **or LLM API keys**.
 6. **Postgres env naming:** prefer **`SUPABASE_URL`** for Supabase; prefer **`DATABASE_URL`** for Neon.
 7. **Always prefer pooled connection strings** (Supabase Session pooler **6543**; Neon pooled host).
-8. **Prefer `npx @tomorrowos/sdk init --hosting v0`**. For Replit/Railway use default `init`. Do not rebuild pairing / WebSocket APIs.
+8. **Prefer `npx @tomorrowos/sdk@latest init --hosting v0`**. For Replit/Railway use `npx @tomorrowos/sdk@latest init .`. Do not rebuild pairing / WebSocket APIs. Untagged `npx @tomorrowos/sdk init` is forbidden (stale cache).
 9. **Never commit secrets.** Use Vercel Environment Variables.
 10. **Skip Replit-only files.**
 11. **SQLite is not a production store on Vercel.**
@@ -225,7 +225,7 @@ Then ask **Question 1**.
 ## 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 init --hosting v0` (`cms-starter-v0`).  
+> **Scope:** Layout + `vercel.json` + dashboard. Prefer `npx @tomorrowos/sdk@latest init --hosting v0` (`cms-starter-v0`).  
 > **Do not** break Replit/Railway: those keep using default `init` ??`cms-starter` (root `server.ts` + `server.listen`, no `api/`).
 
 ### Why Scheme A exists

package/dist/cli.js

@@ -201,10 +201,10 @@ Options:
   --force                         With init: copy into a non-empty directory
 
 Examples:
-  npx @tomorrowos/sdk init
-  npx @tomorrowos/sdk init ./my-cms --hosting replit
-  npx @tomorrowos/sdk init ./my-cms --hosting v0
-  npx @tomorrowos/sdk migrate --from sqlite --from-sqlite ./data/tomorrowos.db --to supabase --to-database-url "$DATABASE_URL"
+  npx @tomorrowos/sdk@latest init .
+  npx @tomorrowos/sdk@latest init ./my-cms --hosting replit
+  npx @tomorrowos/sdk@latest init ./my-cms --hosting v0
+  npx @tomorrowos/sdk@latest migrate --from sqlite --from-sqlite ./data/tomorrowos.db --to supabase --to-database-url "$DATABASE_URL"
 `);
 }
 function printMigrateHelp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.59",
+  "version": "0.9.60",
   "description": "TomorrowOS CMS server SDK - WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.59",
+  "version": "0.9.60",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.59",
+    "@tomorrowos/sdk": "^0.9.60",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },
@@ -22,4 +22,3 @@
     "typescript": "^5.5.0"
   }
 }
-

package/templates/cms-starter-v0/README.md

@@ -13,7 +13,7 @@ This starter is for **Vercel Publish** and **v0**. It follows
 ## Scaffold
 
 ```bash
-npx @tomorrowos/sdk init my-cms --hosting v0
+npx @tomorrowos/sdk@latest init my-cms --hosting v0
 ```
 
 ## Local development
@@ -46,5 +46,5 @@ TV endpoint: `https://YOUR.vercel.app/` (players also try `/api` on `*.vercel.ap
 Use the default starter (unchanged Node listen, no `api/` Function):
 
 ```bash
-npx @tomorrowos/sdk init my-cms --hosting replit
+npx @tomorrowos/sdk@latest init my-cms --hosting replit
 ```

package/templates/cms-starter-v0/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.59",
+  "version": "0.9.60",
   "description": "TomorrowOS CMS for Vercel / v0 Publish (Fluid Function + WebSockets + optional Next Preview).",
   "private": true,
   "type": "module",
@@ -17,7 +17,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.59",
+    "@tomorrowos/sdk": "^0.9.60",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },