summer-engine 3.5.2 → 3.6.0

package/dist/mcp/tools/generate-tools.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { BOARD_ENDPOINT, boardArgsSchema, boardContent, boardQuery } from "../../core/capabilities/board.js";
 import { IMAGE_GENERATION_TIMEOUT_MS, imageGenerationArgsSchema, saveGeneratedImage } from "../../core/capabilities/image-generation.js";
 import { buildMotionRequestBody, motionErrorHint, motionGenerationArgsSchema, motionJobFailureHint, } from "../../core/capabilities/motion-generation.js";
+import { MAX_CHOICES_WAIT_SECONDS, defaultCanOpenBrowser, generateSfxChoices, getChoices, getChoicesArgsSchema, openInStudioTab, sfxChoicesArgsSchema, SFX_CHOICES_ENDPOINT, } from "../../core/capabilities/sfx-choices.js";
+import open from "open";
 import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readJsonResponse } from "../../core/util/http.js";
@@ -10,6 +12,7 @@ import { TOOLKIT_VERSION as CLI_VERSION } from "../../core/version.js";
 const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/image": "summer_generate_image",
     "/api/mcp/generate/audio": "summer_generate_audio",
+    [SFX_CHOICES_ENDPOINT]: "summer_generate_sfx_choices",
     "/api/mcp/generate/3d": "summer_generate_3d",
     "/api/mcp/generate/video": "summer_generate_video",
     "/api/mcp/generate/motion": "summer_generate_motion",
@@ -356,10 +359,21 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
 
 Capabilities:
   - "text_to_speech" — Convert text to spoken audio. Requires 'text'. Optional 'voiceId'.
-  - "sound_effects" — Generate sound effects from description. Requires 'text'. Optional 'durationSeconds'.
+  - "sound_effects" — Generate sound effects from description. Requires 'text'. Optional 'durationSeconds', 'modelId', 'loop'.
   - "music" — Generate background music. Requires 'prompt'. Optional 'durationSeconds'.
   - "text_to_dialogue" — Multi-voice dialogue. Requires 'inputs' array of {text, voiceId} objects.
 
+Sound-effect models (modelId; omit it to use the person's approved default,
+else ElevenLabs):
+  - "eleven_text_to_sound_v2" — ElevenLabs SFX v2. Strong all-rounder, 0.5-30 s,
+    the only one that makes seamless loops (loop: true).
+  - "sonilo-sfx-1.1" — Sonilo SFX 1.1. Strong all-rounder, >= 0.5 s.
+  - "stable-audio-3-sfx" — Stable Audio 3 SFX. Sometimes best on fast movement
+    (swings, whooshes), less consistent; >= 1 s.
+The best model changes a lot from one sound to the next. For the first sound
+effect in a chat, offer the person three versions to pick from by ear:
+summer_generate_sfx_choices.
+
 The 'options' object is spread into the ElevenLabs SDK call at the TOP level, so
 only keys the SDK accepts there have any effect. Voice tuning is NOT top-level and
 is NOT snake_case: pass it as options.voiceSettings with camelCase keys —
@@ -388,11 +402,16 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         modelId: z
             .string()
             .optional()
-            .describe("ElevenLabs model ID (e.g. 'eleven_multilingual_v2')"),
+            .describe("Model id. text_to_speech: an ElevenLabs model (e.g. 'eleven_multilingual_v2'). " +
+            "sound_effects: eleven_text_to_sound_v2, sonilo-sfx-1.1 or stable-audio-3-sfx; omit to use the person's approved default"),
         durationSeconds: z
             .number()
             .optional()
             .describe("Duration in seconds for SFX or music"),
+        loop: z
+            .boolean()
+            .optional()
+            .describe("sound_effects only: ask for a seamless loop (eleven_text_to_sound_v2 only)"),
         inputs: z
             .array(z.object({ text: z.string(), voiceId: z.string() }))
             .optional()
@@ -403,7 +422,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             .describe("Provider params, spread at the SDK's top level. Voice tuning goes in " +
             "options.voiceSettings with camelCase keys (stability, similarityBoost, " +
             "style, speed, useSpeakerBoost); flat snake_case is silently ignored."),
-    }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, inputs, options }) => {
+    }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, loop, inputs, options }) => {
         const body = { capability };
         if (text)
             body.text = text;
@@ -415,6 +434,8 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             body.modelId = modelId;
         if (durationSeconds)
             body.durationSeconds = durationSeconds;
+        if (loop !== undefined)
+            body.loop = loop;
         if (inputs)
             body.inputs = inputs;
         if (options)
@@ -426,6 +447,52 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         return successResult(result.data);
     });
     // ========================================================================
+    // summer_generate_sfx_choices + summer_get_choices
+    // Shared implementation: core/capabilities/sfx-choices.ts
+    // ========================================================================
+    const sfxChoicesDeps = {
+        post: (endpoint, body, timeoutMs) => mcpGenerate(endpoint, body, timeoutMs),
+        get: (endpoint, params, timeoutMs) => mcpGet(endpoint, params, timeoutMs),
+        studioOpen: (path, reviewUrl) => openInStudioTab(path, reviewUrl),
+        openUrl: (url) => open(url),
+        canOpenBrowser: () => defaultCanOpenBrowser(),
+    };
+    server.tool("summer_generate_sfx_choices", `Make one sound effect with several models (default three) and show the
+versions to the person on a Summer Studio page, where they listen and approve
+one or more. The approved model becomes their default for sound effects.
+
+Use it for the first sound effect in a chat after the person said yes to
+"three versions to pick from", or whenever they want to compare. The page
+opens in their open Summer Studio tab when there is one (needs the store
+sign-in), else in the browser; open:false only returns reviewUrl.
+
+Then tell the person the returned "say" text and call summer_get_choices
+with the choiceSetId. Do not pick for them.
+
+Models: eleven_text_to_sound_v2 (0.5-30 s, loops), sonilo-sfx-1.1 (>= 0.5 s),
+stable-audio-3-sfx (>= 1 s; give durationSeconds >= 1 when it is included).
+Each version is a billed generation.
+
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, sfxChoicesArgsSchema.shape, async (args) => {
+        const result = await generateSfxChoices(sfxChoicesArgsSchema.parse(args), sfxChoicesDeps);
+        return result.ok ? successResult(result) : errorResult(String(result.error), result);
+    });
+    server.tool("summer_get_choices", `Read a sound-effect choice set from summer_generate_sfx_choices: whether the
+person decided ("pending" or "decided"), which versions they approved (with
+audioUrl, assetId and their note) and their default sound-effect model.
+
+waitSeconds (max ${MAX_CHOICES_WAIT_SECONDS}) waits for the decision before answering; call again
+while status is "pending". Import each approved clip with
+summer_import_from_url (url: audioUrl, path: res://audio/sfx/<name>.<fileExtension>)
+or summer_import_asset_by_id (assetId), then wire it.
+
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, getChoicesArgsSchema.shape, async (args) => {
+        const result = await getChoices(getChoicesArgsSchema.parse(args), sfxChoicesDeps);
+        return result.ok ? successResult(result) : errorResult(String(result.error), result);
+    });
+    // ========================================================================
     // summer_generate_3d
     // ========================================================================
     server.tool("summer_generate_3d", `Generate a 3D model via Summer Engine Studio.

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -17,7 +17,7 @@
 
 **Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
 
-## Tool surface (105 tools)
+## Tool surface (107 tools)
 
 ### Project files (4)
 
@@ -211,13 +211,15 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. |
 | `summer_slice_asset_sheet` | Detect and crop every distinct asset from a generated sheet image into named individual assets (works without the engine; import the results afterwards). |
 
-### Asset generation (5 — metered)
+### Asset generation (7 — metered)
 
 | Tool | Use |
 |---|---|
 | `summer_generate_image` | AI image gen. |
 | `summer_generate_3d` | Image-to-3D. |
-| `summer_generate_audio` | SFX / music gen. |
+| `summer_generate_audio` | SFX / music gen. Sound effects: `modelId` picks ElevenLabs SFX v2, Sonilo SFX 1.1 or Stable Audio 3 SFX; omitted = the person's approved default. |
+| `summer_generate_sfx_choices` | One sound effect from several models, shown on a Summer Studio page where the person approves one or more. |
+| `summer_get_choices` | Read which sound-effect versions the person approved (audioUrl, assetId, note). |
 | `summer_generate_video` | Video gen. |
 | `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
 

package/library/references/mcp-tools-reference/resource.yaml

@@ -1,6 +1,6 @@
 id: reference/mcp-tools-reference
 kind: reference
-version: 1.4.0
+version: 1.4.1
 summary: Canonical reference for which Summer MCP tool to call — skills should reference tool names exactly as written here.
 use_when:
   - choosing between Summer MCP tools and host tools for an operation

package/library/skills/README.md

@@ -117,7 +117,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [ambient-bed](./ambient-bed/SKILL.md) | Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop. | assets |
 | [audio-direction](./audio-direction/SKILL.md) ★ | Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md. | game-design |
 | [music-track](./music-track/SKILL.md) ★ | Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear. | assets |
-| [sound-effect](./sound-effect/SKILL.md) ★ | Generate short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts — wired as AudioStreamPlayer/2D/3D that auto-frees on finished. | assets |
+| [sound-effect](./sound-effect/SKILL.md) ★ | Make SFX one-shots and timed sequences (swings, hits, whooshes, reloads, UI) - offer three model versions to pick from, then wire them as AudioStreamPlayers. | assets |
 | [voice-line](./voice-line/SKILL.md) ★ | Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support. | assets |
 
 ## character-controller
@@ -147,7 +147,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | skill | when to use | also |
 |---|---|---|
 | [export-and-ship](./export-and-ship/SKILL.md) ★ | Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval. | project |
-| [*release-readiness*](./release-readiness/SKILL.md) (preview) | Before releasing a Summer game version, prove players can play it: server scene, online join, saved progress, no fixed Game ID, a released Summer compiles it. | multiplayer, playtest |
+| [*release-readiness*](./release-readiness/SKILL.md) (preview) | Before releasing a Summer game version, prove players can play it: server scene, online join, progress, Game ID, released Summer, packed files, app version. | multiplayer, playtest |
 | [remote-deploy](./remote-deploy/SKILL.md) ★ | Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging. | project |
 
 ## editor

package/library/skills/ambient-bed/SKILL.md

@@ -103,13 +103,15 @@ If the user wants a busier bed (market, party), still prevent foreground events:
 ```
 summer_generate_audio(
   capability: "sound_effects",
+  modelId: "eleven_text_to_sound_v2",
+  loop: true,
   text: "forest at dawn, gentle wind through leaves, distant bird calls every 6 seconds, soft creaking branches, no music, no human sound, 22s seamless loop",
   durationSeconds: 22
 )
 // Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/ambient/forest_dawn.wav")
 ```
 
-`sound_effects` reads from **`text`**, not `prompt` — passing `prompt` is a 400 `text_required`. (`prompt` is the `music` capability's field.) The clip comes back as WAV, so a `.wav` target path is correct.
+Name `modelId: "eleven_text_to_sound_v2"` with `loop: true`: it is the only sound-effect model that makes seamless loops, and without a `modelId` the person's default sound-effect model runs, which may not loop. `sound_effects` reads from **`text`**, not `prompt` — passing `prompt` is a 400 `text_required`. (`prompt` is the `music` capability's field.) The clip comes back as WAV, so a `.wav` target path is correct.
 
 22s is the SFX ceiling. Always generate at the ceiling for ambient — longer cycle means less recognized repetition.
 

package/library/skills/ambient-bed/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/ambient-bed
 kind: skill
-version: 1.0.2
+version: 1.0.3
 summary: Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop.
 use_when:
   - generating a long looping location ambience — forest at dawn, dungeon air, city street, spaceship hum, cave drip — non-melodic and low-energy

package/library/skills/audio-direction/SKILL.md

@@ -203,15 +203,15 @@ Ask:
 
 ### 10. Optional — generate first SFX seeds
 
-If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals.
+If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals. Generate them with the `sound-effect` skill: the first sound effect in a chat starts with its question (three versions from three models, picked by ear in Summer Studio), and its prompt shape is the one that tested well.
 
 ```
-summer_generate_audio(capability="sound_effects", text="soft woody UI click, 80ms, no reverb, neutral pitch", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="warm major-third coin pickup, 300ms, light reverb", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="punchy low-mid player damage hit, slight detune, 200ms, no tail", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fingertip taps a small wooden button, soft woody click, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a small gold coin drops onto a wooden table, bright metallic ting with a short ring, close-mic, dry, no music, no voices.", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fist hits a padded leather vest, low-mid thump, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
 ```
 
-`capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
+`capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s (1 s for Stable Audio 3 SFX). Leave out `modelId` so the person's approved default model runs. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
 
 Ask first:
 

package/library/skills/audio-direction/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/audio-direction
 kind: skill
-version: 1.0.6
+version: 1.0.7
 summary: Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md.
 use_when:
   - defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan

package/library/skills/export-and-ship/SKILL.md

@@ -299,6 +299,8 @@ Per platform, point the user at the correct upload path:
   - Per platform, the store takes: iPhone, Android, macOS and Windows in the Summer apps = one summer.games bundle (`summer_export_game` `targets`, format `bundle`; no template, no signing; a game without a server targets `ios`/`android` only). Web = an HTML5 `.zip` on Summer's WebGPU Forward+ template (`targets:["web"]`; the project must render with Forward+ or Mobile). A macOS or Windows download for the store page = `targets:["macos"]` or `["windows"]` with format `download`. Download exports need the template: `summer_export_templates` `install` fetches it from Summer's CDN.
   - Hosted games: if `summer_export_game` fails with "… is in the source graph's authority_engine domain, which the client pack leaves out", an authority root in `source-domains.json` holds a file the client loads (often the composition `.tres`). Narrow that root to the server-only files, or move the shared file under a `shared` path, then export again. Every exporter message is in the `multiplayer-publish` skill's export-errors.md; the folder rules are in `multiplayer-project`.
   - Every summer.games bundle: export with the released Summer editor from the download page, never a development build, and export again after updating Summer. Otherwise its scripts can fail to compile on players' devices and the game opens to an empty window, though every upload check passes. `release-readiness` check 7 proves it.
+  - Every file the game reads by path at run time (`FileAccess`, `DirAccess`, `load_from_file`) that Summer doesn't import, such as a `.bin` or `.json`, must match the **summer.games** preset's own `include_filter` (Resources > Filters to export non-resource files/folders); a filter on another preset doesn't carry over. A left-out file is no export error, it is just missing on players' devices. Never use `SystemFont` for phone text: on iPhone it draws every glyph as a box. `release-readiness` check 8 lists the pack.
+  - iPhone and Android bundles: the Summer Games apps start only exports on their Summer version line (same MAJOR.MINOR, patch no newer). Export with the current Summer release and export again after every Summer minor update, or players see "The game could not start" on phones while desktop works. `release-readiness` check 9.
   - Hosted games, before the upload: a clean export does not prove players can join. Run `release-readiness` on the `.zip`: the bundle's `server.pck`, started with no scene, must load the authority scene (the server preset needs the `summer_authority` custom feature), and `Summer.initialize` must pass no hard-coded Game ID. Otherwise every online join fails with `world_start_timeout`.
   - Store page art: key art, covers and icons carry no text, logos or UI (the store page shows the title). Screenshots are real gameplay and may show the game's own HUD; add no captions, logos or overlays. Capture them with `summer_capture_gameplay` (offscreen, no editor needed; `resolution` `1920x1080`, or `1080x1920` for portrait; get past a title menu with the game's own flags in `args`, e.g. `["--autostart"]`, or `steps` such as `[{"press":"Play"},{"wait":3000},{"shot":true}]`), or `summer_screenshot` target `game` while the editor runs the game.
 - **Steam:** `steamcmd` + Steam Pipe (`builder_app_xxx.vdf`). Set up depots first in Steamworks.

package/library/skills/multiplayer-publish/SKILL.md

@@ -141,7 +141,9 @@ scene the pack will start; step 4d checks that. The `Exported by Summer`
 line must name a released Summer: export with the released editor from the
 download page, never a development build, and export again after you update
 Summer. Players' apps run the packs on the released Summer of that version;
-step 4e checks it. Every
+step 4e checks it. The Summer Games apps for iPhone and Android start only
+exports on their own MAJOR.MINOR, so export with the current Summer release
+(`release-readiness` check 9). Every
 result message and every export error, with its fix, is in
 [export-errors.md](export-errors.md).
 
@@ -265,8 +267,10 @@ of `.zip`. That writes `client.pck` alone.
 Right after the Build is released, open the game in a Summer Games app,
 join online and play until you are in the game, before players hear about
 the update. A wrong Game ID only fails under a real hosted launch, so
-nothing before this step catches it. An agent can't do this; ask the user
-and record the result. The whole list of checks before a release is
+nothing before this step catches it. Keep playing, signed in, for at least 3
+minutes: the game must not close and the player must stay signed in
+(`release-readiness` check 10). An agent can't do this; ask the user and
+record the result. The whole list of checks before a release is
 `release-readiness`, and the creator docs have it at
 https://docs.summerengine.com/publishing/release-readiness.
 
@@ -293,7 +297,7 @@ Use step 4d to see which scene runs.
 - [ ] The bundle's `server.pck`, run with no scene, loads the authority scene first.
 - [ ] `Exported by Summer` names a released Summer, and the bundle's `client.pck` run on that release prints no `SCRIPT ERROR`, `Parse Error` or `Failed to load script`.
 - [ ] Every `Summer.initialize` call passes no Game ID.
-- [ ] After release: a real online join reaches the game (`release-readiness`).
+- [ ] After release: a real online join reaches the game, and a signed-in player keeps playing for 3 minutes (`release-readiness` checks 2 and 10).
 - [ ] Local Play passed with the same project.
 
 ## Common mistakes

package/library/skills/release-readiness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release-readiness
-description: "Before releasing a Summer game version, prove players can play it: server scene, online join, saved progress, no fixed Game ID, a released Summer compiles it."
+description: "Before releasing a Summer game version, prove players can play it: server scene, online join, progress, Game ID, released Summer, packed files, app version."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
@@ -78,7 +78,8 @@ failures:
 
 Checks 1 and 2 apply to every game with a server (`summer.build.json` names
 a `server.exportPreset`). Checks 3 and 4 apply to every game with online
-play. Checks 5, 6 and 7 apply to every game.
+play. Checks 5 to 8 and 10 apply to every game. Check 9 applies to every
+bundle for iPhone or Android.
 
 ### 1. The server pack starts the authority scene
 
@@ -242,6 +243,120 @@ https://summerengine.com/download (or, with their OK, run
 `summer install --yes`). Export again with it, and rerun this check on the
 new `.zip` before you upload it.
 
+### 8. Every file the game reads at run time is in the pack
+
+**Why.** The export packs scenes, scripts and imported assets. A file the
+game opens itself by path (`FileAccess`, `DirAccess`, `load_from_file`,
+`FontFile.load_dynamic_font`, `ConfigFile.load`) that has no `.import`
+beside it, such as a `.bin`, `.json` or `.txt`, is a non-resource file. It
+goes into the pack only when the preset's `include_filter` (**Resources >
+Filters to export non-resource files/folders**) matches it and
+`exclude_filter` doesn't. Each preset has its own filters: the summer.games
+preset doesn't inherit one set on another preset. A file left out is not an
+export error; on players' devices `FileAccess` just returns nothing and the
+game's fallback runs. Fonts show it first: in the Summer Games app on iPhone
+a `SystemFont` has no system fonts to use, so every glyph draws as a box,
+while the editor, Local Play and desktop find a system font and look right.
+A real release shipped this way: its font file was missing from the
+uploaded pack, and every letter on iPhone was a box.
+
+**Check it.**
+
+1. Find every read by path:
+   `grep -rn -E 'FileAccess\.|DirAccess\.|load_from_file|load_dynamic_font|ConfigFile' --include=*.gd .`
+   Note each `res://` file or folder they read; skip `user://` (saves). A
+   file is raw when no `<file>.import` sits beside it.
+2. Check the filters:
+   `grep -n -E '^name=|^include_filter=|^exclude_filter=' export_presets.cfg`.
+   The summer.games preset's `include_filter` must match each raw file the
+   client reads, and its `exclude_filter` must not. Do the same on the
+   server preset for files the authority reads.
+3. List the pack. Save this script **outside** the project, for example as
+   `~/list_pack.gd`:
+
+   ```gdscript
+   extends SceneTree
+   # Prints one "PACK res://..." line per file in the pack mounted with --main-pack.
+   func _init() -> void:
+       _walk("res://")
+       quit()
+
+   func _walk(dir: String) -> void:
+       var d := DirAccess.open(dir)
+       if d == null:
+           return
+       d.include_hidden = true
+       for f in d.get_files():
+           print("PACK ", dir.path_join(f))
+       for s in d.get_directories():
+           _walk(dir.path_join(s))
+   ```
+
+   ```sh
+   perl -e 'alarm shift; exec @ARGV' 60 <summer> --headless --main-pack build/bundle/client.pck --script ~/list_pack.gd > build/client-pack.txt 2>&1
+   grep -Fx 'PACK res://fonts/MyFont.bin' build/client-pack.txt   # once per raw file from step 1
+   ```
+
+   Every raw file must print its line. No line means the file is not in the
+   pack, whatever the preset says. List `server.pck` the same way for files
+   the authority reads.
+4. `grep -rn SystemFont --include=*.gd --include=*.tscn --include=*.tres .`
+   must find nothing on a path phone players reach, fallbacks included.
+5. After publishing, open the game on an iPhone in the Summer Games app and
+   look at the title and one menu: letters, not boxes. An agent can't do
+   this step; report it as **not run** and ask the user.
+
+**Fix.** Add each missing file to the summer.games preset's non-resource
+filter (for example `fonts/*.bin`), or import it as a resource instead.
+Ship the font in the project (an imported `.ttf`/`.otf`, or raw bytes that
+step 3 proves are packed) and fall back to `ThemeDB.fallback_font`, Summer's
+built-in font, never to `SystemFont`. Export again and rerun steps 3 and 5.
+
+### 9. Export with the Summer version line the Summer Games apps run
+
+**Why.** The Summer Games apps for iPhone and Android carry Summer inside
+the app and download none. An app starts a game only when the export's
+`summerVersion` has the app's MAJOR.MINOR (for example `0.7`) and a patch no
+newer than the app's. A `0.6.x` export doesn't start in an app that carries
+`0.7`: the player sees **The game could not start**. The desktop app fetches
+the right Summer for each game, so the game can run on Mac and Windows and
+still fail on every phone. The upload checks don't catch it.
+
+**Check it.**
+
+1. Read the stamp and platforms:
+   `python3 -c 'import json; b=json.load(open("build/bundle/summer-bundle.json")); print(b["export"]["summerVersion"], b["client"]["targetPlatforms"])'`
+2. If `targetPlatforms` lists `ios` or `android`, the first two numbers of
+   `summerVersion` must match the current Summer release, shown on
+   https://summerengine.com/download and in Help > About after updating.
+3. After publishing, open the game on a phone in the Summer Games app, as in
+   check 2. "The game could not start" there, while desktop works, is this
+   check failing.
+
+**Fix.** Ask the user to update Summer to the current release (or, with
+their OK, run `summer install --yes`). Export again, upload it as a new
+version and promote it. Do this again after every Summer minor update
+(0.6 to 0.7), because the apps move to the new line.
+
+### 10. A signed-in player keeps playing for three minutes
+
+**Why.** While the game runs, it calls Summer services for the signed-in
+player: analytics, player data, the store. A short test can end before the
+first of those calls. A real release closed for every player about a minute
+in, with "That link can't be opened", and left them signed out: a Summer
+service refused the player's sign-in, and the app ended play. The fault was
+Summer's, not the game's, and no check on the game's files could see it.
+
+**Check it.** After publishing, sign in to a Summer Games app on a phone,
+open the released version and play it for at least 3 minutes, through at
+least one analytics event. The game must not close, and the player must
+still be signed in afterwards. Do it in each Summer Games app the game
+targets. An agent can't do this step; report it as **not run** and ask the
+user, then record what they saw.
+
+**Fix.** Nothing in the game. Ask the user to report it to Summer with the
+game's name, the app and the time it happened.
+
 ## Troubleshooting
 
 ### Every online join fails with `world_start_timeout`, but Local Play works
@@ -263,6 +378,27 @@ export, and the scripts use something the released version doesn't have.
 Re-export with the current Summer release, upload the new version and
 promote it.
 
+### Text shows as boxes on iPhone
+
+Every letter draws as an empty box in the Summer Games app on iPhone, while
+the game looks right on desktop. The game most likely reads a font file that
+isn't in the pack and falls back to `SystemFont`. Run check 8.
+
+### "The game could not start" on iPhone or Android
+
+The game works on desktop, but the phone app says "The game could not
+start". The `.zip` most likely comes from a Summer version line the app
+doesn't carry. Run check 9, then export again with the current Summer
+release, upload and promote.
+
+### The game closes after about a minute and the player is signed out
+
+The Summer Games app closes the game 20 to 60 seconds into play with "Play
+paused" or "That link can't be opened", and the player finds they are signed
+out. A Summer service refused the player's sign-in while the game played.
+This is Summer's fault, not the game's: see check 10, and ask the user to
+report it with the time it happened.
+
 ### The game server's log is empty
 
 An empty server log is not proof that the server hung or never started. A
@@ -295,4 +431,7 @@ here would have caught:
 - [ ] 5. Players can get back to the title from inside a session, online and offline.
 - [ ] 6. Every `Summer.initialize` passes no ID, or an ID the game got from Summer.
 - [ ] 7. The export stamp names a released Summer and its `engineSha`, and `client.pck` run on that released Summer prints no `SCRIPT ERROR`, `Parse Error` or `Failed to load script`.
+- [ ] 8. Every file the game reads by path has a `PACK res://…` line in the listing of `client.pck` (or `server.pck`), no phone text uses `SystemFont`, and text shows as letters on an iPhone (or is reported as not run).
+- [ ] 9. For an iPhone or Android bundle, `summerVersion` has the current Summer release's MAJOR.MINOR.
+- [ ] 10. A signed-in player played the released version for 3 minutes in each Summer Games app, through an analytics event, without the game closing or being signed out (or it is reported as not run).
 - [ ] One line per check reported to the user before anything is changed.

package/library/skills/release-readiness/resource.yaml

@@ -1,13 +1,16 @@
 id: skill/release-readiness
 kind: skill
 version: 1.0.0
-summary: "Before releasing a Summer game version, prove players can play it: server scene, online join, saved progress, no fixed Game ID, a released Summer compiles it."
+summary: "Before releasing a Summer game version, prove players can play it: server scene, online join, progress, Game ID, released Summer, packed files, app version."
 use_when:
   - "before uploading, promoting or releasing a new version to players: is it ready to release"
   - "every online join fails with world_start_timeout, or the hosted server's log is empty, while Local Play works"
   - "Summer.initialize fails with game_identity_mismatch: the initialized Game ID does not match hosted runtime context"
   - "checking that a hosted game's server.pck starts the authority scene and not the title screen"
   - "players get a blank or black screen when they open the released game, but it runs in the editor: client scripts fail with Parse Error or Failed to load script"
+  - "text shows as boxes on iPhone but looks fine on desktop: a font or other file read with FileAccess is missing from the pack, or SystemFont is used"
+  - "the Summer Games phone app says the game could not start, but it works on desktop: the game's Summer version line differs from the app's"
+  - "the game closes about a minute into play with Play paused or That link can't be opened, and the player is signed out"
   - "a game release failed for players and the check that would have caught it needs adding"
 do_not_use_when:
   - "only producing a local export for a jam or prototype nobody else plays — skill/export-and-ship"