Directory Structure

realm-name/
├── realm.yml              # Required: realm metadata
├── icon.svg               # Realm icon (optional) — any path, named by realm.yml `icon`
├── actions/              # Action specifications (YAML) — framework + host-extension stepTypes
│   └── my-action.yml
├── goals/                # Goal specifications (YAML)
│   └── my-goal.yml
├── types/                # Dynamic type definitions (YAML)
│   └── my-type.yml
├── producers/            # Virtual-join producers for on-demand types (YAML, optional)
│   └── my-producers.yml
├── reference/            # Reference/catalog data seeded into the KG on load (YAML, optional)
│   └── my-reference.yml
├── views/                # Named Cypher views (YAML, optional) — runnable by name, and a node view composes as a label
│   └── my-views.yml
├── rules/                # DERIVE rule sets (YAML, optional) — derived labels/relationships, one rule set per file
│   └── my-rules.yml
├── lenses/               # Named lenses (YAML, optional) — captured handlers or host-specific definitions
│   └── my-lens.yml
├── apis/                 # API entries (YAML)
│   └── my-api.yml
├── keys.yml              # The API keys the realm needs, and how to check them (optional)
├── credentials.yml       # Captured realms: the credentials the owner binds (optional)
├── src/                  # Hand-authored TypeScript handlers (optional)
│   └── api/
│       └── my-handlers.ts
├── tests/                # Vitest specs for handlers
│   └── my-handlers.test.ts
├── wasm/                 # Handler source for the wasm host (optional)
│   └── handlers.js
├── mcp/                  # MCP server configurations (YAML)
│   └── my-server.yml
├── commands/             # Slash command mappings (YAML)
│   └── my-command.yml
├── webhooks/             # Webhook registrations (YAML)
│   └── my-webhook.yml
├── events/               # Event ingestion — push + poll
│   └── my-source.yml
├── data-pipes.yml        # Captured channel source and consumer declarations
├── channels/             # Realm-shipped provider connector drafts (YAML)
│   └── my-channel.yml
├── agents/               # Agents — named colleagues whose routines react to signals/cron, adopted by the world
│   └── my-handler.yml
├── decorations/          # Scheduled KG node-decoration manifests
│   └── my-decoration.yml
├── apps/                 # Bundled HTML apps served at /apps/{name}
│   └── my-dashboard.html
├── hints/                # Tips the host UIs show users of this realm (YAML, optional)
│   └── tips.yml
├── artifacts.yml         # Custom artifact type registrations (optional)
├── prompts/              # Prompt contributions
│   └── examples.md
├── skills/               # Skills (Agent Skills spec)
│   └── my-skill/
│       └── SKILL.md
├── notebook/             # Reusable sets of slots a persona keeps across a conversation
│   └── my-set.yml
├── personalities/        # Voice / behaviour bundles (Jinja templates)
│   └── my-persona/
│       ├── identity.yml
│       ├── brief.yml     # optional; the persona for a single non-chat call
│       └── personality.jinja
└── focuses/              # Named scopings of the chat surface
    └── my-focus.yml

All directories are optional. A realm needs only realm.yml and at least one capability directory.