Realm shapes

A realm is a directory of capabilities. How those capabilities are expressed is up to the author — realms span a spectrum from pure-declarative to handlers-driven:

Declarative-only (e.g. realm-github, realm-email)

YAML files describe everything; no code ships. The host parses the declarations and wires them into the runtime.

• realm-github: types/github.yml, events/*.yml, actions/*.yml, apis/apis.yml, skills/*/SKILL.md. The framework’s planner consumes the action specs; the poll executor consumes the event specs; the API allowlist consumes the apis manifest. No TypeScript, no src/.
• realm-email: a pure abstract-concept realm — types/email.yml declares the universal email.thread DomainType, and actions/*.yml ships the attention-worthiness policies that operate on it. Signal producers (in-tree Gmail today, future realm-exchange / realm-imap) live elsewhere; this realm carries only the abstraction and the rules.

Handlers-driven (e.g. realm-google)

When the integration genuinely needs imperative code — guarded mutations with revision checks, multi-step orchestration of vendor APIs, custom domain logic — the realm ships TypeScript handlers alongside the standard YAML.

• realm-google: src/api/docs-editor.ts implements an editing surface for Google Docs (outline / read / find / proposeEdits / applyEdits) with revisionId guards the framework can’t express declaratively. src/lib/*.ts carries the supporting logic (outline construction, op validation, op translation). src/types/edit-op.ts declares the TypeScript types the handlers trade in. tests/*.test.ts are Vitest specs covering each handler’s contract. package.json / tsconfig.json / vitest.config.ts complete the project. The realm also carries apis/ (vendored OpenAPI specs), skills/ (workflow docs for small models), and prompts/ like any other realm — they aren’t mutually exclusive.

The host loads the handlers through the framework’s TypeScript runtime; the standard YAML capabilities load the same way they do for declarative realms. Authors choose freely per file.

Choosing a shape

• Start declarative. If a YAML stepType: action (or any host-extension ActionSpec referenced by FQN) can express what you need, that’s the right tool — no build step, no runtime code path, the host’s planner reasons about it directly.
• Reach for handlers when the operation has invariants the planner can’t enforce on its own (atomicity, revision guards, ordering across multiple vendor calls) or when the vendor’s API grammar is rich enough that surfacing it as one tool collapses too much.
• A realm can mix freely. actions/ and src/ coexist; nothing in the spec says “if you ship handlers, ship only handlers.”