@joystack/cli 0.1.46 → 0.1.47

package/CHANGELOG.md

@@ -14,6 +14,16 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.47] - 2026-10-09
+
+### Added
+
+- `joystack setup` prints the guide an AI agent follows to make your first
+  game: ask what to call it, run `create`, then hand off into the new folder.
+  It works from any folder, before you have signed in, so the way to start is
+  now to ask your agent to run `npx -y joystack@latest setup` and follow what
+  it prints.
+
 ## [0.1.46] - 2026-10-09
 
 ### Changed

package/README.md

@@ -9,8 +9,9 @@ cd my-game
 npx joystack dev
 ```
 
-New here? Point your AI agent at **https://docs.joystack.ai/setup.md** and say
-"set me up to make Joystack games."
+New here? Ask your AI agent to run **`npx -y joystack@latest setup`** and follow
+what it prints. It asks what to call your game, creates the folder, and tells
+you how to carry on from inside it.
 
 ## License
 

package/bin/joystack.mjs

@@ -9,6 +9,7 @@ import { lane } from '../lib/lane.mjs';
 import { login, logout, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
+import { setupGuide } from '../lib/setup.mjs';
 import { parseTestArgs, TEST_HELP } from '../lib/test-policy.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
 import { lintCmd } from '../lib/lint.mjs';
@@ -28,6 +29,7 @@ function flag(name) {
 const HELP = `joystack — build and run Joystack games
 
 Usage:
+  joystack setup                The guide an AI agent follows to make your first game folder
   joystack create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   joystack dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
   joystack dev --share          ...and print a public link testers can play (needs cloudflared)
@@ -190,6 +192,9 @@ try {
       console.log(`\nWork in it:\n  cd ${dir} && npx joystack dev\n`);
       break;
     }
+    case 'setup':
+      process.stdout.write(setupGuide());
+      break;
     case 'create':
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;

package/lib/setup-guide.md

@@ -0,0 +1,122 @@
+# Make games on Joystack
+
+Joystack is a place to make multiplayer browser games and play them with
+friends; each game lives at its own address, `https://<name>.joystack.games/`.
+Anyone can make one. You don't
+need to know how to code: your AI coding agent does the technical work; you
+describe the game you want and play-test it.
+
+Joystack is **agent-agnostic**: it works with Claude Code, Gemini CLI, Codex,
+opencode, or any agent that reads a project's instruction files. There is no
+plugin or extension to install. Every game folder carries its own agent
+instructions (`AGENTS.md`, with `CLAUDE.md` / `GEMINI.md` pointers, and skills
+under `.claude/skills/`), so whatever tool you use picks them up.
+
+This guide is what `npx -y joystack@latest setup` prints. It is written for
+the AI agent: **if you are the agent, follow these steps.** If you are the
+human, ask your agent to run that command and follow what it prints.
+
+**Your whole job here is: create the folder, then hand off.** Two steps, and the
+page ends. You are *not* going to build, run, or publish the game from where you
+are now — and this page deliberately doesn't tell you how, because that isn't
+your task and those instructions are not yours to hold.
+
+**They live in the game folder.** The scaffold you're about to create carries its
+own `AGENTS.md`, its own skills (`/build`, `/qa`, `/feedback`, …), its own
+handbook, and the engine's craft docs. An agent picks all of that up **only when
+its working directory is that folder**. That is the entire reason for the
+handoff: not bureaucracy, but the fact that the knowledge for building the game
+is *inside* the thing you're creating, and you can't reach it from out here.
+
+## 1. Prerequisites
+
+- Node.js 20.11+ (`node --version`; install from https://nodejs.org if missing).
+- A Joystack account. You don't need one *before* you start — `create` signs the
+  human in as part of making the folder (step 2). It's free, and it takes a
+  click.
+- Nothing else. The engine, its libraries, and the craft docs download during
+  `create`, into the game folder. There is no global install.
+
+## 2. Create the game
+
+Ask the human what to name the game. The name becomes both the folder and the
+published URL slug, so it must be **lowercase letters, numbers and dashes**
+(e.g. `neon-racer`). Don't invent one silently. It's theirs to choose.
+
+```bash
+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 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
+that download is tied to their account. What happens:
+
+1. A browser window opens on the Joystack activation page.
+2. The command prints a short code (like `WXYZ-1234`) and waits.
+3. The human enters that code in the browser and approves.
+4. `create` continues on its own.
+
+**Tell them this is coming, before you run it** — a browser opening by itself and
+a command that stops mid-way is alarming if nobody warned you. Say something
+like: *"This will open your browser to sign you in to Joystack — enter the code it
+shows and approve, and it'll carry on."* Then read them the code from the output.
+
+If they close the window or it times out, nothing is left behind: `create`
+removes the half-made folder so you can simply run it again.
+
+Once signed in, this machine stays signed in — no other command in Joystack will
+ask again.
+
+## 3. Hand off — and stop
+
+**Say this to the human, and end your turn:**
+
+> "Your game is ready, in the folder `<name>`. Now open your agent again **with
+> that folder as its working directory** — a fresh session inside the folder —
+> and tell it what you want to build. Everything needed to make the game lives
+> in there; I can't reach it from here."
+
+Then stop. **Do not** `cd` in and keep working. **Do not** start the dev server,
+install anything, write files into the new repo, take screenshots, or "just check
+that it works" — it already works, and the folder ships with its own test that
+the next session will run. Anything you do from out here is done *without* the
+game's instructions, on a repo that isn't shaped for your current habits. That is
+how creators end up with stray files in their first commit and confident, wrong
+answers about their own game.
+
+**If the human doesn't know how to do that** — and many won't, this is the one
+genuinely technical moment in Joystack — walk them through it rather than doing it
+for them. Explain it plainly:
+
+> "Whatever you're using me through — a terminal, an editor, a desktop app —
+> point it at the `<name>` folder and start a new chat there. It's the same as
+> opening a project: the folder *is* the game, and it carries its own
+> instructions for me. Once I'm in there I'll know how to run it, build it, test
+> it and publish it — none of which I know from here."
+
+If they're in a terminal, that's usually: close this session, `cd <name>`, and
+start the agent again. If they're in an editor or a desktop app, it's "open
+folder" / "open project" → `<name>` → new chat. Adapt it to their tool; you know
+what they're using and this page doesn't.
+
+That's the last step on this page. The next session takes it from there: it will
+boot the game and build it with them. They're already signed in, and the engine
+is already downloaded — so in there, `joystack dev` just runs.
+
+## What Joystack provides
+
+- **Multiplayer built in.** Rooms, presence, physics authority, identity.
+  Locally `joystack dev` runs the full stack; published games use the platform's.
+- **The engine.** A versioned library of game components and craft docs,
+  downloaded per game and pinned in package.json's `joystack.engine`. Upgrade when
+  you choose.
+- **Services.** LLM-driven NPCs and more, platform-authenticated. No API keys
+  to acquire, ever.
+- **Hosting.** `<name>.joystack.games`, instantly, from `joystack publish`.
+
+Your game's folder is yours: its own git repo, private if you like, hosted
+wherever you like (or nowhere). Joystack never needs to see your source beyond
+what you publish.

package/lib/setup.mjs

@@ -0,0 +1,9 @@
+// `joystack setup`: the guide an AI agent follows to create a creator's first
+// game folder and hand off into it. It ships inside this package, so an agent
+// reads it with one command it can run from any folder, signed in or not, and
+// the steps always match the `create` of the same release.
+import { readFileSync } from 'node:fs';
+
+export function setupGuide() {
+  return readFileSync(new URL('./setup-guide.md', import.meta.url), 'utf8');
+}

package/package.json

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