Developer Portal Guide

This public guide is for external game developers. The BodyLink developer portal is the only supported entry to validation, staging, human review, and the production catalog. Developers never receive catalog-write credentials.

If you use a coding agent—or cannot program—start with the External Developer Agent Release Runbook. Paste it unchanged. The agent performs the technical work and shows one exact human action at a time.

Current external release workflow

There are two deliberately separate submissions today:

DIRECT AGENT EVIDENCE
        build + validate + export
          -> one-shot OAuth authorization + exact-digest confirmation
          -> direct agent upload
          -> automated validation
          -> staging evidence
          -> productionEligible=false (cannot be promoted)

        EXTERNAL PRODUCTION
        new higher immutable version
          -> authenticated Portal /submit upload
          -> automated validation
          -> staging launcher
          -> a distinct BodyLink human reviewer plays the game
          -> approve or reject
          -> production catalog verification
        

The direct agent flow proves the exact bytes reached validation/staging. It does not prove production provenance and cannot be upgraded into a production release. Because <slug>@<version> is immutable, the later production submission uses the same slug and a new higher semantic version.

Never describe a direct OAuth upload as production-ready, production-eligible, approved, published, or live. It must report source=agent-upload and productionEligible=false.

1. Account and onboarding

Registration is email + password (at least 12 characters). Enter credentials only in the official Portal browser; never give a password, session cookie, token, or authorization code to an agent or command.

For direct agent submission, the BodyLink platform team currently provisions:

• your account's organization/game membership;
• a public OAuth client ID;
• the organization ID;
• the game ID.

These IDs are not secrets, but the agent must verify them against the onboarding information you received. If any are missing, the agent may finish local tests and export, then must stop with BODYLINK PLATFORM ONBOARDING REQUIRED. It must not invent IDs or ask you to use a database or terminal.

Your account is a submitter account. External developers cannot approve their own production submission. Reviewer authority belongs to designated BodyLink humans.

2. Build, preflight, and size limits

Use the game repository's actual scripts. A typical project runs:

npm install
        npm test
        npm run build
        npm run validate
        npm run export:zip
        npm run release:preflight
        

Proceed only when all applicable gates pass. release:preflight prints a final PREFLIGHT: PASS or PREFLIGHT: FAIL; every ✗ includes a concrete fix. Never upload “to see what happens” after a failed preflight.

The public external lane enforces:

If the ZIP exceeds 50 MiB, reduce assets, rebuild, revalidate, and recompute the digest before OAuth or browser upload. Contact BodyLink when a game cannot fit; do not look for an undocumented submission lane.

3. Freeze the exact artifact

Before authorization, the agent must verify:

• stable slug and a new semantic version in both manifests;
• the exact exported ZIP and PKZIP format;
• exact byte count;
• SHA-256 in 64-character hexadecimal;
• SHA-256 in 43-character unpadded base64url (the Portal display form);
• repository, branch, exact source commit, and worktree state;
• test/build/validation/gameplay results as PASS, FAIL, or honestly SKIPPED.

The agent then shows APPROVE OAUTH RELEASE <slug>@<version>. A blank, vague, misspelled, partial, stale, or different reply is not approval. Approval applies only to the displayed artifact and staging-only effect.

4. One-shot OAuth authorization

The installed BodyLink CLI starts Authorization Code + S256 PKCE. It opens the official Portal in your browser and listens temporarily on a random http://127.0.0.1:<port>/oauth/callback on the same computer.

Security rules:

• Sign in only in the Portal browser. The agent never reads or types credentials.
• Never copy the callback URL, authorization code, token, cookie, or browser storage into chat or a terminal.
• On the consent page, verify the displayed client, organization ID, game ID, device label, release:read/release:submit permissions, expiry, and current loopback callback.
• If any field differs from onboarding evidence, deny and stop.
• Approve only after the agent shows the exact reply AUTHORIZE AGENT <org-id> <game-id>.

The browser briefly reaches the loopback callback and returns control to the CLI. The one-shot credential remains in memory and is revoked/discarded when the command finishes.

5. Exact-digest confirmation

After authorization, the Portal shows a separate “Confirm release upload” page. It must match the frozen candidate's slug, version, exact bytes, and base64url SHA-256, and must say the upload is for validation only—not production.

Approve only after the agent shows:

CONFIRM EXACT RELEASE <slug>@<version> <base64url-digest>
        

Any mismatch means deny and stop. Exact-digest confirmation authorizes only the displayed direct upload; it is not reviewer approval and does not authorize the later production submission.

6. Direct validation/staging evidence

A successful direct result must include:

• a safe submission ID;
• source=agent-upload;
• state validated or staged;
• productionEligible=false;
• the exact artifact digest.

The correct conclusion is:

DIRECT AGENT EVIDENCE COMPLETE — NOT PRODUCTION ELIGIBLE
        

If validation rejects the bundle, read the named public check codes, apply the recommended fixes, create a new version when the prior one was consumed, rebuild, and repeat with a new exact approval. See the Validation Reference.

7. Separate production submission

Only after the direct evidence succeeds should the agent ask whether to prepare production. It must:

1. keep the same slug and create a new higher semantic version;
2. update both manifests together;
3. rerun tests, build, validation, gameplay, and export;
4. compute and display the new exact bytes and SHA-256 values;
5. stop for APPROVE EXTERNAL PRODUCTION <slug>@<new-version>.

After that exact approval, the agent may drive the visible authenticated Portal /submit form. If browser control cannot choose the local file, the only human file action is selecting the exact named ZIP and clicking Upload. Credentials remain browser-only.

The production submission moves through received -> validating -> staged or a fail-closed rejection. Staging is not production.

8. Distinct human review and publish

At staged, a reviewer plays your game in the real staging launcher with the real launcher UX and available camera/tracking. The reviewer—not the developer's agent—approves or rejects it with a separate Portal account.

• External developers cannot approve their own submission.
• The direct-upload digest confirmation is not this decision.
• An optional inline preview is not the review gate; the staged launcher is.
• Every decision records who, when, version, and validation evidence.
• On approval, the immutable version becomes the production pointer and the catalog is rebuilt.

Say LIVE only after the production catalog exposes the exact approved <slug>@<version>. An upload, validation PASS, or staged game is never LIVE.

9. Failures and recovery

10. Evidence the agent returns

The final report should contain repository/branch/commit/worktree state; slug@version; ZIP path/name, exact bytes, SHA-256 hex/base64url; every test/build/ validation/gameplay result; safe authorization/confirmation timestamps; safe submission IDs; source/state/production eligibility; credential cleanup; the production submission and reviewer next step when requested; and exactly one next human action.