# Build an Ember applet with an AI agent

Give the agent the repository's entire `docs/applets` folder. It is the authoritative applet contract and contains the manifest specification, v1 and v2 schemas, TypeScript types, a key generator, a package signer, and a WASI backend template. Read the [public API reference](/docs/applets/APPLET_SPEC.md) first, then use the repository folder when packaging.

Use this brief:

```text
Build an Ember applet. Read docs/applets/APPLET_SPEC.md, the matching manifest
schema, and ember.d.ts before writing code. Create an applet folder with
applet.json and its declared HTML entry file. Load /_ember/sdk.js before the
applet script. Use only window.ember APIs and capabilities documented in the
author kit. Keep all application assets in the folder. Do not use Tauri, host
filesystem access, raw sockets, subprocesses, environment variables, or remote
scripts. Request the narrowest capabilities possible. Create a private Ed25519
publisher key outside the applet folder, package the applet, install the exact
.ember-applet artifact in Ember, and return the source and package. Never place
the private key or user secrets in the applet folder, package, or response.
```

## Required files and manifest version

Every applet has an `applet.json` manifest, not `plugin.json`, plus the HTML file named by `entry`.

```text
my-applet/
  applet.json
  index.html
  app.js
  styles.css
```

Use manifest version 1 only for a local applet with optional JSON storage. Use version 2 for native HTTP, browser-network policies, credentials, OAuth, external links, fullscreen, workers, a guest terminal, trusted extension calls, or a WASI backend. Version 2 must contain a `capabilities` object, even when it is empty. It never uses the version 1 `permissions` array.

## SDK and permissions

The applet must load Ember's SDK from `/_ember/sdk.js` before its own JavaScript. The SDK exposes the read-only `window.ember` object. It includes storage, declared settings, native HTTP, credential prompts, OAuth, external links, fullscreen, a guest terminal, optional WASI backend calls, and approved extension methods. A method is available only when its manifest capability is declared.

For a complete manifest and API reference, use `APPLET_SPEC.md`. Copy `ember.d.ts` into a TypeScript project. Do not guess API names, manifest fields, or network rules from other plugin systems.

## Build, test, and publish

From the repository root:

```sh
npm run applet:key -- ../publisher-key.pem
npm run applet:pack -- path/to/my-applet ../publisher-key.pem
```

Keep that private key for every future update of the same applet ID. Ember pins the first publisher key it sees and rejects an update signed by another key. Install the resulting `.ember-applet` in Library and approve the capability review before testing it. Publish the same signed bytes and matching release metadata only after that test passes.

Never ask an agent to bypass signature verification, broaden a network origin, use undeclared native access, or store a secret in the package. A desktop applet cannot safely contain a publisher-wide service secret.