Join the waitlist

App Manifest reference

The sections, statuses, provenance and server-owned container.

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.0

Validate a local file:

gamestage manifest validate gamestage.yaml
gamestage manifest validate gamestage.yaml --level L2

Metadata

manifest holds metadata about the file rather than a reviewable product section.

FieldTypeMeaning
schema_versionstringManifest language version, currently 1.0
revisionnon-negative integerCreator-controlled revision
conformanceL0 to L5The 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.
  • title and summary: 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 as web-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.system pins your organisation's theme, as theme use writes it.
  • host and layout: where the game opens and how it fills the screen. create writes both; see layout and loading.
  • starter: the organisation starter app the game began from, such as web-embed@1.2.0. create --starter writes 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_driven and dedicated_engine, because inspect uses 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, version and variant: 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 as points_per_second and max_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, identify or custom.
  • jwt: jwks_uri, plus issuer and optional audience, when provider is jwt. Leave out issuer only when your login's tokens carry no iss claim, as F1's do: a token is then trusted because it verifies against your jwks_uri, so any token those keys sign is accepted. With no issuer named, a token that does carry an iss is refused, so name the issuer whenever your tokens carry one. Add player_id_claim when your login puts the player's id somewhere other than sub: F1's tokens, for example, carry it in SubscriberId. A token without that claim is refused. The jwks_uri must 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, method and an optional named verifier. The current gate records a fan’s self-declared age, not a verified age.
  • territory: required and allowed, a list of ISO country codes such as GB. 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 settingTypeWhat it does
Ask fans to confirm their ageUse the game's setting, On or OffOn asks the age question and Off does not, whatever the manifest says. Use the game's setting, the default, follows the manifest.
Minimum agenumberThe age fans self-declare, without verification. Empty uses the manifest's minimum_age, or 18 if there is none.
CountriestextTwo-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 boxestextOne 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 for monterosa, posthog, ga4 or webhook.
  • 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 with gamestage 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 of local, playground, staging, production.

operations

Support and promotion controls.

  • support_tier: stored plan key, one of runtime, live or enterprise.
  • 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
CheckSuggestedRun it with
accessibilityA WCAG 2.2 audit skillnpx skills add addyosmani/web-quality-skills@accessibility
securitySentry's security review skillnpx skills add getsentry/skills@security-review
secretsThe gitleaks scannergitleaks detect --source .
privacyA GDPR skillnpx skills add wshobson/agents@gdpr-data-handling

Each check you record takes these fields:

FieldTypeRequiredWhat it holds
toolstringyesThe skill or tool that ran
ran_atdate, YYYY-MM-DDyesThe day it ran
resultpassed, issues_fixed or issues_openyesWhat it found, after any fixes
ownerstringnoThe person answerable for the result
evidencestringnoA link or repo path to the report
notestringnoAnything 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

KeyTypeDefaultWhat it does
liveobjectabsentPresent means the game follows a real contest as it happens. See live data.
round_fieldsobjectabsentWhich 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_enabledbooleanfalseOffers a fan the "Tell me my result" sign-up.
notify_channelsarray 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

StatusMeaning
missingThe section does not exist yet. This is normal until it is needed.
proposedAn agent wrote it and nothing has tested it.
confirmedChecked and it holds.
verifiedProved by evidence rather than inspection.
approvedA 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.

KindRequired fieldsUse
human_decisionowner, dateA person made the decision
generated_proposaltoolAn agent or tool proposed it
repository_evidencefileSource code or repository state supports it
platform_evidencesystem, idA platform record exists
external_evidencesupplierA 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.

LevelBuild stage
L0Concept
L1Experience built
L2Wired to the platform
L3Ready to deploy
L4Production ready
L5Operating 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: jwt needs 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. deploy and status say 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, verify and review read it; deploy never uploads the practice/ folder. gamestage round push <game> copies it into Studio.