summer-engine 3.7.0 → 3.8.0

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

@@ -106,9 +106,9 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     if (!res.ok) {
         let message = formattedApiErrorMessage(res.status, data);
         if (res.status === 402) {
-            message =
-                (data.message || "Insufficient credits.") +
-                    "\nTop up at: https://www.summerengine.com/dashboard\nOr upgrade your plan at: https://www.summerengine.com/pricing";
+            // One link: the Add credits step in Studio (no plan needed). Newer servers already put it in the message.
+            const base = String(data.message || "Not enough credits.");
+            message = base.includes("/studio/credits") ? base : `${base}\nAdd credits: https://summerengine.com/studio/credits`;
         }
         if (res.status === 401) {
             message =

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.7.0",
+  "version": "3.8.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": {
@@ -113,6 +113,8 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-apps/",
+    "./library/skills/summer-apps-design/",
     "./library/skills/summer-friends/",
     "./library/skills/summer-leaderboards/",
     "./library/skills/summer-match-results/",

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 (104 tools)
+## Tool surface (119 tools)
 
 ### Project files (4)
 
@@ -262,6 +262,28 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 |---|---|
 | `summer_library_feedback` | Report library-entry outcomes (worked/wrong/outdated/...) so entries get fixed and re-ranked. Fire-and-forget with a 1s cap; enum-first schema with no field for project files, chat content, or code; honors `SUMMER_NO_TELEMETRY=1` and `DO_NOT_TRACK=1`. |
 
+### Summer Apps (13)
+
+Team tools inside Summer Studio that agents build: shared, live on the team's data and engine. Load the `summer-apps` and `summer-apps-design` skills first.
+
+| Tool | Use |
+|---|---|
+| `summer_app_guide` | The build guide: when to build, Layout vs code, build loop, manifest, SDK, UI kit, layout format, design rules, worked examples. |
+| `summer_app_list` | The apps in the person's workspaces. |
+| `summer_app_create` | New scratch app; the person's Studio tab opens it. |
+| `summer_app_publish` | New immutable version from a local `dir`, `files` or a `layout`, plus the manifest. |
+| `summer_app_get` | Manifest, current files and a data summary. |
+| `summer_app_update` | Rename, move to a folder, keep, archive or restore an app. |
+| `summer_app_events` | Long-poll (up to 50 s) what the app sends agents, errors, feedback and tool calls. |
+| `summer_app_page` | Read, fill and press the open app's declared fields and buttons. |
+| `summer_app_screenshot` | See the app without the person: a headless, read-only render (PNG) with console, errors, refused calls and the declared page; `width` 390 for a phone, `theme` dark, `out` saves the PNG. |
+| `summer_app_data` | Read or write the app's shared collections; no app needs to be open, the team sees writes live. |
+| `summer_app_tools` | The app's declared agent tools. |
+| `summer_app_call` | Run an agent tool inside the person's open app; `app_not_open` otherwise. |
+| `summer_app_report_gap` | Report an SDK capability an app needed and did not have. |
+| `summer_app_dock` | Dock an app in the editor (left, right, bottom), close it, list docks; `engine_lacks_op` on engines without app docks. |
+| `summer_enable_plugin` | Enable an editor plugin (`res://addons/<name>/`) and get the real load result (`enabled`, autoloads, or a failure `code`); older engines answer `queued: true, enabled: null` instead of claiming success. |
+
 ## Common pattern
 
 Every scene-touching skill should follow this loop:

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 123 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 125 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -29,7 +29,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [runtime](#runtime) (1)
 - [scenes](#scenes) (12)
 - [scripting](#scripting) (2)
-- [ui](#ui) (1)
+- [tools](#tools) (1)
+- [ui](#ui) (2)
 - [vfx](#vfx) (9)
 - [video](#video) (3)
 
@@ -248,10 +249,17 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [gdscript-patterns](./gdscript-patterns/SKILL.md) ★ | GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming. | conventions |
 | [*save-load*](./save-load/SKILL.md) (preview) | Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks. | gameplay |
 
+## tools
+
+| skill | when to use | also |
+|---|---|---|
+| [*summer-apps*](./summer-apps/SKILL.md) ★ (preview) | Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools. | ui, agent-workflow |
+
 ## ui
 
 | skill | when to use | also |
 |---|---|---|
+| [*summer-apps-design*](./summer-apps-design/SKILL.md) ★ (preview) | How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist. | tools |
 | [ui-basics](./ui-basics/SKILL.md) ★ | Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling. | ux |
 
 ## vfx

package/library/skills/sound-effect/SKILL.md

@@ -106,6 +106,8 @@ summer_generate_audio(capability: "sound_effects", text: "<prompt>", durationSec
 
 Leave out `modelId` so their approved default runs. The description goes in `text`, not `prompt` (`prompt` gives a 400 `text_required` here).
 
+No Summer project (an asset-only request, or the engine is not installed or not running): stop here. The clips are in the person's Summer library; give them the `audioUrl` of each approved version and skip steps 7 and 8.
+
 ### 7. Import
 
 ```

package/library/skills/summer-apps/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: summer-apps
+description: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: tools
+user-invocable: true
+allowed-tools: Read Write Edit Glob summer_app_guide summer_app_list summer_app_create summer_app_publish summer_app_get summer_app_update summer_app_events summer_app_page summer_app_screenshot summer_app_data summer_app_tools summer_app_call summer_app_dock summer_app_report_gap
+---
+
+# Summer Apps
+
+A Summer App is a tool the person's team uses inside Summer Studio: shared with
+the workspace, live on its assets, game data and engine, dockable in the editor.
+You build it in minutes; the team keeps it.
+
+## First: does Summer already do it?
+
+A custom app is something the team has to maintain. Before you build one, check whether
+Summer already does the job: Studio features (the asset library with its collections and
+groups, Pick one and sound choices, Grow dashboards, Team) and the existing `summer_*` MCP
+tools. If it does, use that and tell the person where it lives.
+
+Build an app only when the need is real and Summer lacks it, or as a Scratch throwaway (a
+quick asset review, a UI prototype) that you call throwaway when you make it, and archive
+when it is done (`summer_app_update {appId, status: "archived"}`). When
+something is missing natively, report it with `summer_app_report_gap` (and
+`summer_library_feedback` when a library entry fell short), so Summer can build it for
+everyone.
+
+| Ask | Do |
+| --- | --- |
+| "Let me pick from these 12 sword sounds" | Pick one: `summer_generate_sfx_choices`, or put the sounds in a library collection. No app. |
+| "Group our Studio assets into a moodboard for the forest level" | Organize them with the asset library's collections and groups. No app. |
+| "A weapon balance table that writes res://data/weapons.json" | Build an app: nothing in Summer edits game data with the team's balance rules. |
+
+## When to build one
+
+- The person asks for a tool ("build us a loot balance tool", "track every creature
+  from concept to in-engine", "a board to review playtest clips").
+- They need a UI to decide or edit something they will come back to.
+- Not for a one-off answer: reply in chat instead.
+- Not when Summer already does it (above).
+
+## Layout or code
+
+- **Layout** (`format: "layout"`): a JSON layout of kit nodes. Quick, throwaway,
+  always on brand. Use it to ask the person to pick, rate or fill something now.
+- **Code** (default): `index.html` + JS/CSS with the Summer SDK and UI kit. Use it
+  for state, editing, shared data, generation or engine access.
+
+## Start from the working app
+
+Read these before writing code; they are exact:
+
+- [minimal-app.md](minimal-app.md): a complete working app (manifest, `index.html`,
+  `app.js`) built from kit components, using shared data, live changes, the viewer, `page.declare`, an
+  agent event, an agent tool and frame-move state. Copy it and change it.
+- [sdk-reference.md](sdk-reference.md): every SDK call with its exact arguments and
+  return shape.
+- [manifest.md](manifest.md): every manifest field.
+- The kit's component catalog (every `<summer-*>` element with attributes, events and a
+  copyable example) is `summer_app_guide` section `kit`, also at `/summer-ui/v1/catalog.json`
+  on the app host. Copy its examples instead of inventing markup.
+
+To see an app, publish it and call `summer_app_screenshot {appId}`: Summer renders it headless
+with the person's data and returns the picture plus the console, uncaught errors, refused calls
+and the fields and buttons it declared. No Studio tab needed; the person sees it at
+`/studio/apps/<appId>` (`summer_app_create` opens it for them). Opening `index.html` on its own
+never connects. There is no offline host: do not build one or mock the SDK.
+
+The app is served from its own host, apps.summerengine.app. Load the SDK and the kit as
+ES modules with root paths: `<script type="module" src="/summer-sdk/v1.js">` and
+`<script type="module" src="/summer-ui/v1/ui.js">`. Then `await summer.ready` before
+the first call, and reach data only through `summer.data.collection(name)`.
+
+## The loop
+
+1. `summer_app_guide` (whole once per session; later one `section`). Load the
+   `summer-apps-design` skill for how it must look.
+2. `summer_app_create {name, purpose, format}`. The person's Studio tab opens it.
+3. Write the files in a local folder, then `summer_app_publish {appId, dir, manifest, note}`
+   (or `layout`). Each publish is an immutable version the tab boots. A publish
+   error names the file or rule: fix it and publish again.
+4. Seed starter data with `summer_app_data` (`ops` plus `"as": "seed"`) when the app should
+   start full. Seed rows belong to the team and show no author.
+5. Look at it: `summer_app_screenshot {appId}`, then `width: 390` (phone) and `theme: "dark"`.
+   Fix every error and console line it reports, publish again, look again. It is read-only:
+   writes, sends and paid calls are refused there and work in Studio.
+6. `summer_app_events {appId, after}` waits for what the app sends you
+   (`summer.agent.send`), errors (uncaught and `console.error`) and feedback. Act on them;
+   pass the cursor on.
+7. Change the app by publishing again; `summer_app_get` returns the current files.
+
+## Data is the API
+
+Read and write an app's shared collections with `summer_app_data`. It works with
+no app open, and everyone in the app sees your edits live. "Nerf the bow in our
+balance sheet" is a data write, not a click.
+
+Declare each collection's record shape in the manifest `collections`; `summer_app_tools`
+and `summer_app_data` reads return it, so any agent knows what a record looks like.
+
+```json
+{ "appId": "<id>", "ops": [
+  { "op": "patch", "collection": "items", "recordId": "bow", "patch": { "damage": 36 }, "ifRevision": 4 },
+  { "op": "put", "collection": "notes", "recordId": "n-17", "data": { "text": "Boss too long", "status": "open" } },
+  { "op": "remove", "collection": "notes", "recordId": "n-3" }
+] }
+```
+
+Up to 100 ops per call. Without `ops`, `summer_app_data` reads (`collection`, `after`, `limit`);
+removed records are not returned. Your writes are recorded as `actor { kind: "agent" }` (and
+as `createdBy` on records you create), so the app can show which rows an agent made. Add
+`"as": "seed"` for starter data that belongs to the team (`kind: "seed"`, no author). `patch` merges keys
+(`null` removes one); `ifRevision` guards against overwriting a newer change.
+
+## Agent tools
+
+Logic that lives in the app (a balance formula, an export) can be exposed in the
+manifest `agentTools` and implemented with `summer.agent.tool(name, handler)`.
+`summer_app_tools` lists them; `summer_app_call` runs one inside the person's open
+app and answers `app_not_open` otherwise. Prefer data for plain reads and edits.
+
+## Rules
+
+- Declare only the permissions the app uses; declare every `engineFiles` path and
+  every `agentEvents` name. A missing one fails at runtime with `permission_missing`.
+- The app runs sandboxed (`allow-scripts allow-forms allow-popups allow-modals
+  allow-downloads`, never `allow-same-origin`): no cookies, no `localStorage`, no network
+  unless the workspace allows a domain. Keep state in `summer.data`.
+- Paid SDK calls spend the credits of the person using the app. Say so before
+  building an app that generates.
+- Use real data (`summer.data`, `summer.assets`, `summer.engine.readFile`), never
+  placeholder numbers.
+- Studio moves an idle app to a fresh frame every few minutes. Keep UI state you care
+  about in shared data, or return it from `summer.app.onSnapshot(() => state)` (up to
+  256 KB) and read it back from `(await summer.ready).restored`. Wrap Web Audio playback
+  in `summer.app.busy(true)` / `summer.app.busy(false)` so a long sound is not cut;
+  `<audio>` and `<video>` count on their own.
+- Call `summer.page.declare` so agents can read and use the UI; mark delete,
+  publish, pay and send actions `critical`.
+- When the SDK cannot do what the app needs, say so and call
+  `summer_app_report_gap`.
+- `summer_app_dock` docks an app in the editor; on engines without app docks it
+  returns `engine_lacks_op`: open the app in the Studio tab instead.
+
+## Done means
+
+The app is published; `summer_app_screenshot` shows it with real data in light, dark and at
+390 px with no errors; its states (loading, empty, error) work; and the person knows what it
+does and where its data goes.

package/library/skills/summer-apps/manifest.md

@@ -0,0 +1,57 @@
+# The Summer App manifest
+
+Sent as `manifest` on every `summer_app_publish` and written into the app as
+`summer.app.json`. Unknown keys and unknown permissions are refused with a message that
+names them. Every field:
+
+```json
+{
+  "name": "Loot table",
+  "purpose": "Balance item stats and write them to res://data/items.json",
+  "permissions": ["data", "assets:read", "generate", "ai", "team:read", "engine:read", "engine:write"],
+  "engineFiles": ["res://data/items.json"],
+  "collections": {
+    "items": {
+      "description": "One weapon or armour piece",
+      "fields": {
+        "name": { "type": "string", "required": true },
+        "damage": { "type": "number", "description": "Damage per hit" },
+        "speed": { "type": "number", "description": "Attacks per second" },
+        "tags": { "type": "array" }
+      }
+    }
+  },
+  "agentEvents": ["items.written"],
+  "agentTools": [
+    {
+      "name": "nerf_item",
+      "description": "Lower one item's damage by a percent",
+      "input": {
+        "type": "object",
+        "properties": { "id": { "type": "string" }, "percent": { "type": "number" } },
+        "required": ["id", "percent"]
+      }
+    }
+  ],
+  "surface": "both",
+  "dock": { "preferred": "bottom" },
+  "plugin": { "name": "loot_tools" }
+}
+```
+
+| Key | Rules |
+|---|---|
+| `name` | Required, 1-80 characters. |
+| `purpose` | Up to 280 characters: what the tool does and where its data goes. |
+| `permissions` | Only these: `data`, `assets:read`, `assets:write`, `generate`, `ai`, `projects:read`, `team:read`, `grow:read`, `engine:read`, `engine:write`, `choices`. `engine:write` includes `engine:read`; `assets:write` includes `assets:read`. No permission is needed for `app.*`, `agent.*`, `page.*` and `team.presence`. |
+| `engineFiles` | Up to 50 `res://` paths `engine.readFile` / `writeFile` may touch. |
+| `collections` | Up to 50, keyed by collection name (lowercase `a-z 0-9 _ . -`). Each: `description`, `fields` (up to 50, name `[A-Za-z_][A-Za-z0-9_]*`) with `type` (`string`, `number`, `integer`, `boolean`, `object`, `array`, `any`), `description`, `required`. Descriptive: agents and people read it; writes are not rejected for it. |
+| `agentEvents` | Up to 50 names (`a-z 0-9 _ . -`) the app sends with `summer.agent.send`. |
+| `agentTools` | Up to 20: `name` (`a-z 0-9 _`, max 64), `description` (max 1,000), `input` (JSON Schema, up to 8 KB). |
+| `surface` | `page` (the Studio app page, default), `dock` (an editor dock) or `both`. A dock layout must work from 320 px wide; docked apps get selection and scene events (`summer.engine.onEvent`). |
+| `dock` | `{ "preferred": "left" \| "right" \| "bottom" }`. |
+| `plugin` | `{ "name": "<folder>" }`: the app may also write `res://addons/<folder>/`. |
+| `entry` | Always `index.html` (you can leave it out). |
+
+The whole manifest is at most 200 KB. A code app's bundle: `index.html` at the root, at most
+300 files, 10 MB, 5 MB per file.

package/library/skills/summer-apps/minimal-app.md

@@ -0,0 +1,183 @@
+# A complete minimal Summer App
+
+A working code app: shared notes for a playtest. Copy it, rename things, then grow it.
+It shows every piece an app needs: the manifest, loading the SDK and kit, waiting for
+the host, shared data (list, put, live changes), who changed a row (person or agent),
+an edit flow (dialog + form with setValues), status badges, an error with Try again, the
+page declaration, an agent event, an agent tool and frame-move state.
+
+Publish it with `summer_app_publish {appId, dir, manifest, note}` where `dir` holds
+`index.html` and `app.js`, or pass the same two as `files`. The page, sections, inputs,
+table, notice and empty text are kit components (`summer_app_guide` section `kit`, or
+`/summer-ui/v1/catalog.json` on the app host); no app CSS is needed.
+
+## The manifest (send it as `manifest`)
+
+```json
+{
+  "name": "Playtest notes",
+  "purpose": "Tester notes per level. Notes live in this app's shared data.",
+  "permissions": ["data"],
+  "collections": {
+    "notes": {
+      "description": "One remark from a playtest",
+      "fields": {
+        "text": { "type": "string", "required": true, "description": "What the tester said" },
+        "level": { "type": "string", "description": "Level name, e.g. bridge" },
+        "status": { "type": "string", "description": "open or fixed" },
+        "author": { "type": "string", "description": "Who added it" }
+      }
+    }
+  },
+  "agentEvents": ["note.added"],
+  "agentTools": [
+    {
+      "name": "add_note",
+      "description": "Add a playtest note",
+      "input": {
+        "type": "object",
+        "properties": { "text": { "type": "string" }, "level": { "type": "string" } },
+        "required": ["text"]
+      }
+    }
+  ]
+}
+```
+
+## index.html
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Playtest notes</title>
+<!-- Both are ES modules on the app's own host (apps.summerengine.app). Root paths, type="module". -->
+<script type="module" src="/summer-sdk/v1.js"></script>
+<script type="module" src="/summer-ui/v1/ui.js"></script>
+</head>
+<body>
+<summer-page heading="Playtest notes" purpose="Tester notes per level, shared with your team and your agent.">
+  <summer-button slot="actions" id="add" variant="primary" icon="plus">Add note</summer-button>
+  <summer-section heading="Notes">
+    <summer-notice id="error" tone="error" action="Try again" action-icon="refresh-cw" hidden></summer-notice>
+    <summer-table id="table" row-key="id" sortable clickable loading
+      empty-text="No notes yet. Add the first one, or ask your agent to add the testers' notes."></summer-table>
+  </summer-section>
+  <summer-dialog id="dialog" heading="Note" description="Shared with your team and your agent.">
+    <summer-form id="form" submit-label="Save note">
+      <summer-text-input label="Note" name="text" multiline required></summer-text-input>
+      <summer-grid columns="2">
+        <summer-text-input label="Level" name="level" placeholder="bridge"></summer-text-input>
+        <summer-select label="Status" name="status" options='[{"value":"open","label":"Open"},{"value":"fixed","label":"Fixed"}]'></summer-select>
+      </summer-grid>
+    </summer-form>
+  </summer-dialog>
+</summer-page>
+<!-- app.js runs after the SDK module (module scripts run in order). -->
+<script type="module" src="app.js"></script>
+</body>
+</html>
+```
+
+## app.js
+
+```js
+const notes = summer.data.collection("notes");
+const info = await summer.ready;   // { viewer: { userId, name }, params, restored, ... }
+const $ = (id) => document.getElementById(id);
+const table = $("table"), dialog = $("dialog"), form = $("form"), error = $("error");
+let editing = null;                 // the note id being edited, or null for a new one
+
+table.columns = [
+  { key: "text", label: "Note", priority: "primary" },
+  { key: "level", label: "Level" },
+  { key: "status", label: "Status", badges: { open: "warn", fixed: "ok" } },   // one badge tone per value
+  { key: "by", label: "By", type: "muted" },
+];
+
+async function load() {
+  table.setAttribute("loading", "");
+  try {
+    const page = await notes.list({ limit: 500 });   // removed notes are never listed
+    table.rows = page.records.map((r) => ({
+      id: r.recordId,
+      ...r.data,
+      // createdBy: who made the row ({ userId, kind: "person" | "agent" | "seed", agent?, via? });
+      // later edits do not change it (actor is the last writer). Seed rows have no author.
+      by: r.createdBy?.kind === "agent" ? `${r.createdBy.agent ?? "Agent"} (agent)` : r.data.author ?? "",
+    }));
+    error.hidden = true;
+  } catch (e) {
+    error.setAttribute("text", `Could not load notes: ${e.message}`);
+    error.hidden = false;
+  } finally {
+    table.removeAttribute("loading");
+  }
+}
+error.addEventListener("action", load);   // the notice's "Try again" button
+
+function openEditor(row) {
+  editing = row?.id ?? null;
+  form.setValues(row ?? { text: "", level: "", status: "open" });
+  dialog.show();
+}
+$("add").addEventListener("click", () => openEditor(null));
+table.addEventListener("summer-row", (event) => openEditor(event.detail.row));   // click a row to edit
+
+form.addEventListener("submit", async (event) => {
+  const { text, level, status } = event.detail.values;   // numbers come as numbers, empty as null
+  form.setAttribute("busy", "");
+  try {
+    const id = editing ?? crypto.randomUUID();
+    await notes.put(id, { text, level: level ?? "", status: status ?? "open", author: info.viewer.name ?? "someone" });
+    if (!editing) await summer.agent.send("note.added", { id, text, level });   // name is in manifest.agentEvents
+    dialog.close();
+    summerUI.toast("Note saved");
+  } catch (e) {
+    form.setAttribute("error", e.message);
+  } finally {
+    form.removeAttribute("busy");
+  }
+});
+
+// Live: every change by a teammate or an agent arrives as { revision, actor, ops } (or { reset: true }).
+notes.subscribe(() => load());
+
+// Agent tool: summer_app_call { tool: "add_note", input: { text, level } } runs this while the app is open.
+// Its writes are recorded as the calling agent's (actor.kind "agent", via "agent-tool").
+summer.agent.tool("add_note", async ({ text, level }, { agent }) => {
+  const id = crypto.randomUUID();
+  await notes.put(id, { text, level: level ?? "", status: "open", author: agent });
+  return { id };
+});
+
+// What agents can read and use with summer_app_page.
+summer.page.declare({ actions: [{ id: "add", label: "Add note", run: () => openEditor(null) }] });
+
+// Frame moves: Studio moves an idle app to a fresh frame every few minutes. Shared data survives on
+// its own; keep only UI state, such as an open editor.
+summer.app.onSnapshot(() => (dialog.hasAttribute("open") ? { editing, values: form.values } : null));
+if (info.restored?.values) {
+  editing = info.restored.editing;
+  form.setValues(info.restored.values);
+  dialog.show();
+}
+
+load();
+```
+
+Playing sound with Web Audio instead of `<audio>`? Wrap it so the frame is not moved
+mid-sound: `summer.app.busy(true)` when it starts, `summer.app.busy(false)` in the
+source's `onended`.
+
+## The agent side of the same app
+
+```json
+{ "appId": "<id>", "ops": [{ "op": "put", "collection": "notes", "recordId": "n-1", "data": { "text": "Boss fight too long", "level": "boss", "status": "open", "author": "agent" } }] }
+```
+
+That is a `summer_app_data` write: it works with the app closed, and the open app shows it
+through `notes.subscribe`. `summer_app_tools` and `summer_app_data` reads return the
+`collections` above, so an agent knows the record shape.

package/library/skills/summer-apps/resource.yaml

@@ -0,0 +1,36 @@
+id: skill/summer-apps
+kind: skill
+version: 0.1.0
+summary: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+use_when:
+  - the person asks for a tool for their team ("build us a loot balance tool", "a board to track creatures")
+  - the person needs a UI to decide, rate or edit something they will come back to
+  - reading or changing the data of an existing Summer App
+  - calling an app's agent tools or waiting for what an app sends
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+    - agent-workflow
+  modalities:
+    - ui
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps-design
+  tools:
+    - tool/app-guide
+    - tool/app-create
+    - tool/app-publish
+    - tool/app-events
+    - tool/app-data
+    - tool/app-call
+    - tool/app-dock
+source: official
+license: MIT
+status: preview
+recommended: true