platform AGENTS.md

AGENTS.md — orienting an AI agent in the QORM repo

What this is. QORM (Query · Observe · Render · Mutate) is a pure-Go, agent-native cross-platform app platform. A QORM app is JSON — a manifest (qorm.json) + scenes/*.json + actions/*.json, an optional Go middle-layer, and an optional qorm.config.json (host window config: size/title/resizable/chromeless/transparent — never bundled or signed) — that one runtime renders to HTML/CSS, ed25519-signs into a verifiable bundle, delivers over-the-air, packages for web / iOS / Android / desktop, and exposes to agents over MCP. Dual-consumer by design: every artifact is meant to be read, written, and verified by both a person and an AI. The acronym is the API surface: Query (HTTP/MCP reads), Observe (SSE), Render (the runtime), Mutate (actions + writes).

Full machine-readable map: llms.txt.

Understand it

• README.md — what QORM is + the CLI at a glance.
• examples/ — the canonical runnable apps. Trust these over any spec.

Write / edit an app

• One-Command Scaffold & Run: Run qorm run <app-dir> (or go run ./cmd/qorm run <app-dir>) — if <app-dir> doesn't exist, it automatically scaffolds the starter app and launches the native standalone executable application window for the platform.
• Use the format the runtime accepts today: text via text, bind with {{state.x}}, onPress names an action in actions/, components in qorm.json use {{prop.x}}. See getting-started and the widget catalog (auto-generated from the code, canonical).
• Do not use the old value / on:{press} / {{count}} / scene:// forms — the runtime ignores them. When docs and a runnable example disagree, the example wins.
• App logic too big for steps goes in a script action: an action JSON with a script field holding qscript source (internal/qscript — let/if/for in/ while/fn, the expression language's operators and builtins, state read/write, args in), or — the file-per-action spelling — an actions/<id>.qs file whose filename is the action id and whose full text is the script. The loader compiles it (parse errors name the line, and the file for .qs); script beats steps when both are declared. Canonical example: examples/tetris.
• Shared styles live in a stylesheet: styles/<id>.qss (QORM Style Sheet, internal/qss) — rules like button { borderRadius: 12 }, .accent { … }, #submit { … } (type / class / id selectors; # comments; numbers stay numbers, strings and {{bindings}} evaluate like inline style values; nested objects such as margin: {top: …} stay inline on the node). Scene nodes reference them with a class prop (space-separated, later classes win). Cascade: theme component default < type rule < class rule (declaration order) < id rule < inline style. Parse errors are load-time diagnostics naming file and line; unknown style keys warn. Canvas and HTML both apply matching rules (HTML merges them into emitted node CSS). Canvas visual effects (filter, mask, scroll-snap, FLIP, spring, text stroke/shadow, …) are documented in docs/styles.md and listed under common style props; showcase examples/canvas-fx. Example stylesheet: examples/tetris styles/app.qss.
• No emoji in UI, code, or docs — use the built-in SVG icon set (icon names like heart / star / zap, listed in internal/render/icons.go).
• Style against the theme variables (var(--accent), var(--label), …) so apps follow the OS light/dark setting (default theme is auto). Manifest designTokens render as stage-scoped CSS vars too — color.primary → var(--qorm-token-color-primary). Unknown style keys are load-time warnings (the renderer ignores them).