# AGENTS.md — coding agent onboarding for {{name}}
> **You are a coding agent working in `node-app-{{name}}`.**
> This app was scaffolded by `node-app new --profile burger`. It is a
> **Burger app**: an ES module bundle hosted by the platform's Burger
> (QuickJS) runtime, not by Bun.
## What this means for you
- **Only the Burger Phase 1 API exists at runtime.** Platform modules:
`burger:host`, `burger:fs`, `burger:path`, `burger:os`, `burger:crypto`,
`burger:buffer`, `burger:sqlite`, `burger:worker_threads`, `burger:test`;
globals include `crypto.randomUUID`/`getRandomValues` and a `Buffer`
subset. You may write `node:fs`, `fs`, `node:path`, `node:os`,
`node:crypto`, `node:buffer`, `node:worker_threads`, `bun:sqlite`,
`bun:test`: `burger-build` rewrites them. Everything else (`node:net`,
`node:http`, `events`, `url`, `fetch`, `URL`, `Bun.*` such as `Bun.SHA256`
or `Bun.sleep`) is missing, and both `bun run build` and `bun run check`
fail on it.
- **No filesystem assets next to the bundle.** Don't read files relative to
`import.meta.url`; import JSON statically. Relative `burger:fs` paths
resolve against the app's data directory.
- **The SDK is bundled.** `@econ-v1/app-sdk` resolves through its `burger`
export condition and is inlined into `dist/index.js`; there is no shared
`node_modules` on the device.
- **Heavy JSON belongs in the host.** `JSON.stringify` is about 10× slower
in QuickJS than in Bun, so keep large payloads out of hot paths.
- **No own systemd unit, no own HTTP listener.** Capability calls arrive
through `runNodeApp(...)`.
- **Stops are abrupt.** Burger gives an app at most 5 s to shut down. If this
app owns durable in-flight work (queued jobs, retries, `in-progress` rows),
it MUST reset or resume that work when it starts, before accepting new
calls; never rely on `shutdown()` finishing it.
## First files to open
| `src/app.ts` | the capability handler (importable by tests) |
| `src/index.ts` | starts the app |
| `tests/app.test.ts` | `bun:test`-style tests, run inside Burger |
| `manifest.json` | `capabilities`, and `resources.memory_mb` (QuickJS heap limit) |
## Useful commands
```bash
bun run check # typecheck against @econ-v1/app-sdk/burger-types (no Node/Bun types)
node-app test # run tests inside node-app-burger
node-app build # bundle dist/index.js with burger-build
node-app dev # hot-reload dev loop against a local monorepo
node-app package # build the .deb (Depends: node-app-burger)
```
## Don'ts
- Don't add `bun-types`, `@types/bun` or `@types/node`: they hide the
missing APIs from the typechecker.
- Don't add native addons or `manifest.nodeApp.privateRuntime` entries.
- Don't change `app_type` back to `"bun"` without a documented reason.