# The journey ### Before you start This works best if you already made a game and have Claude Code, Codex or another agent and you're in the repo. You'll need Node 20+. When done, your game runs with its answers on a server instead of exposed in the page or on a low-volume server you vibe coded. A content producer can then edit the setup of the game and create the content. Some key terms defined: | Word | What it means | | --- | --- | | **Round** | One go at your game. A quiz calls it a round, a vote calls it a voting window, a bracket calls it a tournament, and your game picks the word. | | **Play** | One person's attempt at a round. | | **Engine** | The server that holds the answer, counts attempts and decides the result. | | **Producer** | Whoever writes the content once the game is live. Often not you, and often not technical. | | **Format** | Which set of rules the Engine runs for your game. [Game formats](/docs/game-formats) covers the ones that run today. | Where the account sits, because it decides how far you get before you have to stop: * **Onboarding, orienting, inspecting, writing the manifest and rewriting the page need no account at all.** They happen on your own machine. * **`gamestage dev` and `gamestage verify` need you signed in**, and nothing more. They run an Engine locally, so a workspace waiting for approval runs them today. * **`gamestage deploy` and `gamestage promote` need that account approved.** Both ask our service to do something, and the deploy is where the game reaches a fan. Before an account can be approved you accept the [Terms of Service](/terms) yourself, on the approval screen: your agent hands you the address and waits. Your agent does most of the journey. Signing in, reading what it did, and moving a game to prod are yours: the last of those is a human handoff, covered in its own step below. ## Onboard Gamestage ``` npx skills add https://gamestage.ai/skill ``` Points your agent at Gamestage. Nothing is installed globally. The skill is a set of instructions plus the address of the tool, and the tool runs from npm each time you call it. You do not need an account, and nothing leaves your machine. **What your agent does:** picks the skill up when a task looks like taking a prototype to production, and follows it. ## Orient ``` npx gamestage start ``` Reads the current directory and tells you the next thing to do. Run it whenever you are unsure. **What your agent does:** runs this first every session. It has no memory of the last one, and your directory could be at any stage. ## Inspect ``` npx gamestage inspect ``` Reads your game and writes a report: what it is, what it holds, and which parts a player can currently read that they should not be able to. **What your agent does:** works from the report. A prototype is often one big HTML file with all the data inside it, and reading the lot would fill the agent's memory with statistics it does not need. ## Decide what has to move No command here. This step is a judgement. Ask which facts decide the outcome. Anything a player could read off the page and use to win has to move to the Engine. Everything else can stay where it is. **What your agent does:** matches the report against the six [game formats](/docs/game-formats). First it asks whether you need an Engine at all. If your game is a quiz or a straight prediction, Monterosa's platform already holds the answer and decides when to show it, so you can stop here. ## Write the game round ``` npx gamestage create --name "My game" --format push ``` Writes the [App Manifest](/docs/app-manifest), a file called `gamestage.yaml` that says what your game is, which rules it runs and who owns which fact. `--format` is where the format goes, and `push` is one of the six. The name is what a fan reads. Every later command takes the game's **id** instead, which `create` mints as your name plus four random characters and writes to `app.id` in `gamestage.yaml`: "My game" becomes something like `my-game-a3c9`, and yours will end differently. Read it out of the manifest before you deploy, because the title is not accepted in its place. **What your agent does:** fills the manifest from the report. The tool refuses a manifest that contradicts itself, so a bad one cannot reach a deploy. ## Rewrite the page ``` npx gamestage client --out . ``` Writes two files into your game's folder: `gamestage.js`, the Gamestage library, and `gamestage-player.js`, the player client it uses to talk to the Engine. Your page then asks the Engine for the round and sends each play to it, and works nothing out itself. [The player API](/docs/player-api) is the contract between them. **What your agent does:** the largest edit in the journey. It is repetitive work, bounded by a contract that says what the page is allowed to know. ## Sign in ``` npx gamestage login ``` Signs you in, and creates an account if you do not have one. There is no website step first. Everything above this line works without an account: onboarding, inspecting, writing the manifest and rewriting the page are all offline. This is the first step that needs one, because the next two run your game through a real Engine rather than just reading your files. ## Run it ``` npx gamestage dev ``` Serves your game against an Engine on your own machine, now that you are signed in. Nothing about the game goes anywhere else: the round comes from your manifest and the marking is real. **What your agent does:** runs it and plays the game in a browser. A page can return a healthy response and still be blank, because the code that breaks it runs in the browser, so playing it is the only proof. ## Prove it ``` npx gamestage verify ``` A run of checks: the round played here is this game's own with a real limit on attempts, the answers are gone from what a deploy would publish, the page reads every setting a producer can change, the client is present and is the only way in, and a real browser gets its deadline from the server, plays a round through to a result, and notices the connection dropping and returning. Also needs you signed in, for the same reason `dev` does. **What your agent does:** reads each failure and fixes it. They are written in the words of the fix. ## Repair No command. Back to whichever step broke. **What your agent does:** reads the failing check, edits, runs it again, and reports what happened. ## Publish ``` npx gamestage deploy --dir . ``` Uploads the game, sets it up on Monterosa and gives you back a URL. The argument is the `app.id` from your manifest, not the game's name. A deploy publishes a whole folder, so look at what is in yours first. Anything sitting beside your game goes up with it, including files that hold the answers. **What your agent does:** runs the deploy and reads back everything the service says, including anything it refused. ## Move it to prod ``` npx gamestage promote ``` **What your agent does:** nothing. This one is yours. It changes which audience a game is entitled to reach, so an agent hands you the command and its consequence rather than running it. Approves your own game to move from dev to prod. Approving your own game is not a purchase, so this works for any game that exists, is not archived and is not already approved, and there is no queue behind it. Run it again on a game that is already approved and it reports there is nothing to do, rather than approving it a second time. It does not move the game on its own. Prod also needs your workspace on a paid plan, and only Monterosa can move it onto one: no command captures payment and none grants a paid plan on your word. Talk to us, and [Plans and limits](/docs/starter-plan) covers what Publisher and Enterprise are. The command says which of the two states you are in when it finishes. Either your workspace already carries prod, or the game is approved and still counts as dev until we move the workspace, which then takes effect with nothing further for you to run. Your approval is recorded once, so a workspace that moves onto a paid plan later carries its approved games across without being asked again. Serving does not read the approval. A deployed game is reached the same way and plays the same way whichever of the two states it is in, so promoting a game today records the decision rather than changing what a fan meets. Promotion changes no files and mints no version. The game keeps its id, its scores and its leaderboard. ## Free a slot ``` npx gamestage suspend ``` Starter runs one live game at a time. Suspending an old one makes room. [Plans and limits](/docs/starter-plan) has the detail. ## Somebody plays it Send them the URL from the deploy. They install nothing and need no account, and the round comes from the Engine. ## Hand it over Your deploy prints a link to Monterosa Studio, the tool a producer uses. Studio is Monterosa's product and keeps its own name. There they set the game's name, its description, the how-to-play text, the wording on the main button and the colour. Those reach a player on their next visit, and anyone already playing sees them change without reloading. ## They write the next round The producer writes it in Studio and it goes live. Nothing is rebuilt and nobody deploys. The earlier steps exist to make this one possible. ### If none of this fits Not a step, which is why it has no number. It is what to do when the journey stops working for the game you have. ``` npx gamestage suggest "what you were trying to build" --closest group ``` Tells us about a format or a feature that does not exist. No account needed. It prints exactly what it would send and sends nothing until you add `--send`. What it sends is four short pieces of text: never your game, never your manifest, never an answer.