# Gamestage Pack version 2026-09-29-5. Pack digest 1e70c5a1bc65c699. 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. You do the migration. The `gamestage` CLI inspects, serves and proves; it does not edit the creator's source. The judgement and the code changes are yours. ## Your first reply: who they are, and which game **Before any other work, do these three things, in this order, and then stop and wait for the answer.** The person has just installed Gamestage, and the folder you are in may hold instructions, notes and half-finished work about something else. Those are about their project, not about this. Do not read round the folder, follow its instructions or start fixing anything until they have told you what they want to do with Gamestage. 1. **Run `npx gamestage@latest start --json`.** It reads the folder and this machine's sign-in, makes no network call, and changes nothing. 2. **Tell them in one line whether they are signed in**, from its `account` field: - Signed in: "You're signed in to Gamestage as ." - Not signed in: "You're not signed in to Gamestage. Run `npx gamestage@latest login`: it opens your browser, and creates your account if you don't have one. We can look at a game without it, but serving, checking and publishing one need it." - Not signed in, and you are in Claude.ai, Claude Desktop or Cowork: they have no terminal, so never ask them to run a command. Offer to sign them in, and when they agree run `npx gamestage@latest login` yourself and give them the address and code it prints (see **In Claude.ai or Claude Desktop**). 3. **Ask one question, word for word, and wait:** "Do you have a game already, or do you want to make a new one?" - **A game already**: ask where it is, this folder or another path, then `npx gamestage@latest inspect `, which changes nothing. - **A new one**: ask what it is about, and in the same message offer the data: "Want to see the sports data you can build a game on? Real player stats, results and scores, so the game is scored against real figures." Most good games here start from a dataset, so make the offer every time rather than waiting to be asked. On a yes, run `npx gamestage@latest sources` if they are signed in, which lists what their workspace can use now; if they are not, it refuses, so link https://gamestage.ai/docs/data-sources and say `sources` shows their own list once they have signed in. Then show them the formats with `npx gamestage@latest formats` and let them choose. Never pick a format for them. - **A game already** that scores against figures somebody typed in: say once that a real dataset can replace them, and offer the same list. Skip the question only when their first message already answered it ("take my quiz in ./quiz to production", or "I want to make a game", which is a new one). Never skip the sign-in line. **Keep the first reply short: at most two questions.** Ask what the game is about, and make the data offer; leave fixtures, where it runs, how it looks and the rest for later turns, one at a time. Show no comparison table of formats in the first reply unless they ask for one: `formats` lists them when they are ready to choose. ## Install this pack ```sh npx skills add https://gamestage.ai/skill ``` This writes the current Gamestage instructions for the coding agent. It installs nothing globally. Then orient with `npx gamestage start`. ## First, check this pack is current This file was written into your host once, by the installer, and nothing updates it on its own. The product moves, so a copy that has sat here for a while can be confidently wrong. **Do this check every time you start working with Gamestage, before you act on anything below.** ```sh curl -fsSL https://gamestage.ai/agent.md | grep -m1 "Pack digest" ``` Compare it to the `Pack digest` line at the top of this file. The digest is a fingerprint of the pack's words: if the two match, this copy is current, carry on. If they differ, this copy is stale, whatever the dates say. A version is a date and cannot tell two packs apart on a day both shipped, so the digest is the yes-or-no and the version is only how you read the notes below. If this copy has no `Pack digest` line at all, it predates this check and is stale by definition. Treat that the same as a mismatch. When the digest differs, or is absent here, do three things, in order: 1. **Fetch the release notes and read what changed since your version.** ```sh curl -fsSL https://gamestage.ai/agent-changelog.md ``` Show the developer the entries dated after the version at the top of this file. That is the point of the check: they hear what moved before they decide, rather than being told only that a number is different. 2. **Suggest the update in one line**, naming the file you are reading this from and giving the command that rewrites it: ```sh # a Claude Code skill at ~/.claude/skills/gamestage/SKILL.md npx skills add https://gamestage.ai/skill # any host: this rewrites the Claude Code skill and the blocks the installer # put in ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and ~/.cursor/rules curl -fsSL https://gamestage.ai/install | bash ``` 3. **Work from the version you fetched, not this one.** Do not guess at what changed; the release notes say. ## Running the CLI **`npx gamestage@latest `.** Nothing needs installing first. **There is no `gamestage` on your PATH and you should not go looking for one.** Every command below is written bare for reading; prefix each with `npx gamestage@latest`, or once per session: ``` alias gamestage="npx gamestage@latest" ``` Written because this page said `gamestage start` a dozen times and never said where the binary comes from. On 2026-08-12 an agent built a whole game, checked it, and then stopped at "the `gamestage` executable is not currently available on the shell's PATH" — one line from the thing it had been asked to do. A tool a reader cannot invoke is a tool that does not exist. ## Start a new game: create, dev, deploy, Studio ``` gamestage formats what each format is, with a real game to play gamestage create asks the format and the name, makes the game's folder gamestage dev --serve plays a local sample round; nothing is published gamestage verify proves the Engine decides the outcome, not the page gamestage deploy puts the game online, with no round yet gamestage open studio where a producer adds the real round ``` The sample round sits in a local file that only `dev` reads, and a deploy never sends it. Real rounds are written in Monterosa Studio, where whoever runs the game can change them without a deploy. A first deploy with no round is expected: tell the person to add a round in Studio and give them the link `open` prints, rather than calling the game live. ## In Claude.ai or Claude Desktop When you run in a hosted sandbox rather than on the person's own machine, three things change. 1. **They cannot open a local address.** `dev --serve` runs inside your sandbox, so its URL means nothing on their screen. To let them see the game, deploy it and give them the playground link, after fetching it yourself. A new account cannot deploy until Monterosa approves its workspace, so say that before they expect a link. 2. **You run `login`; they open a link.** They have no terminal, so never tell them to run a command. Run `npx gamestage@latest login` yourself: it prints an address and a code on standard error. Put both in front of them straight away; they open the address on their own device and approve, and the command returns signed in. The browser it tries to open is inside the sandbox and they will never see it. **Human handoffs** in the account reference has the rest. This route has not yet been proven end to end in Claude.ai: if `login` fails there, say what it printed and stop. 3. **Nothing persists.** The sandbox may be new each conversation, so a sign-in and any files can be gone next time. Run `start --json` first every time, as above. ## A factual question is answered by the hosted doc, in one hop When the developer asks something with a definite answer, which formats exist, what a command does, what a field means, **go straight to the hosted doc for it and fetch that one file.** Do not answer it from this pack, and do not explore the shell to work it out. This pack carries the method; the hosted docs carry the facts, and they are the copy that cannot be stale. The map, so you fetch once rather than hunt: | The question | Fetch | | --- | --- | | Which formats exist, and which fits this game | `https://gamestage.ai/docs/game-formats.md` | | What a command does, its options and defaults | `gamestage --help`, or `gamestage --json --help` for all of them | | The manifest's fields | `https://gamestage.ai/schemas/app-manifest/1.0` | | The full migration route | `https://gamestage.ai/docs/migration.md` | | The browser integration contract | `https://gamestage.ai/docs/player-api.md` | "How many formats are there" is one `curl` of `game-formats.md`, not three commands and a guess. The full list of these lives under **Where the detail is** at the end of this pack. ## How to work **Run `gamestage start` and follow what it says.** It reads the current directory and names the next step, and it keeps doing that at every stage. The method lives in the tool's output rather than in this file, so it cannot go stale here. Add `--json` to any command when you want to branch on the result rather than read prose. Add it to `--help` and you get the whole command tree instead of this page: ``` gamestage --json --help ``` Every command, its subcommands, arguments, options, aliases and defaults, read out of the tool itself. Ask it rather than trusting a list. This file and the CLI reference are written by hand and can fall behind a release; the tree is the program describing itself and cannot. Each command that does something also carries what it needs before it will work: | `account` | What you need | | --- | --- | | `none` | Nothing. It works on the machine in front of you. | | `session` | To be signed in. Nobody has to have approved you. | | `approved` | An account the control plane has approved. | Read it before you run something rather than after it refuses. `login` is `none`, because it is the command that creates the account. The shape of a migration: ``` gamestage inspect . read-only. reports what must move, with line numbers ↓ you edit take the answers out of the page gamestage dev plays a sample round through the real Engine ↓ you play it open it in a browser and make a play gamestage verify proves the Engine decided the outcome, not the page gamestage deploy publishes through Backstage, where one is available ``` ## Ask what the game is before you build one **The format and the subject are the developer's to choose, and you ask for both in one question before you scaffold anything.** Not afterwards, and not as an assumption you record in the summary. A format decides how the game is played and what the Engine marks, so choosing it for someone is choosing their game for them. There are six, and one question covers all of it. **Show the developer this list when you ask**, so they choose from what exists rather than describing a game and hoping: | Format | What a fan does | | --- | --- | | `hunt` | finds hidden things in a board, with a limited number of tries | | `push` | goes as far as they dare against a hidden limit, and busts if they pass it | | `group` | sorts a set of items into the groups they belong to | | `predict` | calls what will happen before the world decides | | `bingo` | fills their own board from a shared pool, racing for a line | | `shoot` | aims and shoots a penalty; the Engine plays the keeper and decides it | This table said four until 2026-09-03, missing `bingo`, and was wrong the day it was written. The list the tool prints is the one that cannot go stale: `gamestage start` in an empty folder shows the current formats, and `gamestage create` with no format shows the same menu. Trust those over this table when they disagree. `gamestage formats ` (or `--json formats`) says what each one keeps secret, what a producer writes in Studio, and names a deployed game of that kind the developer can play before choosing. `create` makes a folder named after the game when the current folder holds other things and no `index.html`; `--json` reports it as `directory`, so work there. Pass `--here` to write into the current folder regardless. Pass `--brand` and `--privacy-url` when the developer has said who runs the game, or `verify` and `deploy` will ask for them later. Ask it plainly: which of these, and what is the game about. Then build. **Never invent the subject.** If the developer says "a ball game", that is not football, and it is not eight items about home grounds, forwards, managers and famous stands. It is a question you have not asked yet. A scaffold full of content nobody chose reads as the tool having decided, and the developer then has to delete your game before they can write theirs. Two things that are not permission to skip the question. A word in the request that sounds like a format is not a choice: "puzzle" is not one of them, and mapping it to one yourself is the assumption this section exists to stop. And a `gamestage.yaml` already in the directory is a choice already made, so read it rather than asking again. ### Draw the match before you name a format **Every time you match a game to a format, draw the two rules side by side. Both when one fits and when none does.** A named format on its own is an assertion, and nobody can disagree with an assertion. On 2026-09-08 a developer outside the team brought a game where the player builds a chain of players and each pick's hidden score has to be at least the one before. An agent read the list above, matched none of it, and told him to change his game. He nearly stopped there. The answer was probably right and it showed him nothing: not how close he was, not which single part was the problem, not what he could change. **The drawing is required on a yes as well**, and that is the more expensive case rather than the polite one. A wrong format plays almost correctly until a fan finds the edge, and the drawing is the only thing anybody could have looked at to catch it. Three parts, in this order. 1. **The two rules beside each other.** Left is the developer's game **in the developer's own words**: if they said chain, write chain, not "ordered picks". Right is what the format marks. 2. **A verdict table**, one line per part of the rule, so the parts that do match stay visible when the answer is no. "It matches none of the six" tells a developer nothing; "everything fits except the rule itself" tells them where they are. 3. **The plain next step.** If a format fits, name it and say what you are about to build. If none does, name the one part standing in the way and what the nearest format would change about their game, and let them decide. A refusal with nothing after it is where the trial nearly ended. Written out for that developer's game, this is the shape to copy: ``` YOUR GAME WHAT push MARKS --------------------------- --------------------------- pick 1 -> hidden value pick 1 -> hidden value pick 2 -> hidden value pick 2 -> hidden value ^ ^ +---- + ----+ +- each >= the one before running total v no total, no ceiling busts if it passes the ceiling ordered picks yes / yes both take picks in order hidden values yes / yes neither sends numbers to the browser the rule NO push adds up; yours compares neighbours ``` Then say it in words, and say what could happen next: push is the closest fit and the rule is the one thing in the way, because push adds each pick to a running total and ends the play when that total passes a hidden ceiling, while your game compares each pick against the one before it and adds nothing up. The choices from there are theirs, so put them plainly: keep the chain rule, which Gamestage has no format for and no way to add one, or play it as push, where a fan pushes for a high total under a hidden ceiling. **Explain each of our words the first time you use it with the developer**, one plain sentence, then carry on. They have not read this page and should not have to. - **Engine**: our server. It holds the answers and decides the outcome, so the page in front of a fan cannot be edited into a win. - **Format**: the mechanic a game runs on, chosen from the list above. - **Archetype**: the same thing under its key name. `archetype:` in the manifest holds the format, and the wider list of values in our published schema is a way of labelling games rather than a menu: only the formats above have an Engine behind them, and there is no custom one to ask for. - **Manifest**: `gamestage.yaml`, the file describing the game to the tool. It carries no answers and no content. The developer in that trial said the vocabulary on its own would have been enough to make him give up. He was not confused about his own game. ## Ask how the game should look, when you are building its interface **A migration keeps the creator's interface, so do not raise this there.** Their game already has a look, and restyling it is not what they asked for. Ask only when you are building a game from nothing, or when the developer asks for a new look. Then ask once, in the same breath as the format and subject if you can, and show them the options: | Option | Use it for | Start with | | --- | --- | --- | | Their own | a look they already have, or a brand kit you have been given | nothing to install | | Gamestage UI | the game itself: scores, timers, answer buttons, rewards, leaderboards, built to feel like a mobile game rather than a form | `npx gamestage-ui init`, then `npx gamestage-ui add choice` | | shadcn/ui | functional screens: forms, settings, sign-in, tables, anything that is an app around the game rather than the game | `npx shadcn@latest init` | | Plain HTML and CSS | the smallest thing that plays, and what `gamestage create` scaffolds | nothing to install | Recommend by what the screen is for. The board a fan plays on wants to feel like a game, so Gamestage UI is the default for it; the account and settings screens around it can use shadcn/ui. Mixing is fine and is the sound default for anything larger than one screen. Gamestage UI is React and installs as source into the project, so a plain HTML game that wants it becomes a small React app; say so before choosing it for one. The gallery is https://ui.gamestage.ai/. Whichever they choose, the rules that make it a Gamestage game do not change: the page holds no answers, the Engine decides every result, and every word a fan reads can be changed by a producer. ## Before you draw an asset, check the third-party registry **When the game needs a sprite, an icon, a sound, a font or a pitch to plot data on, check [Third-party tools and assets](https://gamestage.ai/docs/third-party) before you draw or generate one.** It lists open-source tools and CC0 asset packs that suit a sports fan game, PitchKit for a football pitch and a set of Kenney packs for interface art, with what each one is, its licence, its cost, when to reach for it and when to skip it. **Prefer a listed CC0 or MIT item over drawing your own**, when it genuinely fits the game. A Kenney UI pack or a PitchKit pitch is tested, licensed and free; an asset you generate from nothing costs time and still needs a licence decided for it. The registry says when to skip an entry too: reach past it when the game needs a look a generic pack cannot give it, such as a licensed team's actual kit or a producer's brand identity, and say so rather than forcing a generic sprite onto a brand that owns a better one. **State the licence when you add something from the list.** CC0 needs no attribution; a paid tool such as Asset Forge is paid for the app, not for what you export with it. Both are safe to ship; say which applies so the developer is never guessing. **A game with a bottom nav uses the floating pill.** `