> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Summer App with your agent: the build loop

> How an agent builds a Summer App that works the first time: connect the Summer MCP, follow the build loop, avoid three common mistakes, and check it with apps.screenshot.

This page is for the agent and for the person who drives it. It has the build loop, the three mistakes that break apps, and prompts that work.

## Connect your agent

The `apps.*` operations are in the Summer Engine MCP. Your agent runs each with `summer_call`: `{"op": "apps.create", "input": {...}}`. `summer_search "summer app"` lists them with their inputs. Every input: [Summer Apps operations](https://docs.summerengine.com/mcp/operations/apps.md). Connect your agent in one of the two ways below. Or describe the app to Summer in Studio chat: **Build a new app** in **Studio > Apps** and **Edit with agent** on an app page open it.

> [tab] Any agent (hosted)
>
> Add `https://mcp.summerengine.com/mcp` to your agent and sign in to your Summer account once. Nothing to install. Claude Code: `claude mcp add --transport http summer https://mcp.summerengine.com/mcp`, then `/mcp` and sign in. Claude and ChatGPT: add it as a custom connector. Step by step: [Connect your agent](https://docs.summerengine.com/publishing/connect-your-agent.md).
>
> Use the custom connector, not the versions of Summer made for the ChatGPT and Claude app directories: those do not have Summer Apps.

> [tab] On your computer (npm)
>
> For Claude Code, Codex, Cursor and other agents on your computer:
>
> ```bash theme={null}
> npx -y summer-engine@latest setup claude-code --yes   # or: setup codex --yes
> npx -y summer-engine@latest login
> ```
>
> `setup` adds the MCP (`npx -y summer-engine@latest mcp`) to your agent and installs the Summer skills, `summer-apps` and `summer-apps-design` among them. `login` signs you in to your Summer account in the browser. Restart your agent. Other agents: [MCP setup](https://docs.summerengine.com/mcp/setup.md).
>
> The npm package adds two local operations: `apps.publish_folder` publishes a local folder, and `apps.dock` docks an app in Summer Engine (that comes with the next Summer Engine update). You can also install the `summer` CLI with `brew install summerengine/tap/summer` or `npm install -g summer-engine`.

## The loop

**1. Read the guide**

`apps.guide` returns Markdown. Without a `section` it returns `overview`: when to build an app, layout or code, the loop and the rules. Read it first. Then read what the app needs: `examples` starts with a complete working app; `sdk`, `manifest` and `kit` have every call, field and component; `design` has the look; `layout` the layout format; `types` the SDK's TypeScript types. `all` returns every section except `types` at once, about 100,000 characters: raise `maxCharacters` (default 24,000) or the answer is cut and says `truncated`. Load the `summer-apps` and `summer-apps-design` skills when you have them.

**2. Create the app**

`apps.create { name, purpose, format }`. `format` is `code` (default) or `layout`. The answer has the new `appId`. The person's open Studio tab moves to the new app. If the answer has `studio.reason: "no_tab"`, no Studio tab was open: give the person the link `/studio/apps/<appId>`.

**3. Write and publish**

Write `index.html` and `app.js` (and CSS if you need it), then `apps.publish { appId, files, manifest, note }`. With the npm package, `apps.publish_folder` publishes a local folder instead. Each publish is a new, immutable version. A publish error names the file or the rule: fix it and publish again. A publish that goes through can still answer `checks`: SDK calls whose permission the manifest lacks, and `summer.agent.send` events or `summer.agent.tool` tools the manifest does not declare. Those fail when the app runs. Fix them and publish again.

**4. Seed data**

If the app should start with content, write it with `apps.write_data` and `"as": "seed"`. Seed rows belong to the team and show no author.

**5. Look at it**

`apps.screenshot { appId }`, then again with `width: 390` (a phone) and `theme: "dark"`. To see a dialog or a second state, add `steps`. Fix every error, console line and refused call it reports, publish, and look again. Repeat until it is clean.

**6. Listen**

`apps.events { appId, after, timeoutSeconds }` waits up to 50 seconds for what the app sends (`summer.agent.send`), errors (uncaught ones and `console.error` lines) and the team's feedback. Pass the returned `cursor` as `after` next time.

**7. Change it, keep it or archive it**

To change the app, `apps.get { appId }` returns the current files and manifest. Edit them and publish again. To change only data, use `apps.write_data`; no publish needed. When the team keeps the app, `apps.update { appId, status: "kept" }`. Archive throwaway apps when you are done: `apps.update { appId, status: "archived" }`.

Before step 2, check whether Summer already does the job: the asset library's collections and groups, Pick one and sound choices, Grow dashboards, Team. If it does, use that. If an app needs something the SDK lacks, report it with `apps.report_gap`.

## Three things that break apps

1. **The SDK and kit load as ES modules from root paths.** The app is served from its own host, `apps.summerengine.app`:

   ```html theme={null}
   <script type="module" src="/summer-sdk/v1.js"></script>
   <script type="module" src="/summer-ui/v1/ui.js"></script>
   <script type="module" src="app.js"></script>
   ```

   Any other path, a CDN copy or a local copy does not connect. The screenshot then shows `connected: false`.
2. **`await summer.ready` before the first call.** It resolves when Studio connects the app. Outside Summer Studio it never resolves, so opening `index.html` on its own shows nothing. There is no offline host; do not mock the SDK.
3. **Shared data goes through `summer.data.collection(name)`.** Use `.list()`, `.get(id)`, `.put(id, data)`, `.patch(id, partial)`, `.remove(id)` and `.subscribe(fn)`. There is no `summer.data.list(name)`; it rejects with `invalid`.

Also: the app runs in a sandbox with no cookies, no `localStorage` and no network. Keep state in shared data. Add the `data` permission to the manifest, or every data call rejects with `permission_missing`.

## Catch mistakes before you publish

Save the SDK types from `/summer-sdk/v1.d.ts` (or `apps.guide` section `types`) as `summer-sdk.d.ts` in the folder above your app folder, and start `app.js` with:

```js theme={null}
// @ts-check
/// <reference path="../summer-sdk.d.ts" />
```

Your editor, or `tsc --checkJs --noEmit`, now reports a wrong method name, a missing argument or a wrong result field. Keep the `.d.ts` file out of the app folder: `.ts` is not an app file type, so a publish with it fails.

## Look at it: apps.screenshot

Summer renders the published app headless, as the person and with their data, and returns the picture (`image`) plus a `report`.

| Argument | Default | |
| - | - | - |
| `appId` | | Required. |
| `version` | the current one | A published version. |
| `width`, `height` | 1280, 800 | 320 to 1920 and 320 to 1600 px. Use `width: 390` for a phone. |
| `theme` | `light` | `light` or `dark`. |
| `fullPage` | `false` | The whole scroll height, up to 4,000 px. |
| `params` | | Launch params, as in `/studio/apps/<appId>?key=value`. |
| `steps` | | Up to 5 steps, run in order before the capture: `{ "click": "<css selector>" }`, `{ "press": "<declared action id>" }` or `{ "wait": <ms> }` (up to 3,000). In a selector, `>>>` reaches inside kit components: `"summer-table >>> tbody tr"`. Writes that a step causes are refused, as always. |

The `report`:

| Field | Tells you |
| - | - |
| `connected` | The SDK loaded and Studio's stand-in connected it. `false`: fix how `index.html` loads `/summer-sdk/v1.js`. |
| `rendered` | The first SDK calls settled and the app painted within 8 seconds. The capture then waits until the app's SDK calls settle and no kit element shows `loading`, up to 6 seconds. |
| `console`, `errors` | Console lines and uncaught errors, with source and line. |
| `calls` | Every SDK call with `ok`, and `code` for a refused one. |
| `declared` | The fields and buttons from `summer.page.declare`. |
| `agentTools` | The agent tools the app registered. |
| `steps` | Each step with `ok`, and `error` for one that failed. |
| `title`, `notices`, `hints` | `setTitle` and `notify` text, and hints on what to fix. A hint says when the page still shows loading placeholders. |

To see the edit dialog of an app whose table rows open one, click the first row before the capture:

```json theme={null}
{ "appId": "<app id>", "steps": [{ "click": "summer-table >>> tbody tr" }, { "wait": 300 }] }
```

For a button the app declared with `summer.page.declare`, `{ "press": "<action id>" }` works the same way.

The screenshot is read-only. Reads run as the person (data, assets, team, projects, Grow, choices, engine status). Writes, paid calls and other engine calls are refused with `invalid`; events and notices are recorded, not delivered. They all work in Studio. To see data in a screenshot, seed it first with `apps.write_data`. A screenshot before the first publish fails with `not_found`.

The SDK also reports an app's `console.error` lines to `apps.events` as `error` events, so errors the app catches and logs reach you after the person uses it.

## Prompts that work

**Build a team tool.** Your agent builds, publishes, seeds and checks a Summer App.

Build us a Summer App: \[the tool, its data and the one action that finishes the job].
Read the apps.guide operation first and follow the summer-apps and summer-apps-design
skills. Declare every data collection in the manifest. Seed starter data with
apps.write\_data "as": "seed". Then check it with apps.screenshot at the default width, at width 390
and with theme dark, fix everything the report shows, and send me the app link.

**Change an app.** Your agent edits the files and publishes a new version.

In our \[app name] app, \[the change]. Read the current files with apps.get, publish
a new version with a short note, then check it with apps.screenshot.

**Edit the data.** Your agent changes records; everyone with the app open sees it live.

In our \[app name] app, \[the data change, for example "lower the bow's damage by 10%"].
Read the records with apps.read\_data, write the change with apps.write\_data and ifRevision, and tell me
the old and new values.

**Fix what the team reports.** Your agent reads errors and feedback and fixes the app.

Read the errors and feedback for our \[app name] app with apps.events, fix the
causes, publish, and check the result with apps.screenshot.

Worked examples: [Apps for game teams](https://docs.summerengine.com/apps/game-teams/weapon-balance-table.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.