# Start with Gamestage Gamestage takes a game that works in a browser and moves its answers, scoring, locks and settlement behind an Engine the fan cannot edit. The creator keeps the interface. This is the agent front door. The human documentation begins at `https://gamestage.ai/docs`. ## Get the tool and agent instructions ```sh npx skills add https://gamestage.ai/skill ``` This writes the Gamestage instructions for your coding agent. It installs nothing globally. Run it again when you want the current instructions. `npx skills add gamestageai/agent-skills` installs the same file from GitHub, where a worked example of each game format sits beside it. Then run the CLI from npm: ```sh npx gamestage start ``` Nothing needs to be installed first. `start` reads the directory and tells the agent which command is next. ## If you want the CLI on disk To have the tool as a file before you run it, take the bundle on its own. It arrives as a file and does nothing until you run it. Every `gamestage ` below is then `node gamestage.mjs `: ```sh curl -fsSL https://gamestage.ai/cli -o gamestage.mjs node gamestage.mjs start ``` The shell installer at `https://gamestage.ai/install` is the other on-disk option. It puts `gamestage` on your PATH and writes the same agent instructions. Read the script before running it. The bundled CLI requires Node 20 or newer. The Gamestage repository itself uses Node 22.13 or newer. ## Who does the work The coding agent does the migration. The CLI inspects, serves, validates and verifies. It does not make the judgement calls and it does not edit the creator's source. The agent must: 1. Inspect the project. 2. Choose the matching built game format. 3. Move private solution material into `backend.round` in `gamestage.yaml`. 4. Replace browser-owned decisions with the Gamestage client. 5. Run the real Engine rules locally. 6. Verify that the Engine decided and the page rendered the result. Full route: `https://gamestage.ai/docs/migration.md` ## Existing game ```sh gamestage inspect . --write ``` Source inspection is read-only. `--write` adds the App Manifest and refuses to replace an existing one unless `--force` is present. The report separates what stays in the interface, what moves behind authority, missing platform support and questions that need a person. ## New game ```sh gamestage create --name "My Game" --format hunt ``` `create` scaffolds a playable page for `hunt`, `push`, `group`, `predict`, `bingo` and `shoot`. It never replaces a file that is already there: what it finds is kept and named, and an existing `gamestage.yaml` stops it outright, because that file already holds a game. `--force` overrides both. Choose from the seven Engine rules that run: * `hunt`: find a known subset of a board. * `push`: build towards a ceiling using private values. * `group`: find hidden sets and receive whole-guess feedback. * `predict`: commit before a result exists and mark later. * `bingo`: each fan is dealt their own board from a shared pool. * `shoot`: aim, pick a power, shoot; the Engine plays the keeper. * `place`: a card is dealt; drop it on a category it fits. Choice guide and fields: `https://gamestage.ai/docs/game-formats.md` ## Inspecting and writing need no account. Running and proving go through one. ```sh gamestage manifest validate gamestage.yaml no account gamestage client no account gamestage dev signed in gamestage verify signed in ``` Inspect a prototype, work out what must move, write the round and rewrite the page before anybody signs in. There is one Engine, the one a fan plays, so `dev` and `verify` reach it through a signed-in account rather than through a local copy of it. Neither needs that account approved: approval only gates the hosted commands below. If a command refuses for want of one, hand back to the developer with what it said. Do not stand up a substitute runtime and do not weaken the manifest to get past `verify`. `dev` runs the creator's container through the real Engine rules. `verify` checks that no solution material leaked, that the Gamestage client is present, that every producer setting the page offers is read, that a browser play's rendered score came from the Engine, and that the page notices the connection going and coming back. That last one is made rather than read: the browser's network is taken away, and the check is whether anything on the screen changed. `verify` exits `0` only when every check verifies. It exits `1` when a check is open and the game failed verification, or `2` when a check was skipped and the result is unverified. A skipped browser check does not prove the screen, and a game with no round of its own is checked against a stand-in, which proves the wiring and nothing about the game: that is a `2` rather than a pass. ## Hosted deployment needs an approved account The hosted route is: ```sh gamestage login gamestage link github gamestage manifest register gamestage.yaml gamestage deploy --dir . ``` A deployed game starts as **dev**, not a game with a real audience. Moving it to **prod** is `gamestage promote `, which is the creator's call rather than yours: hand it over rather than running it. Approval alone does not move a game either. Prod also needs the workspace on a paid plan, which only Monterosa can arrange and no command captures, so never tell a creator to run something to fix that half. Today neither state changes what a fan meets, so promotion records the decision and nothing else. `login` registers an account and `link github` requires a person to approve a browser device flow. Registration is not approval: an account waits until we approve it, and until then the commands that reach the Engine refuse and say so. Once approved, the four commands above run on the CLI's own default, `https://api.gamestage.ai`, with nothing to configure. `GAMESTAGE_CONTROL_URL` only points the CLI at a different environment and is not part of this route. Identified-player JWT validation works in the shared validator and the local `dev --as` harness. On a deployed game it needs the issuer and its keys configured on that deployment, which Monterosa sets rather than a creator's manifest: ask us to configure it before relying on identified play in production. Unset, the deployed Engine refuses every token. Never claim a hosted deployment from a successful local verification. ## Starter Starter is where a game is built and tested. Reaching an audience needs a paid plan, which only Monterosa can put a workspace on. The current contract defines one live game, 1,000 monthly devices and 250 MB storage. The live-game allowance is enforced on deploy and wake. Devices and storage are both real numbers, tracked from what each game reports and what the bucket holds, but the deploy gate on them is held empty, so reaching either does not refuse a deploy today. Only the live-game allowance actually refuses. There is no concurrency meter, and no figure for it is enforced. Current availability and exclusions: `https://gamestage.ai/docs/starter-plan.md` ## Human handoffs A person must approve creator sign-in, GitHub linking and any action that takes a live game off the air. A person also owns rights, identity, age-gate, promotion and production approval decisions. Handoff checklist: `https://gamestage.ai/docs/how-it-works.md` ## Contracts * App Manifest reference: `https://gamestage.ai/docs/app-manifest.md` * App Manifest JSON Schema: `https://gamestage.ai/schemas/app-manifest/1.0` * Player API: `https://gamestage.ai/docs/player-api.md` ## Rules for agents * Add `--json` when branching on command output. Read the exit code. * Never invent a player id. The Engine issues a signed anonymous session. * Never ship `gamestage.yaml`, environment files or private values beside the game. * Render the Engine's committed result. Do not recompute it in the browser. * Treat a refusal as a decision with a cause, not as a transient error to retry. * Stop for a person at browser approval or when an action affects a live audience. * A refusal for want of an approved account is a hand-over. Never substitute a local runtime for the Engine, and never edit the manifest to get past `verify`. Gamestage is in Preview. Inspecting and migrating a prototype work for anyone; publishing it goes through an account we have approved. Running and proving it need only a signed-in account.