@joystack/cli 0.1.49 → 0.1.50

package/CHANGELOG.md

@@ -14,6 +14,13 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.50] - 2026-10-11
+
+### Changed
+
+- `joystack setup` tells your agent that `create` makes an empty game, ready
+  to be built, rather than a working game to reshape.
+
 ## [0.1.49] - 2026-10-10
 
 ### Added

package/lib/create.mjs

@@ -1,14 +1,15 @@
 // `joystack create <name>` — bootstrap a standalone Joystack game.
 //
 // The create-next-app gesture: one command → a complete folder that is its
-// own repo, where `joystack dev` immediately serves a WORKING multiplayer game
-// (the platform is not optional — the scaffold joins a room on line one, no
-// "add multiplayer later" tier). The folder name is the slug.
+// own repo, where `joystack dev` immediately serves the game: an empty one, so
+// the first game anyone sees in it is the one they asked for. It is
+// multiplayer from line one (its world.js turns the room on, and `joystack
+// dev` runs one from its first start). The folder name is the slug.
 //
 // ── Where the creator's files come from ─────────────────────────────────────
 //
 // EVERYTHING a creator receives comes from the versioned engine artifact: the
-// starter game (`scaffold/`) and the agent surface (`agent-surface/` — skills
+// skeleton every game starts as (`scaffold/`) and the agent surface (`agent-surface/` — skills
 // plus the Layer-0 managed block). This npm package ships CODE ONLY.
 //
 // Shipping a second copy of the surface (a `template/` folder) inside this
@@ -39,7 +40,8 @@ import { ensureEngine } from './engine.mjs';
 import { reconcileAgentSurface } from './agent-surface.mjs';
 import { readEnv } from './legacy-names.mjs';
 
-// The starter game, inside the installed engine artifact.
+// The skeleton every new game starts as, inside the installed engine artifact.
+// The example games beside it (`examples/`) are read in place, never copied.
 export const SCAFFOLD_DIR = 'scaffold';
 
 const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
@@ -81,7 +83,7 @@ const PLAYWRIGHT_SPEC = '1.64.0';
 // devDependency, exactly like playwright. `joystack test` also runs it.
 const ESLINT_SPEC = '^10.7.0';
 
-// Copy the starter game out of the artifact. One rename: `gitignore` →
+// Copy the skeleton out of the artifact. One rename: `gitignore` →
 // `.gitignore` (npm pack silently strips .gitignore files from a package, so
 // the artifact stores it dot-less).
 function copyScaffold(engineDir, dir, name, version) {
@@ -140,7 +142,7 @@ async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, rec
     runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
   }
 
-  // The engine — and with it the starter game and the agent skills. Signs the
+  // The engine — and with it the skeleton and the agent skills. Signs the
   // creator in via the device flow if this machine has no token yet, and writes
   // the `joystack.engine` pin.
   const engine = await ensure(dir, { apiBase, log });

package/lib/dev.mjs

@@ -115,7 +115,12 @@ export async function dev(opts = {}) {
 // alone and keeps everyone else off the dev tools' routes (the Joystack
 // maker): a report sent through the link then counts as one from this
 // machine, so it can wake the agent and read its reply.
-async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null } = {}, onFailure) {
+//
+// `pollMs` is how often, in milliseconds, the game's files are compared for
+// changes the operating system's events miss (live-versions.mjs); left unset
+// it is that module's default of one second. Tests pass a shorter one so a
+// save is acted on sooner.
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null, pollMs } = {}, onFailure) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -545,6 +550,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     versions = createLiveVersions({
       first,
       auto: reload,
+      ...(pollMs ? { intervalMs: pollMs } : {}),
       log,
       snapshot: sourceFiles,
       make: (o) => makeVersion(o),

package/lib/setup-guide.md

@@ -47,8 +47,9 @@ published URL slug, so it must be **lowercase letters, numbers and dashes**
 npx -y joystack@latest create <name>
 ```
 
-This scaffolds `<name>/` as its own git repo: a working multiplayer game plus
-all the agent instructions and the `/build` workflow, inside the folder.
+This scaffolds `<name>/` as its own git repo: an empty game that runs, ready
+for the next session to build, plus all the agent instructions and the
+`/build` workflow, inside the folder.
 
 **This command will pause and ask the human to sign in.** That is expected — not
 a hang, and nothing has gone wrong. Joystack's engine downloads with the game, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",