summer-engine 3.7.0 → 3.8.0

package/library/skills/summer-apps/sdk-reference.md

@@ -0,0 +1,135 @@
+# Summer Apps SDK quick reference
+
+`window.summer`, loaded with `<script type="module" src="/summer-sdk/v1.js">` (the app's own
+host, apps.summerengine.app). The UI kit is `<script type="module" src="/summer-ui/v1/ui.js">`
+(stylesheet alone: `/summer-ui/v1/ui.css`). Use `type="module"` (a classic script still works but warns); other paths do not work. Calling `summer.data.list(name)` and the like rejects with `invalid` and says to use `summer.data.collection(name)`.
+
+The app runs in a sandboxed frame on that host:
+`sandbox="allow-scripts allow-forms allow-popups allow-modals allow-downloads"`, never
+`allow-same-origin`. So it is an opaque origin (no cookies, no `localStorage`), with no network
+unless the workspace allows a domain; the kit and SDK are served with CORS so the module
+scripts load. It only works inside Summer Studio. To preview, publish to a Scratch app and open
+it there (`/studio/apps/<appId>`). There is no offline or local host; do not build one or mock
+the SDK. Opening `index.html` on its own never connects, so `summer.ready` waits forever.
+
+Every call returns a promise and runs as the person using the app. Failures reject with
+`SummerError { code, message }`. Methods need the manifest permission in brackets.
+
+## Start
+
+| Call | Returns |
+|---|---|
+| `await summer.ready` | `{ app: { id, name, version, surface, format }, viewer: { userId, name }, permissions: string[], params: { [k]: string }, theme: "light"\|"dark", restored?: any }` |
+| `summer.app.viewer()` | `{ userId, name, image, role: "owner"\|"admin"\|"member", canManage, spentTodayMicro, dailyCapMicro }` |
+| `summer.app.info({ params })` | `{ app, version, manifest, params }` |
+| `summer.app.setTitle(title)`, `summer.app.notify(text)`, `summer.app.needsYou(count)`, `summer.app.open("/studio/...")` | `void` |
+| `summer.app.theme()` / `summer.app.onTheme(fn)` | `"light"\|"dark"` / stop function |
+| `summer.app.onSnapshot(() => state)` | stop function. `state` (JSON, up to 256 KB) comes back as `(await summer.ready).restored` after Studio moves the app to a fresh frame. |
+| `summer.app.busy(on)` | `void`. Wrap Web Audio playback in `busy(true)` / `busy(false)`; `<audio>` and `<video>` count on their own. |
+
+Use `(await summer.ready).viewer` for who is using the app; `summer.app.viewer()` is the same
+person plus role and spend. The kit applies Studio's light or dark theme by itself
+(`html.dark`): apps never toggle it. `theme()` / `onTheme` are only for your own drawing (canvas).
+
+## Shared data [data]
+
+There is no `summer.data.list(name)`. Always go through `summer.data.collection(name)`.
+
+```js
+const notes = summer.data.collection("notes");   // name: lowercase a-z 0-9 _ . - (max 48)
+```
+
+| Call | Returns |
+|---|---|
+| `notes.list({ limit = 200, after })` | `{ revision, records: Record[], next: string\|null, collections: [{ name, count }] }`. Removed records are never listed. Pass `next` as `after` for the next page (max 500 per page). |
+| `notes.get(id)` | `Record`, or `null` (also for a removed record) |
+| `notes.put(id, data, { ifRevision })` | `Write` (creates or replaces) |
+| `notes.patch(id, partial, { ifRevision })` | `Write` (shallow merge; `null` removes a key; creates if missing) |
+| `notes.remove(id, { ifRevision })` | `Write` |
+| `notes.subscribe((change) => …)` | stop function |
+| `summer.data.subscribe((change) => …)` | every collection |
+| `summer.data.commands({ requestId, baseRevision, ops })` | `Write`: up to 100 ops in one revision |
+
+```ts
+Record = { collection, recordId, data, revision, actor, createdBy, createdAt, updatedAt, deleted }
+Write  = { revision, operation: { revision, requestId, actor, ops, createdAt }, records: Record[], replayed }
+change = { revision, actor, ops: Op[] } | { revision, reset: true }      // on reset, list again
+actor  = { userId, kind: "person" | "agent" | "seed", agent?: "claude-code" | ..., via?: "agent-tool" }
+Op     = { op: "put", collection, recordId, data, ifRevision? }
+       | { op: "patch", collection, recordId, patch, ifRevision? }
+       | { op: "remove", collection, recordId, ifRevision? }
+```
+
+`ifRevision: n` applies only if the record is still at revision `n` (`0`: only if it does not
+exist); otherwise the call rejects with `conflict`. Record ids: letters, digits, `_ . : -`
+(max 128). Records are JSON up to 64 KB, 10,000 per collection, 50 collections.
+
+### Who changed it
+
+`actor.userId` is the account the write ran as, the same id as `ready.viewer.userId` and
+`app.viewer().userId`. `kind: "agent"` marks writes an agent made with `summer_app_data`, and
+writes your own code made while running an agent tool for `summer_app_call` (those also have
+`via: "agent-tool"`). Show agent-made rows (a small "by agent" label) so people know.
+
+`actor` is the last writer. `createdBy` (same shape) is who created the record and does not
+change on later edits, so take the "by agent" label from `createdBy.kind === "agent"`: it
+survives a person's edit. `kind: "seed"` is starter data an agent wrote for the team
+(`summer_app_data` with `as: "seed"`): show no author for it.
+
+## Agents
+
+| Call | Returns |
+|---|---|
+| `summer.agent.send(name, payload)` | `{ seq }`. `name` must be in `manifest.agentEvents`. Agents read it with `summer_app_events`. |
+| `summer.agent.tool(name, async (input, { agent }) => result)` | stop function. `name` must be in `manifest.agentTools`; `agent` is the calling agent's name. Data writes the handler makes are recorded as that agent's (`via: "agent-tool"`). `summer_app_call` runs it; return JSON (under 100 KB); a throw becomes `tool_failed`. |
+| `summer.agent.onMessage((message) => …)` | stop function |
+| `summer.page.declare({ fields, actions })` | promise. `fields: [{ id, label, kind: "text"\|"long-text"\|"number"\|"toggle"\|"choice", value, options?: [{ value, label }] (for choice), max?, hint?, set(value) }]`, `actions: [{ id, label, description?, critical?, run() }]`. Call it again when values change. Critical actions are pressed only by the person. |
+
+## Assets, generation, AI
+
+| Call | Permission | Returns |
+|---|---|---|
+| `summer.assets.search(q, { filters, limit })` | assets:read | matching assets |
+| `summer.assets.get(id)` | assets:read | one asset (`fileUrl`/`url`, `kind`, `title`, ...) |
+| `summer.assets.upload({ name, contentType, base64 })` | assets:write | the new asset |
+| `summer.assets.saveToLibrary(id, { name })` | assets:write | the saved asset |
+| `summer.generate.image({ prompt })`, `.sfx({ prompt, durationSeconds })`, `.sfxChoices({ prompt })`, `.music({ prompt, durationSeconds })`, `.voice({ text, voiceId })` | generate | the result with its asset |
+| `summer.generate.model3d({ prompt })`, `.video({ prompt })`, then `summer.generate.job(jobId)` | generate | a job, then its status |
+| `summer.ai.complete({ prompt, system, json })` | ai | the model's answer |
+
+Paid calls spend the viewer's credits; `spend_cap_reached` when the app's daily cap is hit.
+
+## Team, projects, analytics
+
+| Call | Permission |
+|---|---|
+| `summer.team.members()` → `{ members: [{ userId, role, name, image }] }` (never emails) | team:read |
+| `summer.team.presence()` → `{ presence: [{ userId, name, image, surface, seenAt }] }` | none |
+| `summer.projects.list()`, `summer.projects.get(id)` | projects:read |
+| `summer.grow.portfolio({ range: 7\|28\|90 })` (totals and per-game rows each carry `previous`: the same-length window before, or null), `summer.grow.game(id)`, `summer.grow.earnings()` | grow:read |
+
+## Engine [engine:read / engine:write]
+
+| Call | Notes |
+|---|---|
+| `summer.engine.status()` | Is an engine connected for this person |
+| `summer.engine.readFile(path)` / `writeFile(path, content)` | Only `manifest.engineFiles` paths (and `res://addons/<plugin>/`) |
+| `summer.engine.ops([{ op: "AddNode", ... }])` | App op allowlist only; values are Godot strings (`"Vector3(0, 10, 0)"`) |
+| `summer.engine.play(scene)`, `stop()`, `screenshot("viewport"\|"game")`, `state(kind)` | |
+| `summer.engine.onEvent(fn)`, `summer.engine.plugin.send(msg)`, `summer.engine.plugin.onMessage(fn)` | |
+
+`engine_offline`: no Summer Engine connected; show an "Open in Summer Engine" hint.
+
+## Kit values
+
+`<summer-form>` gives its fields' values by `name` (fields anywhere inside it count, also
+inside `summer-grid`); `form.values = {...}` or `form.setValues({...})` loads a record into it
+for editing. `<summer-text-input type="number">` and `<summer-slider>` give numbers in form
+values and change events (an empty number field gives `null`); the input's `.value` property
+stays text. A `<summer-toggle>` is a boolean.
+
+## Errors
+
+`permission_missing` (add it to the manifest), `invalid` (arguments; the message says which),
+`unknown_method`, `conflict`, `rate_limited` (600 calls a minute, 60 paid), `spend_cap_reached`,
+`engine_offline`, `not_implemented`, `unavailable`.

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

@@ -0,0 +1,197 @@
+---
+name: summer-apps-design
+description: "How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: tools
+user-invocable: false
+---
+
+# Summer Apps design
+
+A Summer App is a tool a game team uses every day inside Summer Studio. It should
+feel like a calm, precise studio instrument around colourful game content. The
+chrome is ink on paper; colour comes from the game (art, renders, waveforms) and
+from data that means something. You have freedom inside the app. Use it for the
+task, not for decoration.
+
+## The catalog is the API
+
+The kit ships `summer-ui/v1/catalog.json` next to `ui.js` on the kit origin (the
+summer-apps skill says how to load the kit). It lists every component's
+attributes with value shapes, events with their `detail`, slots, methods, a working
+example, the icon names and the tokens. **Read the entry before you use a
+component** and copy its example. Never guess an attribute.
+
+- JSON attributes take a JSON string, or set the same-named property:
+  `table.rows = rows`. Prefer properties for data.
+- Events bubble out of the components; read `event.detail`.
+- Icons: only names in `icons.names` (lucide: `plus`, `check`, `pencil`,
+  `trash-2`, `search`, `sparkles`, `download`, `ellipsis`, ...). Never draw SVG.
+- Colours: only the tokens in `tokens` (`var(--se-text)`, ...). No hex.
+
+## Do this
+
+1. Write one line: what the person came to do, and the one action that finishes
+   it. That action is the primary button.
+2. Build the page from the recipe below. Every part is a kit component; write your
+   own CSS only for layout glue (a grid, a gap), from tokens, under 30 lines.
+3. Read real data through the SDK. No lorem ipsum, no invented numbers.
+4. Wire `loading`, empty and error for every data component.
+5. Run the checklist. Look at light and dark, 390px and 1440px.
+
+## Page recipe
+
+```html
+<summer-page heading="Playtest results" purpose="How each level played in the latest playtest. Notes are shared with your team and your agent.">
+  <summer-avatar-stack slot="actions" people='[{"name":"Mia"},{"name":"Tom"}]'></summer-avatar-stack>
+  <span slot="actions" class="summer-meta">Playtest 12 Oct</span>
+  <summer-button slot="actions" variant="primary" icon="plus">Add note</summer-button>
+
+  <summer-stats loading>…3-5 summer-stat…</summer-stats>
+  <summer-chart heading="Where players stop" loading …></summer-chart>
+  <summer-section heading="Levels">
+    <summer-select slot="aside" label="Sort" options='…'></summer-select>
+    <summer-table loading …></summer-table>
+  </summer-section>
+</summer-page>
+```
+
+- `summer-page` gives the canvas, width (1280px; forms 640px), padding and spacing,
+  and the header. The purpose line says what the tool does and where data goes.
+  Header actions, in order: avatars, one meta (`.summer-meta` or
+  `summer-progress`), secondary buttons, the primary.
+- One `summer-section` per part, with a short noun heading. Extras for the title row
+  (a select, a count) go in `slot="aside"`; a select there turns compact by itself.
+- A chart gets its own `heading` (its legend then sits in the title row). A chart
+  without a heading as the first thing in a section moves its legend into the
+  section's title row.
+- A page with one part needs no section heading and no card around it.
+- Tables and lists are always framed; charts never. Do not set `frame="false"` on
+  a page.
+
+## Pick the component
+
+| Job | Use (exact names; shapes in the catalog) |
+| --- | --- |
+| Key numbers | `summer-stats` > 3-5 `summer-stat label value delta hint tone`. Delta is text like "+12 this week"; the kit colours the number |
+| A comparison or trend | `summer-chart kind x y heading highlight reference`. `y` is a JSON array of keys; `highlight` `{key, above, below, equals, tone, label, otherLabel}` (`key` tests another field, e.g. colour `lines` bars where `redo` is above 3; `equals` takes a value or a list); counts get whole-number gridlines by themselves; `reference` `{value, label, tone}`. One question per chart |
+| Records you scan, sort, edit | `summer-table columns rows row-key`. Column `{key, label, format, digits, type: bar/badge/muted, over, tone, badges, priority: "secondary", thumb, editable, badge, badgeTone, width, minWidth, wrap}`. Text columns wrap to 2 lines by themselves; `width` takes pixels, a CSS length, "narrow" or "wide" (e.g. `"wide"` for a notes column). `badges` maps each value to a tone or `{tone, label}` for a status column (`{"draft": "quiet", "review": {"tone": "info", "label": "In review"}, "done": "ok"}`; unlabelled values show in sentence case); `badge` names a row key shown as a small badge inside a cell (e.g. "+3:01" over target). Under 640px badge columns fold under the name, and rows stack only if the columns still do not fit. `clickable` gives `summer-row`; `selectable="single"` or `"multi"` gives `summer-select-rows` |
+| Unsaved table edits | `summer-save-bar count save-label` (`save` and `discard` events; then `table.commit()` or `table.discard()`) |
+| Notes, tasks, comments | `summer-list items checkable action menu`. Item `{id, title, meta, checked, badge: {text, tone}, action}`; `action` `{id, label, icon}` is the one quiet button per row; `menu` items `{id, label, icon, tone: "danger"}`; events `summer-check`, `summer-action`, `summer-item` |
+| Pipeline stages | `summer-board` > `summer-lane heading lane-id add-label` > `summer-board-card heading card-id art meta person comments done`; `summer-move` event |
+| Pick between versions | `summer-choice-grid items` (`layout="row" heading meta` for one row per need). Item `{id, label, src, kind}` |
+| Filters above a list | `summer-toolbar` > `summer-search`, `summer-segmented options value` (`{value, label, count}`; scrolls inside its own track when it does not fit), `summer-select` in `slot="end"` (compact by itself) |
+| Add or edit something | `summer-dialog heading description` > `summer-form submit-label` > named inputs |
+| Inputs | `summer-text-input name label hint required multiline`, `summer-select name label options`, `summer-slider`, `summer-toggle`. Every field sends `input` and `change` with `event.detail.value` |
+| Media | `summer-audio`, `summer-video`, `summer-image aspect`, `summer-model-viewer`. Never `<audio controls>` or `<video controls>` |
+| A repeated object | `summer-card variant="object" media selected` |
+| Status in words | `summer-badge tone` (ok, warn, bad, info, quiet, count) |
+| Buttons | `summer-button variant icon size`, `summer-icon-button icon label` |
+| Messages | `summer-notice tone text action` in place (`action="Try again"` adds a button; listen for `action`); `summerUI.toast(text)` after an action |
+| Nothing yet | `summer-empty-state heading body` with one button inside |
+
+If you play Web Audio yourself, call `summer.app.busy(true)` while it plays and
+`busy(false)` after.
+
+## Patterns
+
+**Dashboard (numbers, chart, table).** Stats, then one chart answering the main
+question with the problem bars highlighted and a reference line for the target,
+then the table with a bar column for the value that matters. Columns a phone can do
+without get `priority: "secondary"`.
+
+**Badges in tables.** Two kinds, one rule each:
+- A workflow status column (draft, in review, done, needs art) shows every value as
+  a badge with `badges`. Neutral steps are `quiet`, work in progress `info`, done
+  `ok`; only values that need someone to act get `warn` or `bad`.
+- A health column (balance, over target, errors) shows a badge only on the rows
+  that need attention and stays empty on the rest. Never "OK" on every row.
+
+**Edit flow.** A row click (`summer-row`) or the header's primary opens a
+`summer-dialog` holding a `summer-form`. For an edit, call
+`form.setValues(record)` before `dialog.show()`; for a new item, show it empty.
+Listen for `submit` (`detail.values`; number fields give numbers, empty gives
+null); set `busy` while saving and `error` if it fails; close the dialog on success and toast the result ("Note saved"). The rule is one
+primary per region: the page header, an open dialog, a form that is the whole page,
+and the save bar are separate regions. A page whose job is the form puts Save in the
+form and no primary in the header.
+
+**Empty page and the header.** One primary on screen. When the whole page is empty,
+the empty state holds the primary ("Add note" or "Ask your agent") and the header
+shows no primary until there is data. When only one section is empty, its
+empty-state button is `secondary` and the header keeps its primary.
+
+**List with row actions.** `summer-list` with `checkable` for done or fixed, one
+`action` for the most common step (`{id: "fix", label: "Mark fixed", icon:
+"check"}`: a quiet button that shows on hover and on touch), and `menu` for the rest
+(Edit, Copy, Delete with `tone: "danger"`). Never a bordered button on every row.
+Delete asks first in a `summer-dialog` with `summer-form destructive`.
+
+**Data your agent fills in.** When the app waits on an agent (an import, an
+analysis), the empty state says what is missing and offers the request:
+`summer-empty-state heading="No playtest data yet" body="Your agent can import
+last night's playtest."` with a `summer-button icon="sparkles"` "Ask your agent"
+(primary or secondary per the empty-page rule above). On click call `summer.agent.send("playtest.import", {})`, swap the button
+for `summer-notice tone="info"` "Your agent was asked. This fills in when it
+answers.", and subscribe so rows appear live:
+`summer.data.collection("levels").subscribe(render)` (there is no
+`summer.data.list(name)`).
+
+**Who added it, who changed it.** People and agents edit the same data. Every
+record carries `createdBy` (set once, when it was added) and `actor` (the last
+writer), both `{userId, kind: "person" | "agent" | "seed", agent, via}` or null on
+old records. A "By"
+column or list meta shows `createdBy`: the person's name, or the agent's name
+("Claude Code") with an "Agent" badge when `createdBy.kind` is "agent". Show
+nothing for "seed" (starter data) or null. Add "Last changed by" from `actor` only when it
+helps the task. Say "You" when the `userId` is `info.viewer.userId`. Flash a row or
+card that someone else just changed. Changes from `subscribe` carry `actor` but not
+`createdBy`: read the record again (`get(id)`) to show who added it.
+
+**Board.** Lanes per stage, art on cards from the asset, owner initial and comment
+count. Move cards with `summer-move`; write the new stage to data at once.
+
+**Pick grid.** One `summer-choice-grid layout="row"` per need; the header shows
+`summer-progress` and the primary sends the picks ("Send 7 to game").
+
+## States
+
+- Loading: set `loading` on stats, chart, table, list and select until the data
+  arrives. Never show "No data yet" or "-" while loading.
+- Empty: `empty-text`, or `empty-heading` + `empty-body`, on the component, or
+  `summer-empty-state` for a whole page. Say what to do next.
+- Error: `summer-notice tone="error" text="The notes could not load." action="Try again"`
+  in place of the part that failed; retry on its `action` event. The rest keeps
+  working.
+- Saving: `busy` on the form or save bar, `loading` on a button.
+
+## Type, colour, copy
+
+- The kit sets type. In your own glue use 14px body, 12px muted meta, weights 400,
+  500, 600, `tabular-nums` for numbers. Never 700, never all caps.
+- Colour means something: quiet by default, ink or a status tone for what needs
+  attention, always with words.
+- Plain words, sentence case, no full stop on labels. Name actions by result ("Save
+  note", "Write to game"). Errors do not apologise. Never "AI-generated".
+
+## Never
+
+Grey boxes around numbers. Cards around every section, cards inside cards. Native
+audio, video, select or range controls. Two primaries in one region. A labelled
+button on every row. A health badge on every row that only says all is well. Hand-drawn icons, emoji. Hex
+colours, gradients, glows, shadows on cards. Mono font for numbers. "No data yet"
+while loading.
+
+## Checklist
+
+- [ ] The purpose line says what the tool does; one primary per region finishes it.
+- [ ] Every component and attribute matches its catalog entry.
+- [ ] Numbers line up; long text wraps; on a phone nothing scrolls off.
+- [ ] Loading, empty (including "waiting for your agent") and error states exist
+      and keep the layout in place.
+- [ ] Subtract: remove each badge, icon, helper line and frame; keep it only if the
+      task gets worse without it.
+- [ ] Works by keyboard; icon buttons have labels.
+- [ ] Looked at light and dark, 390px and 1440px; nothing scrolls sideways except a
+      board or a wide table inside its frame.

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

@@ -0,0 +1,23 @@
+id: skill/summer-apps-design
+kind: skill
+version: 0.1.0
+summary: How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist.
+use_when:
+  - building or changing the UI of a Summer App (agent-built team tool inside Summer Studio)
+  - an app looks generic, cluttered or off-brand
+  - choosing layout for a table, chart, board, pick grid or settings tool
+facets:
+  lifecycle:
+    - build
+  domains:
+    - ui
+    - tools
+  modalities:
+    - docs
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+recommended: true

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

@@ -112,6 +112,7 @@ When multiple Summer skills could apply, run them in this order:
 3. **Build skills third** — `fps-controller`, `design-mechanic`, `design-level`, `multiplayer`. These produce the artifacts.
 
 > "I want to make a game" → `brainstorm-game` first, then build skills.
+> "Make me a sword clash sound" with no game in sight → the asset skill (`sound-effect`) directly. Asset requests need no brainstorm, no project and no running engine.
 > "Fix this crash" → `debug` first, then domain skills.
 > "Add an FPS controller" → check `scene-composition` first, then `fps-controller`.
 

package/library/tools/app-call/resource.yaml

@@ -0,0 +1,59 @@
+id: tool/app-call
+kind: tool
+version: 1.0.0
+summary: Run one of a Summer App's agent tools inside the person's open app.
+use_when:
+  - '"nerf the bow using the balance formula in our app"'
+  - using logic that lives in an app (a balance formula, an export) while the app is open
+do_not_use_when:
+  - "plain reads and edits of app data: summer_app_data"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_call
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_call
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    tool:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: The agent tool name from summer_app_tools
+    input:
+      type: object
+      additionalProperties: {}
+      default: {}
+      description: Input matching the tool's input schema
+  required:
+    - appId
+    - tool
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-create/resource.yaml

@@ -0,0 +1,67 @@
+id: tool/app-create
+kind: tool
+version: 1.0.0
+summary: Create a new scratch Summer App (a tool for the person's team inside Summer Studio) and open it in their Studio tab.
+use_when:
+  - '"build me a tool for…" / "make an app that…"'
+  - the person needs a UI to decide or edit something they will come back to
+do_not_use_when:
+  - "a one-off answer: reply in chat"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_create
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_create
+    remote: true
+input_schema:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 80
+    purpose:
+      type: string
+      maxLength: 280
+      description: "One line: what the tool does and where its data goes"
+    format:
+      type: string
+      enum:
+        - code
+        - layout
+      default: code
+      description: "code: index.html + JS/CSS (default). layout: a JSON layout of kit nodes, for quick decision UIs"
+    workspaceId:
+      type: string
+      format: uuid
+      description: "A workspace id. Default: the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which"
+    folder:
+      type: string
+      minLength: 1
+      maxLength: 80
+  required:
+    - name
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-data/resource.yaml

@@ -0,0 +1,74 @@
+id: tool/app-data
+kind: tool
+version: 1.0.0
+summary: Read or write a Summer App's shared data collections; works with no app open and the team sees writes live.
+use_when:
+  - '"nerf the bow in our balance sheet"'
+  - seeding an app with data
+  - reading what the team entered in an app
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_data
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_data
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    collection:
+      type: string
+      maxLength: 48
+      description: "Read: one collection. Default: all"
+    after:
+      type: string
+      maxLength: 200
+      description: "Read: the next cursor from the previous page"
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 500
+      default: 200
+    ops:
+      type: array
+      items:
+        type: object
+        additionalProperties: {}
+      minItems: 1
+      maxItems: 100
+      description: "Write: [{op: put, collection, recordId, data}, {op: patch, collection, recordId, patch}, {op: remove, collection, recordId}]; ifRevision on an op applies it only at that record revision (0: must not exist)"
+    as:
+      type: string
+      enum:
+        - agent
+        - seed
+      description: "Write: seed for starter data that belongs to the team (no author). Default: agent"
+  required:
+    - appId
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false

package/library/tools/app-dock/resource.yaml

@@ -0,0 +1,59 @@
+id: tool/app-dock
+kind: tool
+version: 1.0.0
+summary: Dock a Summer App as a panel in the running Summer Engine editor, close it, or list docked apps.
+use_when:
+  - '"put the quest editor next to my scene"'
+  - keeping a team tool open while editing
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_dock
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_dock
+    remote: false
+input_schema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum:
+        - open
+        - close
+        - list
+      default: open
+    appId:
+      type: string
+      format: uuid
+      description: "open, close: the app"
+    slot:
+      type: string
+      enum:
+        - left
+        - right
+        - bottom
+      default: right
+      description: "open: left, right or bottom"
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false