The App Manifest is gamestage.yaml: one file describing the whole game. It is not an App Spec and it is not a general configuration file.
Fetch the machine-readable contract:
curl https://gamestage.ai/schemas/app-manifest/1.0Validate a local file:
gamestage manifest validate gamestage.yaml
gamestage manifest validate gamestage.yaml --level L2Metadata
manifest holds metadata about the file rather than a reviewable product section.
| Field | Type | Meaning |
|---|---|---|
schema_version | string | Manifest language version, currently 1.0 |
revision | non-negative integer | Creator-controlled revision |
conformance | L0 to L5 | The level the author claims; validation computes the evidenced level and refuses a claim above it |
Sections
The ten sections below carry their own status and provenance.
app
Identity and ownership of the game.
id: stable game id, also used as the Engine tenant and URL key.titleandsummary: creator-facing name and optional description.source: canonical repository URL and branch. This is distinct from repository evidence attached to one value.owners: optional IP, delivery and platform owners.
experience
The fan-facing shape.
surfaces: places the game renders, such asweb-embed.container_label: what this game calls one go, such as Round, Voting window or Tournament. Defaults to Round.screen_graph: optional path to the experience's screen graph.design: optional Figma file, version, token reference and design build stage.design.systempins your organisation's theme, astheme usewrites it.hostandlayout: where the game opens and how it fills the screen.createwrites both; see layout and loading.starter: the organisation starter app the game began from, such asweb-embed@1.2.0.create --starterwrites it as a record; a new starter app version changes no game. See starter apps.
backend
The authority model.
route:managed_runtime. Every game runs on our Engine, so this is the only value a manifest can carry. The schema still names three others,bring_your_own,manifest_drivenanddedicated_engine, becauseinspectuses them to describe a game it found before you migrate it. A manifest that declares one is refused, and the refusal says which value to use.archetype: the declared rule set.component,versionandvariant: the pinned Proxima implementation where known.configuration: additional component configuration.round: the current Preview container specification. See Game formats.arcade: an Arcade game's score limits, such aspoints_per_secondandmax_run_seconds, all optional. See Arcade.
studio_app
The registered Monterosa Studio App Spec: spec_url and version.
studio_surface
The operator surface: family, version and configuration_schema. Gamestage has no content editor. Paid content operations belong in Monterosa Studio.
interaction_cloud
The platform mapping: project_template, project_id, events and elements. A game maps to a project, an edition maps to an event and a container maps to an element.
The pairing ids are stored end to end: a deploy writes platformProject, platformEvent and platformElement back onto the game record, and the next deploy reads them rather than searching by name (GS-259). Do not mark this section verified because provisioning returned ids once: verify that a second deploy found the same project rather than creating another.
identity
Player identity and consent policy.
provider:anonymous,jwt,identifyorcustom.jwt:jwks_uri, plusissuerand optionalaudience, when provider isjwt. Leave outissueronly when your login's tokens carry noissclaim, as F1's do: a token is then trusted because it verifies against yourjwks_uri, so any token those keys sign is accepted. With noissuernamed, a token that does carry anissis refused, so name the issuer whenever your tokens carry one. Addplayer_id_claimwhen your login puts the player's id somewhere other thansub: F1's tokens, for example, carry it inSubscriberId. A token without that claim is refused. Thejwks_urimust be a public https URL with no username or password in it: Gamestage refuses a private, loopback or reserved address, whether written in the URL or reached through DNS, and refuses a redirect or a key set larger than 64 KB.require_authenticated_writes: whether production writes require an identified player.age_gate:required,minimum_age,methodand an optional named verifier. The current gate records a fan’s self-declared age, not a verified age.territory:requiredandallowed, a list of ISO country codes such asGB. Territory is self-declared by the fan, not verified.gate_note: one line the gate shows above its boxes, such as "This is a development version."
With age_gate (self-declared) or territory on, the Gamestage client asks before play. A fan ticks "I'm 16 or over" and "I'm in the United Kingdom", then presses Continue. gamestage.start() does not hand the game back until they have, and the answer is remembered on the device, so a fan is asked once. Change the age or the countries and every fan is asked again. Gamestage does not check either declaration: it records what the fan said. gamestage verify passes the gate the way a fan does and fails if the page never draws it.
identity:
age_gate: { required: true, minimum_age: 16 }
territory: { required: true, allowed: [GB] }
gate_note: This is a development version.The manifest's gate is your default. The organisation running the game can switch it on, switch it off or change it in Studio, under Who can play in the project's settings, without you redeploying:
| Studio setting | Type | What it does |
|---|---|---|
| Ask fans to confirm their age | Use the game's setting, On or Off | On asks the age question and Off does not, whatever the manifest says. Use the game's setting, the default, follows the manifest. |
| Minimum age | number | The age fans self-declare, without verification. Empty uses the manifest's minimum_age, or 18 if there is none. |
| Countries | text | Two-letter country codes separated by commas, such as GB,IE. Fans self-declare their territory; it is not verified. Empty asks nothing about where fans are. |
| Note above the boxes | text | One line shown above the boxes. Empty shows none. |
Your deploy fills these in from the manifest, once. After that the Studio values win, and a later change to the manifest's gate does not overwrite them: the deploy says which settings Studio holds differently from your files. A game whose manifest declares no gate starts with the section empty, which means the manifest decides. The page and the Engine read the same settings, so the Engine checks the recorded declarations, not the fan’s actual age or location. A change in Studio reaches the Engine with the next round it provisions, and a fan who answered the old gate is asked again.
consent: whether analytics needs consent and which provider owns the choice.
Gamestage issues signed anonymous sessions. It does not provide a login system for identified fans at any plan. A game that needs identity names its own JWT issuer and public key set.
The JWT validator exercises that contract. The deployed Engine validates a presented token against the issuer and JWKS configured on that deployment; a deployment with neither set still refuses every token rather than trusting one. create and inspect also still propose identity.provider: identify; review that generated value rather than treating it as a product default. Use jwt only after a person has confirmed the external issuer and keys.
measurement
Declared event routing.
destinations: ordered declarations formonterosa,posthog,ga4orwebhook.trusted_events: events emitted after an Engine commit.signal: optional Fantenna Signal declaration and public identifiers. Whether a game collects Signal is decided by the workspace, not by this field: it needs a Publisher or Enterprise plan and the workspace's Signal switch turned on, on Stage's Analytics page or withgamestage workspace signal on. Starter never collects.
Keys and tokens never belong in the manifest. The schema accepting a destination is not evidence that a production service has provisioned it. The launch plan records that production ingestion and Studio visibility are still dependencies, so a declared destination alone is not proof that analytics is flowing.
deployment
Hosting and environments.
hosting: named host or strategy.space_spec: Proxima space specification when one exists.environments: any oflocal,playground,staging,production.
operations
Support and promotion controls.
support_tier: stored plan key, one ofruntime,liveorenterprise.runbook: operator runbook reference.promotion: whether the game offers a prize, its terms, jurisdictions, free entry route and skill position.
The stored plan keys are not creator-facing labels. Surfaces show Starter, Publisher and Enterprise.
assurance
Record the accessibility, security, secrets and privacy checks you ran on your game. Gamestage suggests a check for each and shows your record on the game's page in Stage. It does not run them, and it does not certify the result: the record is yours. Nothing here affects verify, deploy or the build stage.
assurance:
accessibility:
tool: addyosmani/web-quality-skills@accessibility
ran_at: 2026-09-28
result: issues_fixed
owner: Jo Bloggs
evidence: reports/accessibility-2026-09-28.md
secrets:
tool: gitleaks
ran_at: 2026-09-28
result: passed| Check | Suggested | Run it with |
|---|---|---|
accessibility | A WCAG 2.2 audit skill | npx skills add addyosmani/web-quality-skills@accessibility |
security | Sentry's security review skill | npx skills add getsentry/skills@security-review |
secrets | The gitleaks scanner | gitleaks detect --source . |
privacy | A GDPR skill | npx skills add wshobson/agents@gdpr-data-handling |
Each check you record takes these fields:
| Field | Type | Required | What it holds |
|---|---|---|---|
tool | string | yes | The skill or tool that ran |
ran_at | date, YYYY-MM-DD | yes | The day it ran |
result | passed, issues_fixed or issues_open | yes | What it found, after any fixes |
owner | string | no | The person answerable for the result |
evidence | string | no | A link or repo path to the report |
note | string | no | Anything a reviewer should know |
A check with no ran_at, a date in another format or an unknown result is not counted: verify names the field to fix and Stage shows it as not counted. It never makes the manifest invalid, so a typo here cannot stop a deploy. A check you have not run is left out, and verify suggests it after its verdict.
Other top-level keys
| Key | Type | Default | What it does |
|---|---|---|---|
live | object | absent | Present means the game follows a real contest as it happens. See live data. |
round_fields | object | absent | Which round fields a producer gets in Studio, in order, with their labels, help and tab: a field left out of fields is not offered. A section on the block is the tab for every round field, the optional boxes the page earns included. omit names optional boxes the page earns but does not use, such as place_card_tags on a place game that deals but never groups its cards. Only a place game can use omit for now. words gives an optional box this game's own label and help, and the fields inside its list theirs, as fields does for a round field: { key: place_deal_boxes, label: Number of tiles }. A key the format does not offer optionally, or one also in omit, is refused. Studio text, never fan copy. |
notify_enabled | boolean | false | Offers a fan the "Tell me my result" sign-up. |
notify_channels | array of email, sms, rcs | ["email"] | The ways that sign-up may reach a fan. At least one. |
Beside the manifest: gamestage.settings.json
The manifest describes the game and carries no content. The words and colours a fan sees by default go in gamestage.settings.json next to it, keyed by the Studio field keys: display_name, strapline, how_to_play, the button labels, primary_colour and the css_variables_* palette.
{
"display_name": "Wages",
"how_to_play": "Pick one player from each line. Stay under the cap.",
"play_button_label": "Select Player"
}A deploy writes each value into the game's Studio project where that field is empty, and never over a producer's edit. manifest validate and deploy refuse a key Studio does not have and list the ones it does. The file is never published with the game.
A game's own words and checkboxes go here too. A label_<key> the page names gets a text box under Wording, and an option_<key> the page names gets a checkbox under Options. An option's value is true or false, never text:
{
"display_name": "Box Box Bingo",
"label_deal_button": "Deal",
"option_game_feel": true
}The page must name each key in full, as "option_game_feel", so a deploy can find it. A key the page never names, or an option that is not true or false, is refused.
A data capture form works the other way round. A form_<key> the page names in quotes, such as "form_data_capture", and also reads as forms.<key> or forms["<key>"], gets a dropdown under Forms listing the forms built in the project's Forms extension, and the game's project is given the forms service. The producer picks the form in Studio, so a form_ key never goes in gamestage.settings.json: a form's id differs in every environment. The choice reaches the page as presentation.forms.data_capture, holding the form's id and the host a fan's browser loads it from (GET {host}/form/{id}.json) and sends it to (POST {host}/submit/{id}). With no form picked, forms is absent and the page shows no form.
Under gamestage dev there is no Studio to pick a form in, so a page under development fakes the pick in the same shape, on the presentation global: window.GAMESTAGE_PRESENTATION.forms = { data_capture: { id: "3862", host: "https://forms.example.com" } }. Without it, forms is always absent locally.
Status
| Status | Meaning |
|---|---|
missing | The section does not exist yet. This is normal until it is needed. |
proposed | An agent wrote it and nothing has tested it. |
confirmed | Checked and it holds. |
verified | Proved by evidence rather than inspection. |
approved | A person signed it off. |
An inferred value is proposed. An agent must not turn its own inference into a human decision.
Provenance
Each section carries a list showing where its values came from.
| Kind | Required fields | Use |
|---|---|---|
human_decision | owner, date | A person made the decision |
generated_proposal | tool | An agent or tool proposed it |
repository_evidence | file | Source code or repository state supports it |
platform_evidence | system, id | A platform record exists |
external_evidence | supplier | A supplier, licence or dataset supports it |
Optional detail includes notes, commits, packages, model names, source context, licences and dataset versions.
Build stages
The CLI works out the highest stage supported by the evidence. Setting conformance above that stage is a validation error.
| Level | Build stage |
|---|---|
| L0 | Concept |
| L1 | Experience built |
| L2 | Wired to the platform |
| L3 | Ready to deploy |
| L4 | Production ready |
| L5 | Operating live |
Never use the L number alone in creator-facing output.
Cross-section rules
Structural JSON Schema validation is necessary but does not cover every rule. The CLI also checks:
- Signal and consent: Signal cannot be enabled while analytics consent is disabled.
- Prize declarations: a prize needs terms, jurisdictions and either a free entry route or a declared skill basis.
- JWT identity:
provider: jwtneeds a JWKS URI, and an issuer when its tokens carry one. Deployed URLs must use HTTPS and cannot point at loopback. - Age gates: a required gate needs a minimum age, and a verified method needs a named verifier in the schema. The current fan gate still records self-declared age and territory; it does not verify them.
- Container integrity: each built game format has reachability, uniqueness and ordering checks described in the game formats guide.
Where a round's content comes from
Not from the manifest. gamestage.yaml describes the game and holds no round: every command refuses one that does, with "Rounds don't go in gamestage.yaml. Put practice rounds in practice/round.yaml, and real ones in Studio."
- The game fans play reads its rounds from Studio, where a producer writes and changes them without a deploy.
deployandstatussay which in one line: "Round: Studio, edition <name>" with the link, or "No round yet: add one in Studio". - Your own machine plays
practice/round.yaml, beside the manifest.dev,verifyandreviewread it;deploynever uploads thepractice/folder.gamestage round push <game>copies it into Studio.