{"doc":"journey","title":"The journey","markdown":"# The journey\n\n### Before you start\n\nThis works best if you already made a game and have Claude Code, Codex or\nanother agent and you're in the repo. You'll need Node 20+.\n\nWhen done, your game runs with its answers on a server instead of exposed in\nthe page or on a low-volume server you vibe coded. A content producer can\nthen edit the setup of the game and create the content.\n\nSome key terms defined:\n\n| Word | What it means |\n| --- | --- |\n| **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. |\n| **Play** | One person's attempt at a round. |\n| **Engine** | The server that holds the answer, counts attempts and decides the result. |\n| **Producer** | Whoever writes the content once the game is live. Often not you, and often not technical. |\n| **Format** | Which set of rules the Engine runs for your game. [Game formats](/docs/game-formats) covers the ones that run today. |\n\nWhere the account sits, because it decides how far you get before you have to\nstop:\n\n* **Onboarding, orienting, inspecting, writing the manifest and rewriting the\n  page need no account at all.** They happen on your own machine.\n* **`gamestage dev` and `gamestage verify` need you signed in**, and nothing\n  more. They run an Engine locally, so a workspace waiting for approval runs\n  them today.\n* **`gamestage deploy` and `gamestage promote` need that account approved.**\n  Both ask our service to do something, and the deploy is where the game\n  reaches a fan. Before an account can be approved you accept the\n  [Terms of Service](/terms) yourself, on the approval screen: your agent\n  hands you the address and waits.\n\nYour agent does most of the journey. Signing in, reading what it did, and\nmoving a game to prod are yours: the last of those is a human handoff, covered\nin its own step below.\n\n## Onboard Gamestage\n\n```\nnpx skills add https://gamestage.ai/skill\n```\n\nPoints your agent at Gamestage. Nothing is installed globally. The skill is a\nset of instructions plus the address of the tool, and the tool runs from npm\neach time you call it.\n\nYou do not need an account, and nothing leaves your machine.\n\n**What your agent does:** picks the skill up when a task looks like taking a\nprototype to production, and follows it.\n\n## Orient\n\n```\nnpx gamestage start\n```\n\nReads the current directory and tells you the next thing to do. Run it whenever\nyou are unsure.\n\n**What your agent does:** runs this first every session. It has no memory of the\nlast one, and your directory could be at any stage.\n\n## Inspect\n\n```\nnpx gamestage inspect\n```\n\nReads your game and writes a report: what it is, what it holds, and which parts\na player can currently read that they should not be able to.\n\n**What your agent does:** works from the report. A prototype is often one big\nHTML file with all the data inside it, and reading the lot would fill the\nagent's memory with statistics it does not need.\n\n## Decide what has to move\n\nNo command here. This step is a judgement.\n\nAsk which facts decide the outcome. Anything a player could read off the page\nand use to win has to move to the Engine. Everything else can stay where it is.\n\n**What your agent does:** matches the report against the six [game\nformats](/docs/game-formats). First it asks whether you need an Engine at all.\nIf your game is a quiz or a straight prediction, Monterosa's platform already\nholds the answer and decides when to show it, so you can stop here.\n\n## Write the game round\n\n```\nnpx gamestage create --name \"My game\" --format push\n```\n\nWrites the [App Manifest](/docs/app-manifest), a file called `gamestage.yaml`\nthat says what your game is, which rules it runs and who owns which fact.\n`--format` is where the format goes, and `push` is one of the six.\n\nThe name is what a fan reads. Every later command takes the game's **id**\ninstead, which `create` mints as your name plus four random characters and\nwrites to `app.id` in `gamestage.yaml`: \"My game\" becomes something like\n`my-game-a3c9`, and yours will end differently. Read it out of the manifest\nbefore you deploy, because the title is not accepted in its place.\n\n**What your agent does:** fills the manifest from the report. The tool refuses a\nmanifest that contradicts itself, so a bad one cannot reach a deploy.\n\n## Rewrite the page\n\n```\nnpx gamestage client --out .\n```\n\nWrites two files into your game's folder: `gamestage.js`, the Gamestage\nlibrary, and `gamestage-player.js`, the player client it uses to talk to the\nEngine. Your page then asks the Engine for the round and sends each play to\nit, and works nothing out itself. [The player API](/docs/player-api) is the\ncontract between them.\n\n**What your agent does:** the largest edit in the journey. It is repetitive\nwork, bounded by a contract that says what the page is allowed to know.\n\n## Sign in\n\n```\nnpx gamestage login\n```\n\nSigns you in, and creates an account if you do not have one. There is no website\nstep first.\n\nEverything above this line works without an account: onboarding, inspecting,\nwriting the manifest and rewriting the page are all offline. This is the first\nstep that needs one, because the next two run your game through a real Engine\nrather than just reading your files.\n\n## Run it\n\n```\nnpx gamestage dev\n```\n\nServes your game against an Engine on your own machine, now that you are signed\nin. Nothing about the game goes anywhere else: the round comes from your\nmanifest and the marking is real.\n\n**What your agent does:** runs it and plays the game in a browser. A page can\nreturn a healthy response and still be blank, because the code that breaks it\nruns in the browser, so playing it is the only proof.\n\n## Prove it\n\n```\nnpx gamestage verify\n```\n\nA run of checks: the round played here is this game's own with a real limit on\nattempts, the answers are gone from what a deploy would publish, the page\nreads every setting a producer can change, the client is present and is the\nonly way in, and a real browser gets its deadline from the server, plays a\nround through to a result, and notices the connection dropping and returning.\nAlso needs you signed in, for the same reason `dev` does.\n\n**What your agent does:** reads each failure and fixes it. They are written in\nthe words of the fix.\n\n## Repair\n\nNo command. Back to whichever step broke.\n\n**What your agent does:** reads the failing check, edits, runs it again, and\nreports what happened.\n\n## Publish\n\n```\nnpx gamestage deploy <game-id> --dir .\n```\n\nUploads the game, sets it up on Monterosa and gives you back a URL. The\nargument is the `app.id` from your manifest, not the game's name.\n\nA deploy publishes a whole folder, so look at what is in yours first. Anything\nsitting beside your game goes up with it, including files that hold the answers.\n\n**What your agent does:** runs the deploy and reads back everything the service\nsays, including anything it refused.\n\n## Move it to prod\n\n```\nnpx gamestage promote <game-id>\n```\n\n**What your agent does:** nothing. This one is yours. It changes which\naudience a game is entitled to reach, so an agent hands you the command and\nits consequence rather than running it.\n\nApproves your own game to move from dev to prod. Approving your own game is not\na purchase, so this works for any game that exists, is not archived and is not\nalready approved, and there is no queue behind it. Run it again on a game that\nis already approved and it reports there is nothing to do, rather than\napproving it a second time.\n\nIt does not move the game on its own. Prod also needs your workspace on a paid\nplan, and only Monterosa can move it onto one: no command captures payment and\nnone grants a paid plan on your word. Talk to us, and\n[Plans and limits](/docs/starter-plan) covers what Publisher and Enterprise are.\n\nThe command says which of the two states you are in when it finishes. Either\nyour workspace already carries prod, or the game is approved and still counts as\ndev until we move the workspace, which then takes effect with nothing further\nfor you to run. Your approval is recorded once, so a workspace that moves onto\na paid plan later carries its approved games across without being asked again.\n\nServing does not read the approval. A deployed game is reached the same way\nand plays the same way whichever of the two states it is in, so promoting a\ngame today records the decision rather than changing what a fan meets.\n\nPromotion changes no files and mints no version. The game keeps its id, its\nscores and its leaderboard.\n\n## Free a slot\n\n```\nnpx gamestage suspend <game-id>\n```\n\nStarter runs one live game at a time. Suspending an old one makes room.\n[Plans and limits](/docs/starter-plan) has the detail.\n\n## Somebody plays it\n\nSend them the URL from the deploy. They install nothing and need no account, and\nthe round comes from the Engine.\n\n## Hand it over\n\nYour deploy prints a link to Monterosa Studio, the tool a producer uses. Studio\nis Monterosa's product and keeps its own name.\n\nThere they set the game's name, its description, the how-to-play text, the\nwording on the main button and the colour. Those reach a player on their next\nvisit, and anyone already playing sees them change without reloading.\n\n## They write the next round\n\nThe producer writes it in Studio and it goes live. Nothing is rebuilt and nobody\ndeploys.\n\nThe earlier steps exist to make this one possible.\n\n### If none of this fits\n\nNot a step, which is why it has no number. It is what to do when the journey\nstops working for the game you have.\n\n```\nnpx gamestage suggest \"what you were trying to build\" --closest group\n```\n\nTells us about a format or a feature that does not exist. No account needed. It\nprints exactly what it would send and sends nothing until you add `--send`. What\nit sends is four short pieces of text: never your game, never your manifest,\nnever an answer.\n"}