@blazium-games/skills 0.1.0

package/skills/blazium-games-get-started/references/auth.md

@@ -0,0 +1,54 @@
+# Authentication
+
+The server at `https://mcp.blazium.games/mcp` accepts OAuth 2.1 access tokens or MCP API keys, both sent as `Authorization: Bearer <token>`.
+
+## OAuth (recommended)
+
+- Discovery: `https://mcp.blazium.games/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server` (player server: the same paths ending in `/player`)
+- PKCE `S256` (verifier 43-128 characters), dynamic client registration, and client ID metadata documents are supported
+- Scopes: `mcp:read`, `mcp:write`, and the narrower `mcp:catalog.write`, `mcp:build.write`, `mcp:crash.read`, `mcp:analytics.read`, `mcp:keys.manage`, `mcp:money`
+- Access tokens last 1 hour. Refresh tokens rotate on every use, so the client renews silently, but the sign-in still ends 30 days after it started
+- Each refresh token works once. Reusing a spent one revokes the whole sign-in; the user then reconnects
+- Details: https://docs.blazium.games/docs/mcp/oauth
+
+On the consent page the user picks:
+
+| Choice | Effect |
+|--------|--------|
+| Account | All games the user owns or admins, plus account tools |
+| Single project | Only that game. Account tools (`get_profile`, `get_setup`, `list_mcp_keys`, `request_mcp_key`, `create_game`, `get_account`, approvals, payments, `blazium-games://me`) and other games return `403` code `4030` |
+| Preset | **Store page**, **CI**, **Crash triage**, **Keys**, **Money**, or **Full access**. A tool outside the preset returns `4073` |
+| Read-only access | Only `mcp:read` is granted. Any write returns `403` code `4031` "This token is read-only" |
+
+Revoke grants at https://blazium.games/settings/mcp.
+
+## API keys
+
+For headless agents and CI:
+
+1. Create a key at https://blazium.games/settings/mcp, or call `request_mcp_key` from an existing account session.
+2. Configure the client:
+
+```json
+{
+  "mcpServers": {
+    "blazium-games": {
+      "type": "http",
+      "url": "https://mcp.blazium.games/mcp",
+      "headers": { "Authorization": "Bearer bgames_mcp_YOUR_KEY" }
+    }
+  }
+}
+```
+
+Keys start with `bgames_mcp_`. Issuing a new account key invalidates every previous account key. The owner and each admin can also create their own project key bound to one game from that game's MCP tab. Player keys start with `bgames_play_` and only work on `https://mcp.blazium.games/player`.
+
+## Rules for agents
+
+- Never print a full key or secret after the user has stored it. Refer to prefixes only.
+- Never commit keys. Store them in CI secrets or a local `.env` that is gitignored.
+- Rotating is destructive: warn before calling `request_mcp_key` or `request_deploy_key`.
+
+## Server card
+
+`https://mcp.blazium.games/.well-known/mcp/server-card.json` lists every tool, prompt, and resource the server currently exposes.

package/skills/blazium-games-get-started/references/prompts.md

@@ -0,0 +1,18 @@
+# Blazium Games MCP prompts
+
+| Prompt | Arguments | Purpose |
+|--------|-----------|---------|
+| `draft_game_page` | `pitch` (required) | Draft a name, one-line tagline, and two-paragraph description from a short pitch |
+| `improve_game_copy` | `description` (required) | Rewrite an existing store description while keeping the facts |
+| `analytics_summary` | `uid` (required) | Summarize the week's visitors using `get_game_analytics` |
+| `bootstrap_game` | `pitch`, `uid` (both optional) | Create or find a store page, read deploy info and builds, and issue rotated deploy keys so an agent can ship from CI |
+
+## `bootstrap_game` steps
+
+1. `get_setup`
+2. `create_game` from the pitch with `draft` visibility if no matching game exists
+3. `get_deploy_info`
+4. `list_game_builds` for existing `build_id` values
+5. `request_deploy_key` (invalidates previous upload keys; returns `X-Access-Token` and `X-Secret-Key` once)
+6. After `POST /api/v1/tool/upload/build`, store the returned `build_id` as `BLAZIUM_GAMES_BUILD_ID` and send it as `X-Build-Id` from crash reporters
+7. Print env var names and URLs. Do not echo secrets after the user has stored them

package/skills/blazium-games-get-started/references/resources.md

@@ -0,0 +1,33 @@
+# Blazium Games MCP resources
+
+JSON resources return JSON. `{uid}` accepts a game uid or vanity name. `ui://` resources return HTML for hosts that support MCP Apps.
+
+## Resources
+
+| URI | Name | Contents |
+|-----|------|----------|
+| `blazium-games://me` | `me` | Authenticated user (account tokens only) |
+| `blazium-games://games` | `games` | Games list |
+| `blazium-games://wallet` | `wallet` | Stored balance and payment rules (account tokens only). **Deprecated**: removed from this server after 2026-10-28; use the player server |
+| `blazium-games://library` | `library` | Owned games and licenses (account tokens only). **Deprecated**: removed from this server after 2026-10-28; use the player server |
+| `ui://blazium-games/account.html` | `account` | Account status, with links to finish sign-in on the website. MIME `text/html;profile=mcp-app` |
+| `ui://blazium-games/approval.html` | `approval` | Approval status, confirm link, and the emailed code |
+| `ui://blazium-games/dev-game.html` | `dev-game` | Store pages this account can edit |
+| `ui://blazium-games/analytics.html` | `analytics` | Visitor analytics |
+| `ui://blazium-games/sales.html` | `sales` | Sales, and a price form that saves when the human clicks |
+| `ui://blazium-games/crashes.html` | `crashes` | Crash reports and a private download link |
+| `ui://blazium-games/checkout.html` | `checkout` | Quote, buy, and donate. **Deprecated** after 2026-10-28 |
+| `ui://blazium-games/wallet.html` | `wallet` | Balance and a card top-up link. **Deprecated** after 2026-10-28 |
+| `ui://blazium-games/library.html` | `library` | Owned games and download links. **Deprecated** after 2026-10-28 |
+
+A host that supports MCP Apps renders a `ui://` resource beside the tool result. The human confirms a price change in the view. Card payment happens on the Checkout link. Key-issuing tools, payout setup, and cash-out stay text-only.
+
+## Resource templates
+
+| URI template | Name | Contents |
+|--------------|------|----------|
+| `blazium-games://games/{uid}` | `game` | One game page |
+| `blazium-games://games/{uid}/analytics` | `game-analytics` | Visitor analytics for a game |
+| `blazium-games://games/{uid}/crashes` | `game-crashes` | Crash reports for a game |
+| `blazium-games://games/{uid}/deploy` | `game-deploy` | Non-secret deploy endpoints and key prefixes |
+| `blazium-games://games/{uid}/builds` | `game-builds` | Uploaded builds and crash reporter build_ids |

package/skills/blazium-games-get-started/references/tools.md

@@ -0,0 +1,160 @@
+# Blazium Games MCP tools
+
+All tools call the Blazium Games API on behalf of the connected user. `uid` accepts a game uid or its vanity name. Tools marked **account** need an account-level token (a project token gets `4030`); tools marked **write** need `mcp:write` or the narrower write scope for that tool's group. Tools marked **deprecated** are removed from this server on 2026-10-28; use the player server at `https://mcp.blazium.games/player` instead.
+
+| Tool | Inputs | Access | What it does |
+|------|--------|--------|--------------|
+| `get_profile` | none | account | Authenticated user profile |
+| `get_setup` | none | account | Account, games, public URLs, and key prefixes. No secrets |
+| `list_games` | none | | Games the user owns or admins, plus pending admin invites |
+| `get_game` | `uid` | | One game's settings and store page fields |
+| `create_game` | `name` (required), `tagline`, `description`, `visibility`, `asset_type`, `vanity_name`, `adult`, `indexable`, `parent` | account, write | Create a store page. Tools, mods and plugins need a `parent` before they can go public. Needs developer mode on the account (`4105`) |
+| `update_game` | `uid` (required), `name`, `tagline`, `description`, `visibility`, `asset_type`, `adult`, `indexable`, `parent` | write | Update a store page; only passed fields change. An empty `parent` object clears it |
+| `get_game_analytics` | `uid` | | Visitor analytics: views, unique visitors, countries, actions |
+| `list_game_crashes` | `uid` | | Recent crash reports |
+| `get_crash` | `uid`, `crash_id` | | One crash with metadata, analysis, and stack availability |
+| `request_crash_download` | `uid`, `crash_id`, `kind` (`dump`, `log`, or `stack`; default `dump`) | | Private download URL valid for 1 hour |
+| `get_deploy_info` | `uid` | | Upload, crash, and events URLs, recent builds, env var names, deploy key prefixes. No secrets |
+| `list_game_builds` | `uid` | | Up to 50 builds. Each `build_id` is the `X-Build-Id` for crash reporters |
+| `get_game_build` | `uid`, `build_id` | | One build with its files and crash reporter headers |
+| `list_mcp_keys` | none | account | MCP API key prefixes. Secrets are never returned |
+| `request_mcp_key` | `idempotency_key` | account, write | Issue a new MCP API key and invalidate every previous one. Waits for the human's approval, then returns the secret once |
+| `request_deploy_key` | `uid`, `idempotency_key` | write | Issue a new upload `access_token` and `secret_key` for a game and invalidate the previous ones. Waits for the human's approval, then returns secrets once |
+| `list_channels` | `uid` | | Channel pointers (stable, beta, dev, custom), expiry, beta subscribers, and history |
+| `promote_build` | `uid`, `channel`, `build_id`, `expires_in_hours`, `idempotency_key` | write | Point a channel at a clean build. `stable` waits for the human's approval |
+| `rollback_channel` | `uid`, `channel` | write | Move a channel back to its previous build |
+| `list_crash_groups` | `uid` | | Up to 100 crash groups by cause, most recently seen first, with counts per build and a sample crash id |
+| `get_build_provenance` | `uid`, `file_uid` | | Uploader, deploy key reference, upload time, checksum, and scan history of a file |
+| `list_reviews` | `uid`, `unreplied`, `page` | | Player reviews with the summary (enjoyed, quality average and counts, would play with friends) |
+| `reply_to_review` | `uid`, `review_uid`, `text` | write | Public reply to a review; empty text removes it |
+| `list_bug_tickets` | `uid`, `status` | | Player bug tickets with counts by status; attachments carry a `crash_id` |
+| `update_bug_ticket` | `uid`, `bug_uid`, `status` (`open`, `fixed`, `closed`) | write | Mark a ticket fixed or closed, or reopen it; covered by `mcp:crash.read` |
+| `list_copyright_notices` | none | | Paid copyright (DMCA) notices about the account's content, with status and how many of its links each names |
+| `get_copyright_notice` | `uid` | | One notice: claimant, work, statements, the account's named links, staff messages, decision, and `reply_to`. Read only; the human replies by email with the reference in the subject |
+| `declare_dependency` | `uid`, `target_uid`, `kind`, `remove` | write | Link to another public listing: `uses`, `supports`, or `made_with` |
+| `list_dependents` | `uid` | | What a listing uses and which listings use it, plus license kind and compatibility |
+| `declare_engine_compat` | `uid`, `compat` | write | Replace the engine version ranges (engine, min/max version, renderer, platform) |
+| `declare_license` | `uid`, `license_kind` | write | `cc0`, `cc-by`, `cc-by-sa`, `paid`, `source-available`, or `proprietary` |
+| `create_key_pool` | `uid`, `name`, `campaign` | write | A named pool for redeemable game keys |
+| `grant_keys` | `uid`, `pool`, `n`, `campaign`, `idempotency_key` | write | Create 1-5000 keys; returns a one-time `csv_url` (1 hour). Over 100 needs the owner's approval |
+| `create_gift_link` | `uid`, `pool`, `note` | write | A single-use redeem link for one person, shown once |
+| `list_key_pools` | `uid` | | Pools with size, redeemed, unredeemed, and gift link counts |
+| `validate_listing` | `uid` | | Listing check (errors block going public), current taxonomy, and allowed values |
+| `update_game_taxonomy` | `uid`, `genres`, `tags`, `tone`, `inputs`, `content_warnings`, `engines`, `session_bucket`, `net`, `players_min`, `players_max`, `authorship`, `authorship_credit`, `ai_uses` | write | Set the taxonomy, the made-with label (`human`, `human_agent`, `agent_heavy`, empty clears; credit up to 120 characters), and the generative AI disclosure (`art`, `audio`, `code`, `text`, `voice`, `runtime`; empty list means none); only passed fields change |
+| `set_similar_games` | `uid`, `games` | write | Replace the similar titles (up to 10) |
+| `set_media` | `uid`, `kind` (`cover`, `thumbnail`, `gallery`) | write | Returns the `chauffeur media` commands and image limits (PNG, JPEG, GIF, WebP, sniffed from the file). Wide images need width/height between 1.70 and 1.85. Thumbnail 1280x720 recommended, 960x540 to 1920x1080, 5 MB. Cover 1024x576 recommended, 1024x576 to 2048x1152, 8 MB. Screenshot 1920x1080 recommended, 1280x720 to 2048x1152, 10 MB. Avatar 256x256 to 512x512, square (0.95 to 1.05), 2 MB, on the account settings page. MCP never uploads images |
+| `scan_status` | `uid` | | Virus-scan state and history per build file, and files removed for failing the scan |
+
+## Tools, mods and press
+
+A tool, mod or plugin names the game it is for with `parent` on `create_game` or `update_game`: `{"game": "uid-or-vanity"}` for a listing on Blazium Games, or `{"external_name": "...", "external_url": "https://..."}` for one that isn't. The parent's store page lists it under **Tools and utilities** or **Mods and plugins**.
+
+| Tool | Inputs | Access | What it does |
+|------|--------|--------|--------------|
+| `set_mod_settings` | `uid`, `install_path`, `loader`, `instructions` | write | Mods and plugins only (`4234` otherwise). Relative install path, lowercase loader slug (for example `bepinex`), markdown instructions up to 8000 characters. Replaces all three |
+| `get_press_kit` | `uid` | | The press kit behind the listing's `/press` page and `press.zip` |
+| `set_press_kit` | `uid`, `release_date`, `website_url`, `press_email`, `trailer_url`, `history`, `features`, `awards`, `links`, `quotes`, `credits` | write | Replace the whole press kit; omitted fields are cleared, so read it with `get_press_kit` first. https links only; up to 20 features, awards, links and quotes, and 50 credits |
+| `hide_community_tag` | `uid`, `tag`, `show` | write | Hide a player-suggested tag from the store page, or show it again with `show`. Without `tag`, lists every suggestion with its vote count |
+| `get_store_links` | `uid` | | The listing's links to its pages on other stores (shown as "Also on"), and every supported store with its allowed hosts |
+| `set_store_links` | `uid`, `store_links` (`platform`, `url`) | write | Replace every store link; omitted stores are removed, so read them with `get_store_links` first. One per store (`steam`, `gog`, `epic`, `itch`, `humble`, `microsoft`, `playstation`, `nintendo`, `apple`, `google_play`, `gamejolt`), each an https link on that store's own site |
+
+## Builds, health and editions
+
+MCP never uploads files: builds, symbols and store images go through the chauffeur CLI with the game's deploy key.
+
+| Tool | Inputs | Access | What it does |
+|------|--------|--------|--------------|
+| `get_build_health` | `uid` | | Per-build devices, boot-ok and crash-on-boot counts, median session and band over 30 days (`excellent`, `healthy`, `mixed`, `problematic`, or `unrated` until enough devices report) |
+| `list_build_symbols` | `uid`, `build_id` | | Breakpad symbol files for a build, plus the `chauffeur symbols` command |
+| `delete_build_symbols` | `uid`, `build_id`, `symbol_uid` | write | Delete one symbol file, or all of them when `symbol_uid` is empty |
+| `upload_symbols_info` | `uid`, `build_id` | | The exact `chauffeur symbols` command and limits for a build. Uploads nothing |
+| `bundle_check` | `uid`, `build_id` | | Informational: store asset packs found inside the build and whether each is `owned`, `licensed`, `attribution`, or `unlicensed` |
+| `mod_compat` | `uid` (a mod), `game` | | The mod's engine compatibility against each supported game's current builds: `compatible`, `incompatible`, or `unknown` |
+| `list_skus` | `uid` | | Editions with slug, kind, price, active flag, order, and bundle listings |
+| `upsert_sku` | `uid`, `sku_uid`, `slug`, `name`, `description`, `kind`, `price_cents`, `bundle_asset_uids`, `active`, `sort_order` | write | Create an edition, or replace one when `sku_uid` is set. Kinds: `standard`, `deluxe`, `beta_access`, `bundle`. Up to 8; the listed price follows the cheapest active one |
+| `delete_sku` | `uid`, `sku_uid` | write | Retire an edition; owners keep it |
+
+## Account and payments
+
+Amounts are integer US cents. Agents pay only from the stored balance, and only after the human approves the quoted total. Workflow: [blazium-games-purchases](../../blazium-games-purchases/SKILL.md).
+
+| Tool | Inputs | Access | What it does |
+|------|--------|--------|--------------|
+| `get_account` | none | account | Email verification, timezone, balances, what the account may do (publish, upload, download, buy), and open website sign-in steps (`gate`, `legal_acceptance_required`, `legal_changes`, `setup_required`, `authenticator`) |
+| `request_email_code` | none | account, write | Email a verification code to the human |
+| `verify_email` | `code` | account, write | Verify the email with the code the human read from their inbox |
+| `set_timezone` | `timezone` | account, write | Replace the saved timezone with the human's IANA name, when it is empty or the human asks. Do not send the timezone of the machine running the agent. Unknown names: `4085` |
+| `get_security_status` | none | account, read | Authenticator `state` (`on`, `skipped`, `not_chosen`), `enabled_at`, `skipped_at`, `recovery_codes_left`, and `email_code_alternative`. Changes happen only on the website |
+| `get_wallet` | none | account | Credit, pending, and available balances with fee, refund, and cash-out rules, payout status, and recent cash-outs. **Deprecated** |
+| `list_wallet_transactions` | `limit` (1-200, default 50), `before` | account | Ledger entries, newest first. **Deprecated** |
+| `get_payment_options` | none | account | Card top-up link option and x402 USDC networks with fees. **Deprecated** |
+| `create_top_up_link` | `amount_cents` (500-50000) | account, write | Card Checkout link for the human; agents cannot pay by card. **Deprecated** |
+| `create_x402_top_up` | `amount_cents`, `network` (default Base) | account, write | x402 payment requirements to sign with the agent's own wallet. **Deprecated** |
+| `pay_with_x402` | `top_up_id`, `payment_payload` | account, write | Submit the signed payment; credit is added after on-chain settlement. **Deprecated** |
+| `quote_purchase` | `uid`, `kind` (`purchase` or `donation`), `amount_cents` (donations), `sku` (edition; empty quotes the cheapest) | account, write | Price, tax, and `total_cents` to show the human. **Deprecated** |
+| `purchase_game` | `uid`, `confirm_total_cents`, `idempotency_key`, `sku` (same as the quote) | account, write | Buy a license from the balance; beyond the agent's limit returns `approval_required`. **Deprecated** |
+| `donate_to_game` | `uid`, `amount_cents`, `confirm_total_cents`, `idempotency_key` | account, write | Donate to a free game from the balance. **Deprecated** |
+| `list_library` | none | account | Owned games with refund windows and playtime. **Deprecated** |
+| `get_download_link` | `file_id` | account | 5-minute signed URL for a build file; needs a verified email and, for paid games, a license. **Deprecated** |
+| `set_game_price` | `uid`, `price_cents` (0 or 99-50000), `donations_enabled` | write | Set price or donations. Owners and game admins only |
+| `list_game_sales` | `uid` | | Sales, donations, refunds, and seller earnings for a game you manage |
+| `get_agent_policy` | none | account | This agent's limit mode, limit, and spend in the period; only the human changes them, on the website. **Deprecated** |
+| `get_approval` | `approval_id` | account | State of a purchase approval |
+| `confirm_approval` | `approval_id`, `code` | account, write | Approve with the 6-digit code the human read from their email |
+| `start_payout_setup` | none | account, money | Stripe payout setup link for the human |
+| `get_payout_dashboard_link` | none | account, money | One-time Stripe Express dashboard link (`4095` before setup) |
+| `cash_out` | `amount_cents` (at least 2500) | account, money | Cashes out available earnings to the account's own payout account, no approval; the owner is emailed. Up to 72 business hours to the bank |
+
+Payout tools are not deprecated and need `mcp:write` or `mcp:money`.
+
+## Field values
+
+- `visibility`: `draft` (owner and admins), `owner` (owner only), `invisible` (link only), or `public`
+- `asset_type`: `game`, `application`, `tool`, `mod`, `plugin`, `game_asset`, or `dev_asset`
+- `adult`: marks 18+ content (sexual content or nudity); hidden from search, recommendations and search engines
+- `indexable`: `false` keeps the store page out of search engines and AI crawlers
+- `build_id`: the build UID (for example `004e044e-...`), not a version string
+
+## Errors
+
+Tool errors come back as `API <status>: <body>`. Common bodies:
+
+| Code | Meaning |
+|------|---------|
+| `4010` | Not authenticated |
+| `4030` | Not allowed: the game isn't yours, or a project token called an account-level tool or another game. Reconnect with **Account** |
+| `4031` | Token is read-only |
+| `4034` | Buying moved to the player server, or only the project owner can manage admins |
+| `4040` | Not found (the message says what) |
+| `4090` | Already done: the game is already owned, or the crash has no such file to download |
+| `4091` | You can't buy your own game |
+| `4092` | The game is free |
+| `4093` | The game doesn't accept donations |
+| `4006` | Build not found |
+| `4096` | Email not verified; use `request_email_code` and `verify_email` |
+| `4085` | Not an IANA timezone name |
+| `4020` | Not enough balance; top up first |
+| `4221` | No billing address for tax; top up by card once or buy on the website |
+| `4023` | Buy the game before downloading it |
+| `4094` | Total changed since the quote; confirm again with the human |
+| `4099` | File still being scanned |
+| `4212` | This token can't make purchases |
+| `4214` | Waiting for the human's approval (a normal result, not an error) |
+| `4215` | The human denied the request |
+| `4216` | Wrong or expired approval code |
+| `4083` | Website only (account settings, approval links, key management) |
+| `4071` | Taxonomy value not allowed |
+| `4072` | Similar title isn't a public game, or is this game |
+| `4225` | Listing check failed, so the page can't go public. Run `validate_listing` |
+| `4073` | The token's scopes don't cover this tool; reconnect with a wider preset |
+| `4074` | File isn't on a channel this account can see |
+| `4075` | Nothing to roll back to |
+| `4226` | Invalid channel name or expiry |
+| `4155` | Invalid edition |
+| `4156` | The game already has 8 editions |
+| `4164` | The price comes from the editions; change them with `upsert_sku` |
+| `4105` | Developer mode is off; the human turns it on at blazium.games/settings |
+| `4233` | Invalid parent |
+| `4234` | Invalid mod settings |
+| `4235` | Invalid press kit |
+| `4238` | Invalid store link: wrong site, not https, or a store listed twice |

package/skills/blazium-games-keys/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: blazium-games-keys
+description: Inspect and rotate Blazium Games credentials, including MCP API keys and per-game deploy keys, with warnings before destructive rotation and the owner's approval, and create redeemable game keys and gift links. Use when the user wants to rotate, revoke, list, or replace a Blazium Games key, suspects a key leaked, or wants to hand out game keys.
+license: MIT
+---
+
+# Blazium Games: Keys
+
+Blazium Games has two kinds of credentials:
+
+| Credential | Used by | Rotate with | List with |
+|------------|---------|-------------|-----------|
+| MCP API key (`bgames_mcp_...`) | MCP clients without OAuth | `request_mcp_key` | `list_mcp_keys` |
+| Deploy key (`access_token` + `secret_key`) | chauffeur CLI and CI uploads (builds, symbols, store images) | `request_deploy_key` | `get_deploy_info` (`keys[]`) |
+
+## Invoke This Skill When
+
+- "Rotate my Blazium Games key", "my deploy key leaked", "list my keys"
+- A CI upload fails with an authentication error after someone rotated keys
+
+## Prerequisites
+
+- The `blazium-games` MCP server is connected with write access
+- MCP key tools need an account-level token
+
+## 1. Inspect
+
+- MCP keys: call `list_mcp_keys`. Only prefixes are returned.
+- Deploy keys: call `get_deploy_info` with the game `uid` and read `keys[]` (`uid`, `prefix`, `created_at`).
+
+## 2. Warn
+
+Rotation is immediate and destructive:
+
+- `request_mcp_key` invalidates **every** previous MCP API key on the account. Any client using an old key stops working. OAuth connections are not affected.
+- `request_deploy_key` invalidates **every** previous deploy key for that game. Any pipeline using an old key fails its next upload.
+
+Ask the user to confirm and to name where the new secret will be stored.
+
+## 3. Rotate
+
+Call the matching tool with an `idempotency_key` you make up (for example `rotate-deploy-<uid>-<date>`). Over MCP the first call returns HTTP 202 with `approval_required: true` (code `4214`), `email_sent`, and an `approval` object. Pass `approval.uid` as `approval_id`, and give the human `approval.confirm_url`; the account owner also gets an email with the link and a 6-digit code. Ask the human to approve, then either call `confirm_approval` with the code they read to you or poll `get_approval` until `approved`. A project-bound token can't call either (`4030`), so wait for the human to say they approved from the email. Call the rotation tool again with the same `idempotency_key`. Each approval works once. If the human denies it you get `4215`; stop.
+
+The secret is returned once. Tell the user to store it (CI secret, password manager, or a gitignored `.env`) and then stop repeating it.
+
+## 4. Update consumers
+
+- MCP key: update the `Authorization: Bearer` header in each MCP client config.
+- Deploy key: update `BLAZIUM_ACCESS_TOKEN` and `BLAZIUM_SECRET_KEY` in every CI system, for example with `gh secret set BLAZIUM_ACCESS_TOKEN`.
+
+## Revoking OAuth access
+
+OAuth grants and project-bound MCP keys are managed at https://blazium.games/settings/mcp and in each game's settings. Revoking there does not require rotating API keys.
+
+## Project keys and admins
+
+- Each owner and admin creates their own project key. Creating one replaces only your own previous key for that project.
+- Adding an admin over MCP waits for the owner's approval, and deleting a deploy key does too. Only the owner can add admins or remove other admins (`4034`).
+- Removing an admin revokes their key for the project.
+- The owner can turn off MCP access for admins on the project's MCP tab (website only). That revokes admins' keys and blocks their account keys and OAuth for that project.
+
+## Game keys (redeemable codes)
+
+Redeemable game keys are not credentials; they give players a copy of the game. They need a token with `mcp:money` (or full access).
+
+1. `create_key_pool` with the game `uid` and a `name`.
+2. `grant_keys` with `pool`, `n` (1 to 5000), and an `idempotency_key`. The codes come back once, as a `csv_url` that downloads one time within an hour. More than 100 at once returns `approval_required` like a rotation.
+3. `create_gift_link` makes a single-use redeem link for one person, shown once.
+4. `list_key_pools` shows size, redeemed, unredeemed, and gift link counts. Codes can't be shown again.
+
+## Read-only tokens
+
+If the user approved the connection with **Read-only access**, the token only has `mcp:read`. Rotation tools then fail with HTTP 403, code 4031 ("This token is read-only"). Ask the user to reconnect without the read-only option, or to rotate on the website. A token from a narrower preset without `mcp:keys.manage` gets `4073`; reconnect with the **Keys** or **Full access** preset.
+
+## Docs
+
+- https://docs.blazium.games/docs/mcp/access-and-keys
+- Permissions, scopes, and error codes: https://docs.blazium.games/docs/legal/permissions

package/skills/blazium-games-player/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: blazium-games-player
+description: Connect an agent to a Blazium Games account as a player through the player MCP server at mcp.blazium.games/player. Checks the account and email, reads the wallet and library, recommends games with cited reasons, searches the catalog, writes reviews and bug reports, shows what friends are playing, explains player scopes and spending limits, and routes to purchases, installs, or launches. Use when the user wants an agent to act for them as a player on Blazium Games, find a game to play, review a game, report a bug, set up the player MCP server, or check what they own or can spend.
+license: MIT
+---
+
+# Blazium Games: Player
+
+The player server acts for one player. It sees the account, wallet, and library, and with `player:buy` it can top up and buy within the human's spending limit. It never touches game pages, builds, or keys; those need the developer server (`blazium-games`, see [get-started](../blazium-games-get-started/SKILL.md)).
+
+## Invoke This Skill When
+
+- "Connect my Blazium Games account as a player", "set up the Blazium Games player server"
+- "What games do I own on Blazium Games?", "how much can this agent spend?"
+- Before [purchases](../blazium-games-purchases/SKILL.md) when the player server isn't connected
+
+## 1. Connect
+
+1. Check whether a `blazium-games-player` server is connected. If not, ask the human to add it:
+
+   ```json
+   { "mcpServers": { "blazium-games-player": { "url": "https://mcp.blazium.games/player" } } }
+   ```
+
+2. On the consent page the human ticks **Allow purchases** only if you should buy for them. A player key (`bgames_play_...`) from https://blazium.games/settings/mcp works too.
+3. A developer key (`bgames_mcp_...`) or developer OAuth token is refused here, and a player token is refused by the developer server. Never try to reuse one for the other.
+
+## 2. Check the account
+
+1. Call `get_account`. If `email_verified` is false, call `request_email_code`, ask the human for the code from their inbox, and call `verify_email`. Downloading and buying need a verified email. If `timezone` is empty and you know the human's IANA timezone, call `set_timezone`. Do not use the timezone of the machine you are running on. If `gate` is not empty, tell the human to finish that step at https://blazium.games/account/finish (accept changed terms, finish setup, or choose about an authenticator app). Never do those steps for them.
+2. Call `get_agent_policy` to see this agent's limit: `unset` (every purchase needs approval), `unlimited`, `monthly`, `yearly`, or `one_time`. Only the human changes it, on the website.
+3. Call `get_wallet` for the available balance.
+
+## 3. Route
+
+| The human wants to | Do |
+|---|---|
+| Buy, donate, or top up | [purchases](../blazium-games-purchases/SKILL.md) |
+| See what they own | `get_library` |
+| Set up payouts or cash out earnings | Only when the human asks. `start_payout_setup` (or `get_payout_dashboard_link` once set up) and give them the Stripe link; never enter their details yourself. `cash_out` with the amount they asked for, from the available earnings in `get_wallet`. Tell them it can take up to 72 business hours to reach the bank and that they will get an email |
+| Something to play, and they haven't said what | `get_shelf` with `tonight`, `unheard_of` when they want something new, or `browser_playable` when they can't install anything, before a wide `recommend` |
+| Something to play right now | `recommend` with what they told you (`minutes`, `party_size`, `intent` in their words, `like_uid`, `os`). Give each pick with its `reasons` and `cautions`; don't add reasons of your own. If the results are empty, relay the `hint` and ask for one more constraint |
+| Why a game was or wasn't suggested | `why_this` with the same inputs; its `blockers` say what kept it out |
+| Find something specific | `search_catalog` with their constraints (for example `session_bucket: 15m`, `players: 2`, `os: windows`, `genres: [puzzle, strategy]`, or `exclude_tone: [dark]` for what they want to avoid), then `get_game_details` on the best matches. Say why each one fits using `why_short` |
+| "More like this" / "not for me" | `taste_feedback` with `more_like` true or false |
+| Mods or tools for a game | `list_game_addons` with the game's `uid` (`kind: mods` or `tools`) |
+| Tag a game they play | `suggest_tag` with the tag they chose. It needs an hour of play (`4237`); `remove` takes it back |
+| Review a game they own | Ask whether they enjoyed it and, separately, its quality from 1 to 5, then `write_review` with their words. Never write a review they didn't give you |
+| Report a bug | `report_bug` with what happened and how to reproduce it. If they have a crash dump or log, set `include_dump` / `include_log` and upload the file with `PUT` to the returned URL |
+| "What are my friends playing?" | `games_friends_play`; live games come first, then the last 14 days |
+| Add or answer a friend | `send_friend_request` with the username they gave you, or `list_friends` then `respond_friend_request`. Only send requests the human asked for |
+| Redeem a key or gift link | `redeem_key` with the code or link they gave you. `4084` means they already own it and the key is still unused |
+| Install a game they own or a free game | `why_should_i_trust_this` first. Pass its facts on, and do not call a file safe. Then `install_build` and give them the `blazium://install/<uid>` link. If it fails because the scan isn't clean, don't offer another way to download that file |
+| Join or leave a beta | `set_channel` (`beta` or `stable`), then `install_build` |
+| Play a game | `launch_game`, then give them the `blazium://game/<uid>` link. The desktop app is Windows and Linux. Hand over the link; do not fetch the installer unless they ask |
+| Download a game they own or a free game | Step 5 (Download) of [purchases](../blazium-games-purchases/SKILL.md) |
+
+## Errors
+
+| Code | Meaning |
+|------|---------|
+| `4212` | The token has no `player:buy`. The human reconnects and ticks **Allow purchases**, or creates a key with purchases allowed |
+| `4031` | The token is read-only |
+| `4033` | That route isn't available to player tokens. Use the developer server for game management |
+| `4032` | The token mixes developer and player scopes. Reconnect |
+| `4076` | Reviews and bug reports need a copy of the game: buy it, or download it if it's free |
+| `4077` | The human is a developer of this game and can't review it |
+| `4291` | Too many bug reports today; try tomorrow |
+| `4078` | Already friends, or the request was already sent |
+| `4292` | Too many friend requests today; try tomorrow |
+| `4042` / `4079` | The key isn't valid, or was already redeemed |
+
+## References
+
+- [Tools](./references/tools.md)
+- https://docs.blazium.games/docs/mcp/player

package/skills/blazium-games-player/references/tools.md

@@ -0,0 +1,67 @@
+# Player server tools
+
+Server: `https://mcp.blazium.games/player`. Scopes: `player:read`, `player:write`, `player:buy`.
+
+## Tools
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `get_account` | read | Email verification, timezone, balances, what the account may do, and open website sign-in steps (`gate`, `legal_acceptance_required`, `setup_required`, `authenticator`) |
+| `request_email_code` | write | Email a verification code to the human |
+| `verify_email` | write | Verify the email with the human's code |
+| `set_timezone` | write | Replace the saved timezone with the human's IANA name, when `get_account` timezone is empty or the human asks. Do not use the agent's machine timezone. Unknown names: `4085` |
+| `get_security_status` | read | Authenticator `state` (`on`, `skipped`, `not_chosen`), `recovery_codes_left`, and `email_code_alternative`. Changes happen only on the website |
+| `get_wallet` | read | Balances, fee and refund rules, payout status (`payouts`), recent `cash_outs`, and `rules.payout_arrival` |
+| `list_wallet_transactions` | read | Ledger entries, newest first |
+| `get_payment_options` | read | Card and x402 USDC top-up options with fees |
+| `create_top_up_link` | buy | Card Checkout link for the human |
+| `create_x402_top_up` | buy | x402 payment requirements for a USDC top-up |
+| `pay_with_x402` | buy | Submit the signed x402 payment |
+| `quote_purchase` | read | Price, tax, and total |
+| `purchase_game` | buy | Buy a license from the balance |
+| `donate_to_game` | buy | Donate to a free game from the balance |
+| `get_approval` | read | State of an approval |
+| `confirm_approval` | write | Approve with the human's emailed code |
+| `get_library` | read | Owned games, refund windows, play time |
+| `get_download_link` | read | 5-minute signed download URL |
+| `get_agent_policy` | read | This agent's spending limit |
+| `start_payout_setup` | buy | Start or continue Stripe payout setup; returns a link only the human opens to enter identity, tax, and bank details |
+| `get_payout_dashboard_link` | buy | One-time Stripe Express dashboard link for the human (`4095` until setup has started) |
+| `cash_out` | buy | Cash out available earnings (`amount_cents`, at least 2500) to the human's own payout account. No approval; the owner is emailed. Up to 72 business hours to reach the bank. `4021` not enough available, `4057` below the minimum |
+| `search_catalog` | read | Search public games, tools, mods, and assets by text, genres, tags (including community tags), tone, session length, network mode, players, platform, engine and version, renderer, license, made-with label (`authorship`), and `ai_uses`. Several values in one filter match any of them; `exclude_types`, `exclude_genres`, `exclude_tone`, `exclude_tags`, `exclude_warnings`, and `exclude_ai_uses` leave listings out. Adult listings only appear if the human turned on adult content |
+| `list_game_addons` | read | Mods and plugins, or tools and applications, made for a game (`kind`: `mods`, `tools`, or empty for both); `same_creator` marks the developer's own |
+| `suggest_tag` | write | Suggest a tag for a game the human owns and played for an hour (`4237` before that), or `remove` it; up to 5 per game. Without `tag`, returns their suggestions. Only suggest tags the human chose |
+| `get_shelf` | read | A home page shelf for the human's `os` (`limit` 1-24): `tonight` (short sessions with a healthy build), `unheard_of` (recent listings few people have found), `featured`, `new`, `recently_updated`, `made_with_blazium`, `in_development`, `browser_playable`, `community`, or `tools_and_assets`. `has_browser_build` and `has_downloads` say how each one plays |
+| `get_game_details` | read | One listing: taxonomy, price, files with scan state and checksum, similar titles, links to its pages on other stores (`store_links`), ownership |
+| `install_build` | read | License and scan check, checksum, 5-minute download URL, and a `blazium://install/<uid>` hand-off. Uses the channel the human follows unless `channel` is given. Fails unless the file is clean |
+| `launch_game` | read | `blazium://game/<uid>` hand-off link for the launcher |
+| `set_channel` | write | Join (`beta`) or leave (`stable`) a game's beta |
+| `why_should_i_trust_this` | read | Developer, upload provenance, scan history, checksums, and cautions for the current files. Never claims a file is safe |
+| `recommend` | read | Listings of one `asset_type` (default `game`) for right now from `minutes`, `party_size`, `intent`, `like_uid`, and platform. Deterministic; every result has `reasons` citing listing fields. Pass the reasons on instead of inventing your own |
+| `why_this` | read | One game against the same inputs: score, reasons, cautions, and the `blockers` that keep it out of `recommend` |
+| `write_review` | write | Create, update, or `delete` the human's review of a game they own: `enjoyed` and `quality` (1-5) are separate, plus `would_play_with_friends` and `text`. Only write what the human said |
+| `taste_feedback` | write | `more_like` true or false for a game, or `clear` |
+| `report_bug` | write | File a bug ticket with the developers (10 per day); `include_dump` / `include_log` return one-time upload URLs |
+| `games_friends_play` | read | What friends are playing now, then what they played in the last 14 days; `live_only` skips the recent list |
+| `list_friends` | read | Friends with presence, plus incoming and sent requests with their `request_uid` |
+| `send_friend_request` | write | Send a request by username (20 per day, verified email). Accepts theirs if they already asked |
+| `respond_friend_request` | write | Accept or decline an incoming request |
+| `redeem_key` | write | Redeem a game key or gift link the human gave you; a game they already own leaves the key unused |
+
+## Resources
+
+| URI | Contents |
+|-----|----------|
+| `blazium-games://me` | Account status |
+| `blazium-games://wallet` | Stored balance and payment rules |
+| `blazium-games://library` | Owned games and licenses |
+| `ui://blazium-games/checkout.html` | Quote, buy, and donate. The purchase runs when the human clicks |
+| `ui://blazium-games/game.html` | Game information and trust checks |
+| `ui://blazium-games/results.html` | Search, recommendations, shelves, add-ons, and what friends are playing |
+| `ui://blazium-games/wallet.html` | Balance, ledger, spending limit, and a card top-up link |
+| `ui://blazium-games/approval.html` | Approval status, confirm link, and the emailed code |
+| `ui://blazium-games/library.html` | Owned games, redeem, and download links |
+| `ui://blazium-games/handoff.html` | `blazium://` hand-off for the Windows and Linux launcher |
+| `ui://blazium-games/account.html` | Verification, timezone, and links to finish sign-in on the website |
+| `ui://blazium-games/feedback.html` | Reviews, bug reports, taste, and tag suggestions. Send only what the human wrote |
+| `ui://blazium-games/friends.html` | Friends and requests. Send and answer only from a click |

package/skills/blazium-games-purchases/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: blazium-games-purchases
+description: Buy games and donate on Blazium Games from the account's stored balance. Quotes the price and tax, confirms with the human, buys with an idempotency key, handles per-agent spending limits and emailed approvals, low balance, tops up by card link or x402 USDC, and fetches download links. Use when the user wants to buy, purchase, donate to, or download a game on Blazium Games, check their balance or library, or add balance.
+license: MIT
+---
+
+# Blazium Games: Purchases
+
+Agents buy only from the stored balance and only after telling the human the exact total. Within the limit the human set for this agent a purchase completes at once; anything else waits for the human to approve it by emailed link or code.
+
+## Invoke This Skill When
+
+- "Buy <game> on Blazium Games", "donate $5 to <game>"
+- "What's my Blazium Games balance?", "add $20 to my balance"
+- "Download <game>", "what games do I own?"
+
+## Prerequisites
+
+- The `blazium-games-player` MCP server (`https://mcp.blazium.games/player`) is connected with `player:buy` (the human ticked **Allow purchases**). See [player](../blazium-games-player/SKILL.md). The developer server still has these tools until 2026-10-28, marked deprecated; prefer the player server
+- The account email is verified
+- Optional: the human set a spending mode for this agent at https://blazium.games/settings/mcp (unlimited, monthly, yearly, or one-time limit). Without one, every purchase needs their approval
+
+## 1. Check the account
+
+1. Call `get_account`. If `email_verified` is false, call `request_email_code`, ask the human for the code from their inbox, and call `verify_email`.
+2. Call `get_agent_policy`. `limit_mode` is `unset` (every purchase needs approval), `unlimited`, `monthly`, `yearly`, or `one_time`; `limit_cents` minus `spent_in_period_cents` is what you can spend without approval. Only the human changes it, at https://blazium.games/settings/mcp.
+3. Call `get_library` (`list_library` on the developer server) to see whether the game is already owned. If it is, skip to step 5 (Download).
+
+## 2. Quote
+
+Call `quote_purchase` with the game `uid` (or vanity name). For a donation to a free game, pass `kind: "donation"` and `amount_cents` (100 to 50000).
+
+If `get_game_details` lists `skus` (editions such as deluxe, beta access, or a bundle), ask the human which one and pass its slug as `sku` to both `quote_purchase` and `purchase_game`. Without `sku` the cheapest edition is bought. Owners of a cheaper edition pay only the difference.
+
+The quote returns price, tax, and `total_cents`. Tax depends on the human's saved address.
+
+## 3. Confirm with the human
+
+Show the game, price, tax, and total in dollars, and say it will come from their Blazium Games balance. Wait for an explicit yes. Never buy on an assumed or earlier approval.
+
+## 4. Buy
+
+Call `purchase_game` (or `donate_to_game` with the same `amount_cents`) with:
+
+| Field | Value |
+|-------|-------|
+| `uid` | The game |
+| `sku` | Optional edition slug, the same one you quoted |
+| `confirm_total_cents` | `total_cents` the human approved |
+| `idempotency_key` | A new unique string, for example a UUID. Reuse it only to retry this same purchase after a network error |
+
+| Code | What to do |
+|------|------------|
+| `4094` | The total changed. Show the new total from the error and ask again, then retry with a new idempotency key |
+| `4020` | Not enough balance. Go to step 6 (Add balance) |
+| `4221` | No billing address for tax. The human must top up by card once (`create_top_up_link`) or buy on the website |
+| `4214` | Not an error: `approval_required`. Go to step 4b (Approval) |
+| `4215` | The human denied it. Do not retry |
+| `4095` | That idempotency key was used for a different purchase. Use a new key |
+| `4212` | This token can't buy: no `player:buy`, or a project token. The human reconnects the player server with **Allow purchases** |
+| `4096` | Email not verified. Go back to step 1 (Check the account) |
+| `4090` | The human already owns the game. Skip to step 5 (Download) |
+| `4091` | It's the human's own game; they can't buy it |
+| `4092` | The game is free; no purchase needed. Skip to step 5 (Download) |
+| `4093` | The game doesn't accept donations |
+| `4155` | Unknown edition. Check `skus` in `get_game_details` |
+| `4157` | The human already owns this edition or a higher one |
+| `4165` | Beta access is sold as an edition. Offer the `beta_access` edition from `data.skus` |
+| `4030` | A project-bound developer token. Use the player server instead |
+| `4034` | Buying moved to the player server; the developer copies no longer work. Use `blazium-games-player` |
+
+## 4b. Approval
+
+The result has `approval_required: true` and an `approval` with its `uid`. The human got an email with a link and a 6-digit code.
+
+1. Tell the human: approve with the link in the email, or read you the code.
+2. If they give you the code, call `confirm_approval` with `approval_id` and `code`. `4216` means the code is wrong or expired.
+3. Otherwise call `get_approval` after they say they approved. `status` is `pending`, `approved`, `denied`, `expired`, or `used`.
+4. Once `approved`, call `purchase_game` (or `donate_to_game`) again with the same `idempotency_key` and `confirm_total_cents`. The approval covers only that purchase and expires after 30 minutes; if it expired, the retry sends a new email.
+
+## 5. Download
+
+1. Take `developer` and `vanity_name` (or `game_uid`) from `get_library`.
+2. Read the public page data (no auth): `GET https://api.blazium.online/api/v1/public/user/<developer>/games/<vanity_name>`. Pick the file for the human's OS and arch from `data.files[]` and keep its `uid`.
+3. Call `get_download_link` with `file_id` set to that `uid`. The link lasts 5 minutes; give it to the human right away.
+
+Free games can be downloaded the same way without buying. If the error is `4099`, the file is still being scanned; try again later.
+
+## 6. Add balance
+
+Call `get_wallet` and `get_payment_options`, then either:
+
+- **Card:** `create_top_up_link` with `amount_cents` (500 to 50000). Give the URL to the human; you cannot pay by card. Check `get_wallet` after they say it is done.
+- **USDC over x402:** only if you have your own wallet and the human agreed. Call `create_x402_top_up` (`amount_cents`, optional `network`), sign a payment for exactly the returned requirements, then call `pay_with_x402` with `top_up_id` and the signed `payment_payload`. Credit appears after settlement.
+
+Top-ups add a processing fee (shown by `get_payment_options`). Credit can be spent but never cashed out.
+
+## Rules to tell the human when relevant
+
+- Refunds are only through support@blazium.games: purchases within 7 days and before 2 hours of play. Donations are not refundable.
+- With `player:buy` you can set up payouts (`start_payout_setup`, `get_payout_dashboard_link`; the human opens the Stripe link) and cash out available earnings (`cash_out`, $25 minimum) without approval. Money only goes to the account's own payout account, the owner is emailed after each cash-out, and it can take up to 72 business hours to reach the bank.
+
+## Docs
+
+- https://docs.blazium.games/docs/payments/agent-purchases
+- https://docs.blazium.games/docs/payments/top-up