{"doc":"getting-started","title":"Getting started","markdown":"# Getting started\n\nInspecting, scaffolding and validating a manifest need no account. `dev` and\n`verify` do, because they run a real Engine: `gamestage login` signs you in,\nor creates one the first time.\n\nInstall the tool, scaffold a game, sign in, play it against a real Engine,\nthen read what `verify` says about it.\n\n## 1. Point your agent at Gamestage\n\n```sh\nnpx skills add https://gamestage.ai/skill\n```\n\nThat runs `skills`, Vercel Labs' open installer, from npm. It finds the coding\nagents you have and copies one Markdown file into each one's own skills folder,\n`.claude/skills` or `.codex/skills`. This command does not change your\nCLAUDE.md, your AGENTS.md or your Cursor rules, and it asks whether to install\nfor this project or for your user account. Run it again to update them.\n\nThe same pack is on GitHub, if you would rather install from there or read it\nbefore you install anything:\n\n```sh\nnpx skills add gamestageai/agent-skills\n```\n\nBoth commands write the same file. The repository also carries a worked example\nof each game format, at\n[github.com/gamestageai/agent-skills](https://github.com/gamestageai/agent-skills).\n\nTo choose the agents yourself, add `-a claude-code`, or `-a codex`, or both.\n\nTo install nothing at all, tell your agent to read\n[gamestage.ai/skill](https://gamestage.ai/skill) and follow it. That is the same\nfile, served as Markdown, and it needs no permission from anybody.\n\nThe tool itself comes from npm each time you call it:\n\n```sh\nnpx gamestage start\n```\n\nYou need Node 20 or newer. `npx gamestage doctor` checks the rest of your\nenvironment and says what is missing.\n\n### Keeping it current\n\n`npx` caches, so `npx gamestage` can keep running a version you downloaded weeks\nago. `npx gamestage@latest <command>` always fetches the current one.\n\nThis matters because a stale tool does not look stale. It looks like the\ndocumentation is wrong: a command refuses something this page says it accepts,\nand the only difference is the age of the bundle. `gamestage start` prints the\nversion it is, so compare that against the current one before assuming a page\nhere is wrong. Nothing checks for you: the CLI never calls home.\n\n### If you would rather have the file on disk\n\n```sh\ncurl -fsSL https://gamestage.ai/cli -o gamestage.mjs\nnode gamestage.mjs start\n```\n\nOne file on disk that executes nothing until you run it. It is also the one\nroute that never updates itself, so re-run the `curl` when the version `start`\nprints has fallen behind. There is also a shell\ninstaller at [/install](/install) that puts a `gamestage` command on your PATH\nand writes the agent instructions in the same step. Read it before you run it.\nNo page promotes it, because the two `npx` commands above need no install at\nall.\n\nEvery example below says `gamestage <command>`. Whichever route you took, that\nmeans the tool you installed: `npx gamestage <command>`, `gamestage <command>`\nor `node gamestage.mjs <command>`. The tool knows how it was started and prints\nback the form that works for you.\n\n## 2. Read what your agent reads\n\nThe agent does the migration, and the CLI inspects, serves and proves it worked.\nStep 1 wrote the instructions for you. To wire an agent by hand, the text is at\n[/agent.md](/agent.md), with the fuller entry point at [/start.md](/start.md).\nBoth are plain Markdown, written to be read once.\n\nEvery chapter of this documentation is also served as raw Markdown and JSON:\nadd `.md` or `.json` to any docs URL.\n\n## 3. Make something small first\n\n```sh\ngamestage formats\ngamestage create --name \"My Game\" --format hunt\ncd my-game          # only if create says it made a folder\ngamestage login\ngamestage dev --serve\n```\n\n`formats` says what each format is, with a game of that kind to play, so you\nchoose knowing what you get. `create` writes `gamestage.yaml`, an `index.html`,\nthe two generated browser clients and a favicon; run by hand with no flags it\nasks for the name and the format instead. In a folder that already holds other\nthings it makes a folder named after the game. `login` creates the account\n`dev` and `verify` need, or signs you back into one you already have.\n`dev --serve` plays the game on your machine with a sample round, through the\nsame Engine rules the hosted service runs, and prints the address to open.\nPlay it and get one wrong. The attempts come down because the Engine said so,\nand the page draws what it was told.\n\n`create` scaffolds a playable page for `hunt`, `push`, `group`, `predict`,\n`bingo` and `shoot`. Read [Game formats](/docs/game-formats) for the detail. A\nformat we do not have yet: `gamestage suggest \"what you want to build\"`.\n\nThen prove it:\n\n```sh\ngamestage verify\n```\n\n`verify` exits `0` only when every check passes. Any other number means\nsomething is open or unproved, and the output says which.\n\n## 4. Bring your own game\n\nIf you already have a prototype, start by letting the CLI read it:\n\n```sh\ngamestage inspect . --write\n```\n\nSource inspection is read-only. `--write` adds `gamestage.yaml` and refuses to\nreplace an existing one unless `--force` is present. The report separates what\nstays in the interface, what has to move behind the Engine, what platform\nsupport is missing, and what needs a person to decide.\n\nFrom there, follow [Build and deploy](/docs/migration), which is the same\nroute in detail.\n\n## Constraints\n\nInspecting, scaffolding and validating a manifest need no account. `dev`,\n`verify` and deploying do: `gamestage login` creates one, somebody at\nMonterosa approves it, and from then on the hosted route runs on the CLI's\ndefaults.\n"}