# AGENTS.md: building a PurposeOS app

You are helping build a `.papp` for PurposeOS, a local-first Linux OS. Read this before editing.

## Layout
    app.json          manifest, schema 1. Unknown keys are rejected. Edit with care.
    bin/              service binaries (native). Must accept: <exe> serve --socket PATH
    ui/               web UI (ui.kind = "web"), plain JS or Dioxus-wasm; QML for action views
    assets/           icon (svg)
    LICENSE

## Rules you must not break
- App id is [a-z0-9-]. Services are named <id>-<service>. Actions are <id>.* .
- Services talk newline-delimited JSON over a Unix socket. One request per line:
  {"id":"1","action":"journal.list","input":{}}  ->  {"ok":...} or {"error":{"kind":"transient|unavailable|permanent","message":"..."}}
- Every action must be idempotent (calls are retried).
- Never use the network. permissions.network = true is rejected. Never log user text.
- UI code calls services only through window.purpose.call(action, input). No fetch to remote hosts.
- Ask for the narrowest permissions.files grant that works ("ro:~/Documents/x", not "rw:~/").
- Do not add dependencies on pacman packages.

## Commands
    purpose-pkg pack . -o dist/<id>-<version>-aarch64.papp --arch aarch64
    purpose-pkg install dist/<id>-<version>-aarch64.papp
    purpose-pkg verify <id>

## Done means
- `purpose-pkg verify <id>` exits 0.
- Every action in app.json is served by the service (the executor refuses a service that omits one).
- Tests pass for core logic. UI tests use a fake window.purpose.