---
name: purposeos-app
description: Scaffold, build and package a PurposeOS app (.papp) with an app.json manifest, a native service and a web UI. Use when asked to create or modify a PurposeOS app, service, intent or manifest.
---

# PurposeOS app

1. Pick an id ([a-z0-9-]). Create `app.json` (schema 1) with `ui`, `services`, optional `intents`, and `permissions`.
2. Write the service. Rust: depend on `exec-plugin-service`, call `server::bind` then `server::serve(listener, name, actions, handler, shutdown)`.
   Any language works if it speaks the newline-JSON protocol on the socket passed as `serve --socket PATH`.
3. Declare every action in `services[].actions`. Make each idempotent.
4. For voice: add an `intents[]` entry with `phrases`. For dictation into the app use `result: "capture"` with `sink`, `end`, `discard`.
5. UI: `ui/index.html` using `window.purpose.call(action, input)` and `window.purpose.on(event, cb)`.
6. Package: `purpose-pkg pack . -o out.papp --arch aarch64`, then `purpose-pkg install out.papp`.

Pitfalls: unknown manifest keys fail the install; a service that does not serve every declared action is refused;
`permissions.network: true` is rejected; `data/` is reserved in the bundle.