{"doc":"organisation","title":"Your organisation's context and starter apps","markdown":"# Your organisation's context and starter apps\n\nTell every agent in your organisation how a game fits your app, once. You write\none Markdown file, `integration.md`, and publish it for your organisation. Each\nagent reads it before it builds, and `gamestage create` copies it into every\nnew game's folder.\n\nFor what must hold in every game, publish a starter app as well: a working app\nin your own stack, with your SDK version, analytics and libraries already in\nit. `gamestage create --starter` starts each new game from it. See\n[start games from your own app](#start-games-from-your-own-app).\n\n```\n$ gamestage org context set integration.md\nSet your organisation's integration context: revision 1, set by sam@harbour-example.com on 2026-10-20.\nEvery member's agent reads it from now on, and `gamestage create` copies it into each new game's folder.\n\n$ gamestage org context --save\nSaved your organisation's integration context, revision 1, set by sam@harbour-example.com on 2026-10-20, to /Users/alex/games/integration.md.\n```\n\nThe file is private to your organisation. Only signed-in members can read it, a\ndeploy never publishes it, and nobody outside your organisation can see it.\n\n## See what your organisation has set up\n\nOpen **Organisation** in [Stage](https://gamestage.ai/stage/organisation). It\nshows the integration context in force, with who set it and when, each starter\napp with its versions and framework, each theme, and your organisation's\nadmins, so you know whom to ask for a change. Stage only reads them: an admin\nchanges them with the commands on this page.\n\n## Write the file\n\nSay what an agent needs to know to build a game that drops into your app: the\nSDK version your app embeds, how sign-in reaches the game, which analytics and\nconsent tools you use, the libraries you prefer, and where your own code and\ndocs are. Plain Markdown, with code samples and links where they help.\n\nHere is a short example for Harbour Sports, an invented company:\n\n````markdown\n# Harbour Sports: how a game fits our app\n\n## Where games run\nGames open in the Harbour app's web view on iOS and Android, and in an iframe\non harbour-example.com. Design for a 390 px wide screen first.\n\n## Sign-in\nThe app is already signed in. It sends the fan's token to the game with\n`postMessage({ type: \"harbour:auth\", token })`. Never show a sign-in screen.\n\n## Monterosa SDK\nOur app embeds Monterosa SDK v1. Use the same major version in the game.\n\n## Analytics and consent\nUse PostHog, project key in the game's settings, never in code. Consent comes\nfrom OneTrust in the host app; read it with `window.HarbourConsent.get()`.\n\n## Libraries\nReact 19 and Tailwind. No jQuery. Our components:\nhttps://design.harbour-example.com\n````\n\nKeep secrets out of it. Every member of your organisation, and every agent\nthey run, reads this file. Say where a key is kept, never the key itself.\n\n## Publish it\n\nOnly an organisation admin can publish: see\n[who can change the context and starters](#who-can-change-the-context-and-starters).\nRun this in the folder with the file:\n\n```\ngamestage org context set integration.md\n```\n\nEach publish is a new revision, numbered from 1. The newest revision is the one\nin force, and earlier ones are kept, so you can see who changed it and when.\nThere is nothing to choose: to change it, edit the file and publish again.\n\n## Read it\n\nAny member of your organisation can read it, including an account still\nwaiting for approval.\n\n```\ngamestage org context                 print it\ngamestage org context --save          write it to integration.md here\ngamestage org context --save notes.md write it to a path of your choice\ngamestage org context history         every revision, newest first\n```\n\n`gamestage create` writes `integration.md` into a new game's folder when your\norganisation has one, and says so in one line. If there is already an\n`integration.md` there, `create` keeps it unless you pass `--force`. Signed out\nor offline, `create` skips it and makes the game as usual.\n\n## Who can change the context and starters\n\nAn organisation admin publishes the integration context, starter apps and\nthemes. Everyone else in your organisation reads them. Every person who signs up owns\na workspace of their own, so owning one, or having an email address at your\norganisation's domain, lets you read your organisation's files but not change\nthem.\n\n### Get an organisation admin\n\nMonterosa makes a workspace an admin for your organisation. Email us the\naddress each person who should publish signs in with, and we add them. Once\nthey are added, `org context set`, `org starter publish` and `theme publish`\nwork for them on their next command, with nothing to install or sign in again.\n\nSomeone whose email address is not at your organisation's domain, such as an\nagency working for you, can be an admin too. We first put their workspace in\nyour organisation, then make it an admin.\n\nA workspace belongs to one organisation, and is an admin for that one only.\nSomeone already in another organisation, through their email address or\nbecause we put them there, cannot be made an admin of yours from the same\nworkspace, because they could then change neither organisation's files. They\nsign in with a separate account for your organisation instead.\n\nTo stop someone publishing, ask us and we remove the admin grant. They keep\nreading your organisation's files for as long as their workspace belongs to it.\n\n| Who | Read the context, starters and themes | Change them |\n| --- | --- | --- |\n| Anyone whose workspace belongs to your organisation, once approved | Yes | No |\n| An account waiting for approval | The context and starters from the command line, not themes or Stage | No |\n| An account that was turned down | Nothing | No |\n| An organisation admin | Yes | Yes, once the account is approved |\n| A member of somebody else's workspace | Yes | No |\n| A workspace in no organisation | Its own files only | Its own files only |\n\n## Commands\n\n| Command | Who can run it | What it does |\n| --- | --- | --- |\n| `org context` | Any member | Prints the revision in force, or one line saying there is none. |\n| `org context --save [path]` | Any member | Writes it to `path`, by default `integration.md`. Writes nothing when there is none. |\n| `org context set <file>` | Organisation admin | Publishes the file as a new revision. |\n| `org context history` | Any member | Lists every revision: number, who set it, date and size. |\n\nEach command takes `--json`. `org context` answers `{ \"ok\": true, \"context\": null }`\nwhen there is none, and otherwise `context` holds the fields below.\n\n| Field | Type | What it is |\n| --- | --- | --- |\n| `markdown` | string | The file, exactly as published. |\n| `revision` | number | Counts up from 1 with each publish. |\n| `setBy` | string | The email address of the admin who published it. |\n| `setAt` | string | When, as an ISO 8601 date and time. |\n| `bytes` | number | Its size in UTF-8 bytes. |\n\n## Rules for the file\n\n| Rule | Limit |\n| --- | --- |\n| Format | Markdown, saved as UTF-8 text. |\n| Size | Up to 50 KB. |\n| Content | Not empty, and no line that looks like a secret. |\n| Visibility | Members of your organisation only. Never cached by a shared cache, never published by a deploy. |\n\nYour organisation is decided by your workspace: by the owner's email domain,\nor by Monterosa granting the workspace to your organisation. Workspaces in one\norganisation share one file. A workspace in no organisation keeps its own.\n\n## When it fails\n\n| What you see | What happened | What to do |\n| --- | --- | --- |\n| `Your organisation has no integration context yet.` | Nobody has published one. | Ask an organisation admin to run `gamestage org context set integration.md`. |\n| `Only an organisation admin can change Harbour Sports' integration context.` | Your workspace belongs to the organisation but is not one of its admins. | Ask Monterosa to make your workspace an admin, or send the file to an admin to publish. |\n| `Only the workspace's owner can set the organisation's integration context.` | You are a member of the workspace, not its owner. | Send the file to the owner to publish. |\n| `Not set. The file looks like it contains a secret` | A line looks like a private key, an API key, an AWS key, a password or a long access token. The line number is named; the value is not repeated. | Take the value out, say where it is kept instead, and publish again. Nothing was uploaded. |\n| `The file is 61 KB, and the limit is 50 KB.` | The file is too long for an agent to read before it builds. | Cut it to what an agent needs, and link to longer documents. |\n| `The file is not UTF-8 text.` | It was saved in another encoding, or is not text. | Save it as plain Markdown in UTF-8. |\n| A message that your account is waiting for approval | You tried to publish before Monterosa approved the account. | Read it now; publish once the account is approved. |\n| `Somebody else in your organisation set the integration context at the same moment.` | Two admins published at once. Both revisions are kept. | Run `gamestage org context` to read theirs, then publish yours again if it still applies. |\n\n## How an agent uses it\n\nThe Gamestage skill tells an agent to read the context before it builds. Where\nthe context and the skill disagree about how the game fits your app, the\ncontext wins. On what Gamestage requires, the skill wins: the Engine owns the\nanswers, every game asks fans for consent, and `gamestage verify` must pass.\n\nThe file is advice for the agent, and an agent can follow advice imperfectly.\nAnything that must hold in every game belongs in the game's manifest, where\n`gamestage verify` checks it.\n\n## Start games from your own app\n\nA starter app is a folder holding a working app in your organisation's stack.\nAn organisation admin publishes it once; everyone in the organisation then starts games from it,\nso your SDK version, sign-in, analytics and libraries are in the code from the\nfirst line, not left to an agent's reading.\n\n```\n$ gamestage org starter publish ./web-embed\nPublished web-embed@1.0.0 (vite-react) for everyone in your organisation. Every check passed.\n  Files      14, 38 KB zipped\n  Left out   .env.local, node_modules/\n\n$ gamestage create --name \"Cup Final Predictor\" --format predict\n  Started from web-embed@1.0.0, your organisation's starter app (vite-react), because it is the only one. Pass --no-starter to start without it.\n  It needs building: run npm run build, then deploy dist with gamestage deploy --dir dist.\n```\n\n### Describe the starter\n\nPut a `gamestage-starter.json` at the root of the folder:\n\n```json\n{\n  \"name\": \"web-embed\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Harbour Sports web embed: React, PostHog, Monterosa SDK v1\",\n  \"framework\": \"vite-react\",\n  \"build\": \"npm run build\",\n  \"out\": \"dist\"\n}\n```\n\n| Field | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `name` | string | Required | 3 to 40 lowercase letters and numbers, with single hyphens between them. |\n| `version` | string | Required | Three numbers, such as `1.0.0`. A published version never changes; raise it to publish again. |\n| `description` | string | Required | One line for the people choosing a starter, up to 280 characters. |\n| `framework` | string | Required | A word for people, such as `vite-react` or `vanilla`, up to 40 characters. |\n| `build` | string | Optional | The command that builds the app. Needed when the page loads source code, such as `/src/main.tsx`. |\n| `out` | string | With `build` | The folder the build writes. A game made from the starter deploys this folder. |\n\nThe folder also needs what every Gamestage game needs, because the starter is\nchecked against the same rules: an `index.html`, the Gamestage client, and a\n`gamestage.settings.json` naming who asks for consent:\n\n```json\n{\n  \"consent_brand_name\": \"Harbour Sports\",\n  \"privacy_policy_url\": \"https://harbour-example.com/privacy\"\n}\n```\n\n### Publish it\n\nOnly an organisation admin can publish. `org starter publish` zips the folder and\nuploads it, leaving out what a deploy leaves out: `gamestage.yaml`, the\npractice round, `.env` files, `integration.md`, source maps, `node_modules`,\n`.git` and editor folders. It keeps `gamestage.settings.json`, `package.json`,\nthe lockfile and the README, which a game made from it needs.\n\nGamestage then checks the upload on its servers. A starter that fails any check\nis refused, the answer names every check that failed, and nobody can list or\nuse it. Fix each one and publish again.\n\n| Check | What passes |\n| --- | --- |\n| `gamestage-starter.json` | Present, valid, and naming the version being published. |\n| `index.html` | At the root, or in the `out` folder. A page that loads source code needs `build` and `out`. |\n| Gamestage client | The app loads `gamestage.js` or imports `@monterosa/gamestage`, and leaves the consent banner on. |\n| Consent settings | `gamestage.settings.json` has `consent_brand_name` and an https `privacy_policy_url`. |\n| Monterosa branding | No setting names Monterosa as the brand or links Monterosa's privacy policy. |\n| No `.env` files | No file named `.env` or `.env.*` anywhere in it. |\n| No secrets | No line that looks like a key, a token or a password. |\n| Size and paths | Up to 25 MB zipped, 2,000 files and 100 MB unpacked. No symbolic links, and no path that leaves the folder. |\n\n### Start a game from one\n\n```\ngamestage org starter list                          every starter, newest version first\ngamestage create --starter web-embed                its newest version\ngamestage create --starter web-embed@1.0.0          that exact version\ngamestage create --no-starter                       the format's own page instead\n```\n\nAny member can list starters and create from them, including an account still\nwaiting for approval. Without `--starter`:\n\n| Your organisation has | What `create` does |\n| --- | --- |\n| No starters | What it always did. |\n| One starter | Uses it, and says so. |\n| Several | Asks you to choose when you run it by hand. An agent, a pipeline or `--json` is told their names and stopped, with nothing written. |\n\n`create` unpacks the starter into the game's folder, then adds what every game\ngets: the game's id and manifest, `practice/round.yaml`, the Gamestage client\nfiles the starter lacks, `integration.md`, and your organisation's sign-in and\nconsent defaults. It pins the starter in `gamestage.yaml`:\n\n```yaml\nexperience:\n  starter: web-embed@1.0.0\n```\n\nA new starter version changes no existing game. `--brand` and `--privacy-url`\nstill replace the starter's consent settings for this game.\n\n### When publishing or creating fails\n\n| What you see | What happened | What to do |\n| --- | --- | --- |\n| `The starter was refused, so nobody can create a game from it.` | One or more checks failed. Each is named, with what to change. | Fix each one and publish again. |\n| `web-embed@1.0.0 is already published, and a published version never changes.` | That version exists. | Raise `version` in `gamestage-starter.json` and publish again. |\n| `Only an organisation admin can publish Harbour Sports' starter apps.` | Your workspace belongs to the organisation but is not one of its admins. | Ask Monterosa to make your workspace an admin, or send the folder to an admin to publish. |\n| `Only the workspace's owner can publish the organisation's starter apps.` | You are a member, not the owner. | Send the folder to the owner to publish. |\n| `The zip is 31.2 MB, and the limit is 25 MB.` | The folder holds too much. | Leave out build output and large media. |\n| `Your organisation has 2 starter apps, so create needs to know which one this game starts from.` | `create` ran without a terminal and could not ask. | Run it again with `--starter <name>` or `--no-starter`. |\n| `Your organisation has no starter web-embed.` | The name or version is wrong. | Run `gamestage org starter list`. |\n"}