# Nebulit Event Modeling

> Nebulit Event Modeling is an agentic, real-time canvas for designing event-driven and traditionally-structured systems. Model a business process by voice or text, let AI generate wireframes/commands/read models/specifications, and connect a coding agent (via CLI, REST API, or MCP) that turns finished slices directly into tested, committed code across multiple backend stacks.

## Features

### Features

**TL;DR:** Connect an agent to your board, then either model live or build the code — see **Connect Agent** below for the full walkthrough.

```
npx @eventmodelers/cli init --stack <name>   # connect — full backend stack, for building code
npx @eventmodelers/cli init --modeling        # connect — skills + agent only, no backend, for modeling
npx @eventmodelers/cli run --modeling         # start modeling — event storming, timelines, wireframes, live on the board
npx @eventmodelers/cli run                    # start building — implements slices into real code as they're marked ready
```

Nebulit Event Modeling is an agentic collaborative canvas for designing event-driven and traditionally-structured systems. It combines visual modeling with AI assistance and multi-user collaboration.

**Try a live preview** — Explore a sample board loaded in read-only in-memory mode — no login required. (Live Preview button)

The platform provides:

- **Event Modeling Canvas** — Drag-and-drop canvas with Events, Commands, Read Models, Automations, Screens, and Model Contexts organized on timelines.
- **Real-time Collaboration** — Multiple users can model together in real time using cloud-backed boards. Changes sync instantly across all connected clients.
- **AI-Powered Modeling** — Describe a business workflow in plain text and let AI generate a complete event model including events, commands, slices, and specifications.
- **Code Generation** — Generate boilerplate code directly from your model. Supports multiple languages and frameworks through configurable code templates.
- **Multiple Storage Backends** — Choose between localStorage, IndexedDB, in-memory, or cloud storage. Switch backends without losing your boards.
- **Timeline Focus Mode** — Zoom into a single timeline for a focused editing experience, then return to the full board view.
- **Given/When/Then Specs** — Attach behavioral specifications to any element. AI can generate scenarios from your model context automatically.
- **Context Map** — Automatic context map generation from Model Context elements on the board showing bounded contexts and their relationships.
- **Screen Design** — Sketch UI mockups for screen elements directly on the canvas using AI-assisted design generation, or render real HTML/CSS mockups onto HTML Screen nodes when you need a coded-looking prototype.

## Model As You Speak

### Model As You Speak

*Dennis opened a fresh chapter before a client call and just left the mic running. As the client walked through their onboarding flow out loud — "so first they sign up, then we send a verification email, then once they click it their account activates" — events landed on the timeline one after another: UserSignedUp, VerificationEmailSent, AccountActivated. He never stopped the conversation to type anything; by the time the call ended the chapter already had a rough timeline to clean up together instead of a blank canvas to start from.*

The board has a built-in voice mode: activate a chapter, talk through what you're thinking, and a connected agent turns your words into live changes on the timeline — no typing, no switching windows. It's one of the fastest ways to get a rough model down while a conversation is still happening.

**Prerequisite:** Voice mode needs a connected agent — install the **Eventmodelers CLI** in modeling mode and keep the agent process running. See **Connect Agent** for full setup details.

**1. Install the modeling kit**
Install the Agent Modeling Kit in your project, the same as any other agentic modeling setup:
```
npx @eventmodelers/cli init --modeling
```

**2. Run the agent**
Start the long-lived agent process that listens for prompts sent from the board. Until an agent is running, the **Prompts** panel shows **no agent is connected** — you can still type or record prompts, they'll just wait until an agent picks them up.
```
npx @eventmodelers/cli run --modeling
```
*(Screenshot: Prompts panel showing no agent is connected)*

**3. Confirm the agent is connected**
As soon as the agent process connects to the platform, the panel switches to a green **agent connected** badge next to a **modeling** tag.
*(Screenshot: Prompts panel showing agent connected)*

**4. Activate a chapter**
Voice mode always targets exactly one chapter at a time. Activate one either from the **Chapter** dropdown in the Prompts panel, or by activating it directly in the Chapter Toolbar (the microphone icon).
*(Screenshots: Selecting a chapter from the Chapter dropdown; Activating a chapter from the Chapter Toolbar)*

**5. Record your instructions**
With a chapter active, click the microphone and just talk — describe events, ask for a screen, think out loud about an edge case. A recording timer confirms it's listening.
*(Screenshot: Recording indicator with a running timer)*

**6. Or type it manually**
Prefer typing? Add the same instructions manually in the prompt field instead of recording.
*(Screenshot: Typing a prompt manually into the Prompts panel)*

**7. Turn a comment into an instruction**
Any comment on any node can become an agent instruction — click the robot icon on the comment. This is a quick way to hand off small, targeted asks, like adding examples to elements that already have their fields defined.
*(Screenshot: Comment popup with a robot icon to turn it into an agent instruction)*

**Note:** Voice mode runs on the browser's Web Speech API, so for now it's only reliable in **Google Chrome**. Full support for other browsers is on the way — until then, typed prompts and comment-to-agent both work everywhere.

## Usage

### Usage

*Marc wanted to map out his team's order flow before the sprint kicked off. He opened Nebulit, clicked **New**, typed "Order Management", and hit Enter. He switched storage to **Cloud** so his colleague could join live, then right-clicked the canvas and dropped an Event into the first timeline cell. Within ten minutes he had a rough flow on the board — no setup, no shared doc, just a live canvas.*

This guide walks through the core workflows in Nebulit Event Modeling.

#### Creating a Board

Open the application and click **New** in the left sidebar to create a board. Give it a name and press Enter. You can rename or delete boards at any time using the sidebar controls.

#### Storage Backend

Click the storage indicator (top-left of the sidebar) to switch between backends:

- **LocalStorage** — Persists in browser storage. Data survives page reloads.
- **IndexedDB** — Larger capacity local storage, suitable for big boards.
- **In-Memory** — Temporary. Data is lost on page reload. Useful for demos.
- **Cloud** — Requires login. Enables real-time collaboration and cross-device sync.

#### Working with Elements

Elements are placed inside **timelines**. A timeline represents a slice of the system workflow. Right-click the canvas to open the element palette and choose from:

- **Event** — Something that happened in the system (orange).
- **Command** — An intent to change state (blue).
- **Read Model** — A query/projection (green).
- **Automation** — An automated process triggered by events (purple).
- **Screen** — A UI screen or view (pink).
- **HTML Screen** — A real, styled HTML/CSS mockup (one or more pages) instead of a wireframe sketch — use it when you want a coded-looking prototype rather than a sketchnote-style Screen.
- **Model Context** — A bounded context grouping related slices.

#### Timelines

Timelines are horizontal containers that group related elements into a flow. Create a timeline from the element palette, then drag elements into its cells. Click the focus icon on a timeline to enter focused editing mode.

#### Copy, Paste & Duplicate

Select one or more nodes (including timelines) and use `Ctrl+C` / `Ctrl+V` to copy and paste. Pasted timelines bring all their child elements along, with cell references automatically remapped. Use the context menu to duplicate a single element in place.

#### Context Map

When your board contains Model Context elements, the **Context Map** button appears in the top-right corner of the canvas. Click it to view a generated diagram of your bounded contexts and their relationships.

#### Keyboard Shortcuts

Press `?` at any time on the canvas to open the shortcuts panel. The most important bindings are listed below.

**General**

| Key | Action | Description |
|---|---|---|
| `?` | Show keyboard shortcuts | Opens the shortcuts help panel. |
| `/` | Open quick access | Opens the quick access menu. |
| `/ → T` | New Chapter | Opens quick access and creates a new timeline chapter. |
| `/ → D` | Draw Screen | Opens quick access and opens the screen designer. |
| `Tab` | Cycle timelines | Selects the next timeline (left to right) and zooms to it. |
| `+` | Zoom in | Zooms into the canvas. |
| `-` | Zoom out | Zooms out of the canvas. |
| `↑ ↓ ← →` | Pan canvas | When nothing is selected, pans the canvas. |
| `Ctrl+P` | Show all edges | Reveals all connections on the canvas. |

**Editing**

| Key | Action | Description |
|---|---|---|
| `Ctrl+Enter` | Open inline editor | Select a node to edit its content. |
| `Backspace / Delete` | Delete selected nodes | Select one or more nodes first. |
| `D` | Clear cell | Select any cell to remove its content. |
| `Ctrl+E` | Eject node from cell | Ejects the node out of its cell onto the canvas. |
| `Ctrl+-` | Remove column | Select a cell to remove its entire column. |
| `Shift+=` | Open formula modal | Opens the formula editor for the selected cell. |
| `Z` | Preview screen | On a selected screen node (image or HTML), shows it full-screen. Escape closes it. |

**Navigation**

| Key | Action | Description |
|---|---|---|
| `↑ ↓ ← →` | Navigate cells | Move between cells inside a timeline. |
| `Enter` | Select node / Open spec | Select a cell to select its node or open a spec node. |
| `Escape` | Deselect / Exit / Close | Deselects the selected cell. Also closes modals and exits focus mode. |
| `← →` | Page through spec scenarios | Navigate between scenario pages on a spec node. |
| `1 – 9` | Pin/open specification by number | First press pins the hover. Press again to open the spec modal. |

**Adding Elements**

| Key | Action | Description |
|---|---|---|
| `E` | Add Event | Select an empty cell in a swimlane row. |
| `C` | Add Command | Select an empty cell in an interaction row. |
| `R` | Add Read Model | Select an empty cell in an interaction row. |
| `S` | Add Specification / HTML Screen / Markdown | Spec lane → specification. Actor row → HTML screen. Feedback row → markdown note. |
| `A` | Add Automation | Select an empty cell in an actor row. |

**Linking**

| Key | Action | Description |
|---|---|---|
| `Space` | Select / Deselect link source | Mark a cell as the link source. Press again on the same cell to deselect. |
| `L` | Create / Remove link | After selecting a source with Space, navigate to the target and press L. |
| `Ctrl+Space` | Remove incoming edges | Removes all incoming connections from the selected cell. |
| `Ctrl+C` | Copy fields from highlighted cell | Mark source with Space, navigate to target, then press Ctrl+C. |

**Spec Editor**

| Key | Action | Description |
|---|---|---|
| `G / W / T` | Switch Given / When / Then | Jump to that section inside the scenario editor. |

## REST API

### REST API

*Marc's team spun up a new microservice every few weeks. He was tired of creating boards by hand each time, so he grabbed an API token from Settings, wrote a small CI script that called **POST /api/boards** on every new repository, and invited the team via **POST /api/org/:orga_id/invitations**. From then on, a fresh board with the right members was waiting before anyone wrote a single line of code.*

The Nebulit backend exposes a REST API for managing tokens, organizations, licenses, boards, and invitations. All endpoints require a Bearer token obtained from the account settings unless noted otherwise.

#### Authentication

Include your API token in every request as a Bearer token:

```
Authorization: Bearer <your-api-token>
```

#### Organizations

##### POST /api/org

Create a new organization. The authenticated user becomes the owner. One organization per user.

**Request body:**
```
{
  "name": "Acme Corp"
}
```

**Response:**
```
{
  "orga_id": "uuid",
  "name": "Acme Corp",
  "owner_user_id": "user-uuid",
  "created_at": "2024-01-10T08:00:00Z"
}
```

##### GET /api/org/:user_id

List all organizations a user belongs to (owned or member).

**Response:**
```
[
  {
    "orga_id": "uuid",
    "name": "Acme Corp",
    "owner_user_id": "user-uuid",
    "created_at": "2024-01-10T08:00:00Z"
  }
]
```

##### POST /api/org/:orga_id/members

Add the authenticated user to an organization as a member.

**Request body:**
```
{
  "user_id": "user-uuid"
}
```

#### Tokens

##### GET /api/org/:orga_id/tokens

List all API tokens for the authenticated user in an organization.

**Response:**
```
[
  {
    "id": "uuid",
    "description": "CI/CD pipeline token",
    "organization_id": "uuid",
    "issued_at": "2024-01-15T10:30:00Z"
  }
]
```

##### POST /api/org/:orga_id/tokens

Issue a new API token for the organization. The id field is the token value — store it securely, it will not be shown again.

**Request body:**
```
{
  "description": "CI pipeline"   // optional
}
```

**Response:**
```
{
  "id": "uuid",                  // this is the token value
  "description": "CI pipeline",
  "organization_id": "uuid",
  "issued_at": "2024-01-15T10:30:00Z"
}
```

##### DELETE /api/org/:orga_id/tokens/:id

Revoke an API token.

#### License

##### POST /api/org/:orga_id/license

Activate a commercial license for an organization.

**Request body:**
```
{
  "activation_date": "2024-01-01T00:00:00Z",
  "expiration_date": "2025-01-01T00:00:00Z",
  "seats": 10,
  "company_license": false   // optional
}
```

**Response:**
```
{
  "id": "uuid",
  "orga_id": "uuid",
  "activation_date": "2024-01-01T00:00:00Z",
  "expiration_date": "2025-01-01T00:00:00Z",
  "active": true,
  "seats": 10,
  "free_seats": 10,
  "company_license": false,
  "trial_enabled": false,
  "created_at": "2024-01-01T00:00:00Z"
}
```

##### GET /api/org/:orga_id/license/active

Check whether an organization has an active, non-expired license.

**Response:**
```
{
  "active": true,
  "description": "Trial active until January 1, 2025. 3 seats available."  // optional
}
```

##### GET /api/org/:orga_id/license/trial

Check whether a trial license is available for an organization.

**Response:**
```
{
  "enabled": true
}
```

##### POST /api/org/:orga_id/license/trial

Activate a 7-day trial license for an organization. Returns 409 if an active license already exists.

**Response:**
```
{
  "id": "uuid",
  "orga_id": "uuid",
  "active": true,
  "seats": 3,
  "trial_enabled": true,
  "expiration_date": "2024-01-08T00:00:00Z"
}
```

#### Boards

##### GET /api/boards

List all boards accessible to the authenticated user (filtered by organization when using an API token).

**Response:**
```
[
  {
    "board_id": "uuid",
    "board_name": "Order Management",
    "created_at": "2024-01-10T08:00:00Z",
    "organization_id": "uuid"
  }
]
```

##### POST /api/org/:orgId/boards/:boardId/events

Create a board by posting a board:created event. Also used to persist any board-level events (timeline rows, cells). The boardId is a client-generated UUID.

**Request body:**
```
[
  {
    "eventType": "board:created",
    "boardId": "your-new-board-uuid",
    "board_name": "Payment Processing"
  }
]
```

**Response:**
```
{ "ok": true }
```

##### DELETE /api/org/:orgId/boards/:boardId

Delete a board and all its data permanently.

##### GET /api/org/:orgId/boards/:boardId/events

Return all persisted board events in sequence order. Useful for replaying board state or auditing history.

**Response:**
```
[
  {
    "id": "event-uuid",
    "eventType": "board:created",
    "boardId": "board-uuid",
    "board_name": "Order Management",
    "timestamp": 1712920000000
  }
]
```

##### GET /api/org/:orgId/boards/:boardId/events/search

Search board events by node name. Pass ?name=OrderPlaced to find events whose title contains the query.

**Response:**
```
[
  {
    "id": "node-uuid",
    "title": "OrderPlaced",
    "type": "EVENT"
  }
]
```

##### PUT /api/org/:orgId/boards/:boardId/organization

Assign a board to an organization. The authenticated user must own the board.

**Request body:**
```
{
  "organizationId": "org-uuid"
}
```

##### DELETE /api/org/:orgId/boards/:boardId/organization

Unassign a board from its organization. The authenticated user must own the board.

#### Nodes

Nodes are the individual elements on a board (EVENTs, COMMANDs, READMODELs, SCREENs, etc.). Node data and metadata are patched separately — only send the fields that changed.

##### GET /api/org/:orgId/boards/:boardId/nodes

List all nodes on a board. Optionally filter by element type using ?type=EVENT.

**Response:**
```
[
  {
    "id": "node-uuid",
    "type": "EVENT",
    "node": { "id": "node-uuid", "data": { "title": "OrderPlaced", "type": "EVENT" } },
    "meta": { "type": "EVENT", "title": "OrderPlaced", "fields": [] },
    "hash": "a3f1c2d4",
    "version": 3
  }
]
```

##### GET /api/org/:orgId/boards/:boardId/nodes/:nodeId

Get a single node by ID. Returns 404 when the node does not exist.

##### POST /api/org/:orgId/boards/:boardId/nodes/events

Submit an array of node change events (create, update, or delete). node and meta are shallow-patched — only send changed fields. The server resolves node:created vs node:changed from DB state. Any node:created event carrying a chapterId plus cellId/cellName (i.e. placing a node on a timeline) also triggers a best-effort, fire-and-forget auto-connect to type-compatible neighbors — same rules as POST /connections.

**Request body:**
```
[
  {
    "id": "event-uuid",
    "eventType": "node:changed",
    "nodeId": "node-uuid",
    "boardId": "board-uuid",
    "timestamp": 1712920000000,
    "changedAttributes": ["meta.title"],
    "meta": { "type": "COMMAND", "title": "PlaceOrder" },
    "edges": [
      { "id": "edge-1", "source": "node-uuid", "target": "other-node-uuid" }
    ]
  }
]
```

**Response:**
```
{
  "hashes": {
    "event-uuid": "a3f1c2d4e5b6"
  }
}
```

##### POST /api/org/:orgId/boards/:boardId/nodes/:nodeId/auto-connect

Auto-connect a node to its timeline neighbors. Looks at the node's own timeline column and the previous column, and creates edge:added events to every type-compatible neighbor found there (same rules as POST /connections). Neighbors that aren't a legal pair, or that already have an edge, are reported in skipped/connected rather than causing an error. A node that isn't placed on a timeline, or isn't a connectable element type, returns an empty result.

**Response:**
```
{
  "connected": [
    { "edgeId": "edge-uuid", "source": "node-uuid", "target": "other-node-uuid", "created": true }
  ],
  "skipped": [
    { "nodeId": "other-node-uuid", "reason": "incompatible-type" }
  ]
}
```

##### POST /api/org/:orgId/boards/:boardId/connections

Create a directed edge between two nodes. Allowed pairs: COMMAND→EVENT, SCREEN→COMMAND, EVENT→READMODEL, READMODEL→SCREEN, READMODEL→AUTOMATION, AUTOMATION→COMMAND. Both nodes must belong to the same timeline.

**Request body:**
```
{
  "source": "node-uuid",
  "target": "node-uuid"
}
```

**Response:**
```
{
  "id": "edge-uuid",
  "source": "node-uuid",
  "target": "node-uuid",
  "created": true
}
```

##### DELETE /api/org/:orgId/boards/:boardId/connections

Remove the edge between two nodes. Direction is checked both ways. Returns removed=false without error if no edge exists.

**Request body:**
```
{
  "source": "node-uuid",
  "target": "node-uuid"
}
```

**Response:**
```
{
  "removed": true
}
```

#### Comments

##### GET /api/org/:orgId/boards/:boardId/nodes/:nodeId/comments

Return all comments attached to a node.

**Response:**
```
[
  {
    "id": "comment-uuid",
    "nodeId": "node-uuid",
    "boardId": "board-uuid",
    "text": "Should this be split into two slices?",
    "type": "COMMENT",
    "resolved": false,
    "timestamp": 1712920000000,
    "author": "marc@example.com"
  }
]
```

##### POST /api/org/:orgId/boards/:boardId/nodes/:nodeId/comments

Add a comment to a node. type defaults to COMMENT; use TASK for actionable items.

**Request body:**
```
{
  "text": "Should this be split into two slices?",
  "type": "COMMENT",   // COMMENT | TASK (default: COMMENT)
  "author": "marc@example.com"  // optional
}
```

**Response:**
```
{
  "id": "comment-uuid"
}
```

##### POST /api/org/:orgId/boards/:boardId/nodes/:nodeId/comments/:commentId/resolve

Mark a comment as resolved. Returns 204 on success.

##### DELETE /api/org/:orgId/boards/:boardId/nodes/:nodeId/comments/:commentId

Delete a comment permanently. Returns 204 on success.

#### Timelines & Chapters

Chapters are the top-level timeline containers on a board. Each chapter holds columns (vertical slices) and lanes (horizontal rows).

##### POST /api/org/:orgId/boards/:boardId/chapters

Create a new timeline chapter on the board at an optional canvas position. Omitting position auto-stacks it below the lowest existing chapter, sized to each chapter's actual current row-height total — not the height it was created with — so it stays safe even after add_lane/add_column growth.

**Request body:**
```
{
  "position": { "x": 100, "y": 200 }   // optional
}
```

##### GET /api/org/:orgId/boards/:boardId/chapters/bounds

Absolute canvas bounding box of every chapter on the board. width/height are derived from each chapter's current row/column layout, not a fixed default — use this to pick x/y for a new chapter (e.g. below the chapter with the largest y + height) without risking an overlap once chapters grow.

**Response:**
```
{
  "chapters": [
    { "id": "chapter-uuid", "title": "Checkout", "x": 0, "y": 0, "width": 900, "height": 1280 }
  ]
}
```

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns

Add a column to a timeline. Pass index to insert at a specific position (0 = prepend, omit = append).

**Request body:**
```
{
  "index": 2   // optional
}
```

##### DELETE /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId

Remove a column from a timeline. Returns 400 if it is the last column.

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/lanes

Add a lane (row) to a timeline.

**Request body:**
```
{
  "type": "actor",   // actor | interaction | swimlane | spec | feedback
  "label": "User",  // optional
  "index": 0        // optional insertion position
}
```

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/cells/:cellId/drop

Place an existing node into a specific cell. Returns 400 if the cell is occupied or the placement violates lane rules.

**Request body:**
```
{
  "nodeId": "node-uuid",
  "nodeType": "EVENT"
}
```

##### DELETE /api/org/:orgId/boards/:boardId/timelines/:timelineId/lanes/:rowId

Remove a lane (row) from a timeline. Returns 400 if it is the last lane.

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId/move

Reorder a column within its timeline.

**Request body:**
```
{
  "toIndex": 2
}
```

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/lanes/:rowId/move

Reorder a lane (row) within its timeline.

**Request body:**
```
{
  "toIndex": 1
}
```

##### DELETE /api/org/:orgId/boards/:boardId/timelines/:timelineId/cells/:cellId

Clear a cell — removes the placed node from the cell and deletes it.

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/nodes/move

Move a node from its current cell to another cell in the same timeline.

**Request body:**
```
{
  "movedNodeId": "node-uuid",
  "toCellId": "cell-uuid"
}
```

##### PUT /api/org/:orgId/boards/:boardId/timelines/:timelineId/position

Update the canvas (x, y) position of a timeline node.

**Request body:**
```
{
  "x": 400,
  "y": 120
}
```

#### Slices

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/slices

Create a complete slice (1 column + matching nodes) inside a timeline. state-change = Command+Event+Spec, state-view = ReadModel+Event+Spec, automation = Automation+Event.

**Request body:**
```
{
  "type": "state-change",   // state-change | state-view | automation
  "index": 2                // optional column insertion index
}
```

**Response:**
```
{
  "columnId": "col-uuid",
  "nodes": {
    "command": "node-uuid",
    "event": "node-uuid",
    "spec": "node-uuid"
  }
}
```

#### Slice Data

Read-only endpoints that project board nodes into a structured element graph — useful for code generation, analysis, and CI pipelines. Both endpoints require a Bearer token and board access.

##### GET /api/org/:orgId/boards/:boardId/slicedata/slices

List all slices on a board with their id, title, status, and context. Pass contextName to return only slices belonging to that MODEL_CONTEXT.

**Response:**
```
{
  "slices": [
    {
      "id": "node-uuid",
      "title": "PlaceOrder",
      "status": "InProgress",
      "contextId": "ctx-uuid",
      "contextName": "Order Management"
    }
  ]
}
```

##### GET /api/org/:orgId/boards/:boardId/slicedata

Build the full element graph for a context — events, commands, read models, screens, automations, specs, and their dependencies. Pass contextId, or contextName matched against MODEL_CONTEXT titles first and timeline titles second (a timeline with no assigned/connected context scopes the result to just that timeline). Optionally filter to a single slice with sliceId. Pass format (default json) to encode the result as yaml, textual (a compact AI-prompt-friendly markdown dump), toon (token-efficient tabular encoding), emlang, or esdm (https://www.esdm.io) instead — same six formats offered in the board's Code view. json is returned as-is; every other format is a transform of it, with the response Content-Type and body changed to match (a raw encoded string, not another JSON envelope). esdm's domain/bounded-context naming is derived entirely from the resolved context/timeline — there's no separate parameter for it.

**Response:**
```
{
  "slices": [
    {
      "id": "node-uuid",
      "title": "PlaceOrder",
      "status": "InProgress",
      "sliceType": "STATE_CHANGE",
      "chapter": "Checkout",
      "context": "Order Management",
      "commands": [ { "id": "...", "title": "PlaceOrder", "type": "COMMAND", "fields": [], "dependencies": [] } ],
      "events":   [ { "id": "...", "title": "OrderPlaced",  "type": "EVENT",   "fields": [], "dependencies": [] } ],
      "readmodels": [],
      "screens": [],
      "processors": [],
      "tables": [],
      "specifications": [],
      "aggregates": ["order"]
    }
  ]
}
```

#### Specifications

Attach Given/When/Then scenarios to a timeline column. The spec node is created automatically if one does not exist yet.

##### GET /api/org/:orgId/boards/:boardId/timelines/:timelineId/spec-info

Return all valid EVENTs, COMMANDs, and READMODELs in a timeline — the elements that may legally appear as given/when/then steps when building specifications.

**Response:**
```
{
  "events":     [ { "id": "node-uuid", "title": "OrderPlaced" } ],
  "commands":   [ { "id": "node-uuid", "title": "PlaceOrder" } ],
  "readmodels": [ { "id": "node-uuid", "title": "OrderSummary" } ]
}
```

##### POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId/scenarios

Append one or more GWT scenarios to a column's spec node. Accepts a single scenario object or an array. The spec node is auto-created if missing. Returns 409 on duplicate title.

**Request body:**
```
[
  {
    "id": "scenario-uuid",
    "title": "Successful order placement",
    "given": [ { "id": "event-uuid", "title": "CartConfirmed", "type": "EVENT", "fields": [] } ],
    "when":  [ { "id": "cmd-uuid",   "title": "PlaceOrder",    "type": "COMMAND", "fields": [] } ],
    "then":  [ { "id": "event-uuid2","title": "OrderPlaced",   "type": "EVENT",   "fields": [] } ]
  }
]
```

**Response:**
```
{
  "specNodeId": "node-uuid",
  "added": 1,
  "isNewNode": false,
  "scenarios": [ { "id": "scenario-uuid", "title": "Successful order placement" } ]
}
```

#### Images

Upload and manage images attached to SCREEN nodes. All image endpoints use multipart/form-data unless noted.

##### POST /api/org/:orgId/boards/:boardId/images/:imageId

Upload a file to replace an existing image (e.g. a screen node's image). Fires node:changed. imageId is the node UUID.

**Request body:**
```
multipart/form-data
  file: <binary>   // required
```

##### POST /api/org/:orgId/boards/:boardId/imagesnapshots/:imageId

Upload a snapshot variant of an image (stored separately from the main image). Fires node:changed.

**Request body:**
```
multipart/form-data
  file: <binary>   // required
```

##### POST /api/org/:orgId/boards/:boardId/image-nodes/:nodeId

Create a new SCREEN image node from a file upload. Uploads the image and fires node:created.

**Request body:**
```
multipart/form-data
  file:       <binary>     // required
  chapterId:  "uuid"       // required — timeline the node belongs to
  cellName:   "col-uuid"   // required — cell within the timeline
```

##### POST /api/org/:orgId/boards/:boardId/images/:imageId/sketch

Generate a webp UI sketch from a structured grid description (JSON) and upload it as the node's image. Accepts the same shape as the AI screenDesignInstructions prompt — an elements array on a 50×40 grid.

**Request body:**
```
{
  "elements": [
    { "type": "rect",   "x": 0, "y": 0, "w": 50, "h": 5, "label": "Header" },
    { "type": "button", "x": 2, "y": 7, "w": 10, "h": 3, "label": "Submit" }
  ],
  "description": "Checkout screen"   // optional — stored as node meta.description
}
```

##### POST /api/org/:orgId/boards/:boardId/image-nodes/:nodeId/sketch

Same as the image sketch endpoint, but also creates the node if it does not exist yet. Requires chapterId and cellName in the JSON body alongside elements.

**Request body:**
```
{
  "elements": [ ... ],
  "chapterId": "uuid",
  "cellName":  "col-uuid",
  "description": "Order confirmation screen"
}
```

#### HTML Screens

HTML Screen nodes render one or more real HTML/CSS pages instead of a wireframe sketch — useful for a coded-looking prototype. Each page is a standalone body-only fragment; the server strips `<script>` tags, inline event handlers, and `javascript:` URIs before persisting, and wraps each page in its own `<html><head>` (Bulma 0.9.4 + a resize script) `<body>` at render time.

##### POST /api/org/:orgId/boards/:boardId/html-screen-nodes/:nodeId

Create a new HTML_SCREEN node with the given pages and place it into a timeline cell. nodeId is client-generated (e.g. uuidgen). Fires node:created. Returns 204 No Content.

**Request body:**
```
{
  "chapterId": "uuid",        // required — timeline the node belongs to
  "cellName":  "B2",          // required — cell within the timeline
  "pages": ["<div>...</div>"] // required — one or more body-only HTML fragments
}
```

##### POST /api/org/:orgId/boards/:boardId/html-screens/:nodeId

Replace the pages on an existing HTML_SCREEN node. Always send the complete pages array, not just the changed or new entry. Fires node:changed. Returns 204 No Content.

**Request body:**
```
{
  "pages": ["<div>...</div>", "<div>...</div>"]
}
```

##### GET /api/org/:orgId/boards/:boardId/html-screens/:nodeId/verify

Confirm the node exists, is type HTML_SCREEN, and has at least one non-empty page. Use this after a create/update call to verify the render actually took effect.

**Response:**
```
{
  "valid": true,
  "error": null   // populated with a reason when valid is false
}
```

#### Drawing

Drawing nodes are freehand SVG annotations on the canvas — a pen stroke (`kind: "path"`), a rectangle outline (`kind: "rect"`), or a text label (`kind: "text"`). They're canvas annotations, not business elements, so no chapter/cell placement applies. `path` is an SVG path `d` string in local `0..width,0..height` coordinates. There is no separate endpoint for grouping/circling elements — compute a bounding box from `GET .../nodes` (unioning the target elements' positions/sizes, plus padding) and draw a `rect` or `path` loop around it like any other drawing.

##### POST /api/org/:orgId/boards/:boardId/drawing/draw

Create a drawing node (meta.type DRAWING). Fires node:created.

**Request body:**
```
{
  "kind":        "path",          // required — "path" | "rect" | "text"
  "x":           100,             // required
  "y":           100,             // required
  "width":       200,             // required
  "height":      120,             // required
  "path":        "M0,0 L200,120", // required when kind is "path" — SVG path "d" string
  "content":     "Note text",     // used when kind is "text"
  "stroke":      "#1e293b",       // CSS color, default #1e293b
  "strokeWidth": 10,              // default 10
  "arrowStart":  false,           // "path" kind only — arrowhead at the start of the stroke
  "arrowEnd":    true,            // "path" kind only — arrowhead at the end of the stroke
  "border":      false,           // "text" kind only — draw a rectangle outline around the label
  "nodeId":      "uuid"           // optional caller-supplied id; a uuid is generated when omitted
}
```

**Response:**
```
{ "nodeId": "uuid" }
```

##### GET /api/org/:orgId/boards/:boardId/drawing/:drawingId/nodes

Given an existing node (e.g. a loop drawn via drawing/draw), returns the ids of every other node on the board whose bounding box is fully contained within its bounding box (containment, not mere overlap).

**Response:**
```
{ "nodeIds": ["uuid", "uuid"] }
```

#### Snapshots

Snapshots are portable JSON exports of one or more boards. They can be used to share a board state, restore it on another account, or keep time-based backups. Snapshots expire after 30 days. **Snapshot endpoints require user authentication (not API token).**

##### GET /api/snapshots

List all snapshots belonging to the authenticated user.

**Response:**
```
[
  {
    "id": "snapshot-uuid",
    "name": "Sprint 12 baseline",
    "expiry": "2024-02-10T00:00:00Z",
    "shared": true
  }
]
```

##### POST /api/snapshots

Create a snapshot from a client-uploaded JSON file (multipart/form-data). The file must be a valid snapshot JSON with a boards key. Max 20 snapshots per user — oldest is evicted.

**Request body:**
```
multipart/form-data
  payloadFile: <binary>       // required — snapshot JSON file
  name:        "Sprint 12"    // required
  retention:   30             // optional, days (max 30)
```

**Response:**
```
{
  "ok": true,
  "id": "snapshot-uuid",
  "link": "https://app.eventmodelers.ai/snapshot/snapshot-uuid"
}
```

##### POST /api/takesnapshot

Create a snapshot directly from the current DB state of a board. Useful for automated backups without needing to download the board first.

**Request body:**
```
{
  "boardId":   "board-uuid",
  "name":      "Pre-deploy backup",
  "retention": 30    // optional, days (max 30)
}
```

**Response:**
```
{
  "ok": true,
  "id": "snapshot-uuid",
  "link": "https://app.eventmodelers.ai/snapshot/snapshot-uuid"
}
```

##### GET /api/snapshots/:id

Download the full snapshot payload (boards, nodes, edges, comments). Returns the decompressed JSON.

##### DELETE /api/snapshots/:id

Delete a snapshot and its stored file.

#### Realtime Polling

##### GET /api/org/:orgId/boards/:boardId/nodes/changes

Return node IDs changed since a sequence checkpoint. Clients store the returned latestSeq and pass it as since on the next poll to fetch only updated nodes. This is a lightweight alternative to WebSocket sync.

**Response:**
```
{
  "nodeIds":   ["node-abc", "node-xyz"],
  "latestSeq": 42
}
```

#### Extensions

##### GET /api/org/:orgId/boards/:boardId/extensions

List all extension configurations for a board.

**Response:**
```
[
  {
    "board_id": "board-uuid",
    "type": "git",
    "enabled": true,
    "config": { "repo": "https://github.com/acme/model.git", "branch": "main" }
  }
]
```

##### PUT /api/org/:orgId/boards/:boardId/extensions/:type

Enable or reconfigure an extension. Supported types: git. config is extension-specific and merged with the existing config on update.

**Request body:**
```
{
  "enabled": true,
  "config": {
    "repo":   "https://github.com/acme/model.git",
    "branch": "main",
    "token":  "ghp_..."    // optional PAT for private repos
  }
}
```

**Response:**
```
{
  "board_id": "board-uuid",
  "type": "git",
  "enabled": true,
  "config": { "repo": "https://github.com/acme/model.git", "branch": "main" }
}
```

#### Git Extension

When the git extension is enabled for a board, the model is automatically committed to a repository after every save. These endpoints let you browse history and restore older versions.

##### GET /api/org/:orgId/boards/:boardId/extensions/git/revisions

List all git commits for the board branch. Returns 404 if the git extension is not enabled.

**Response:**
```
[
  {
    "hash": "a1b2c3d",
    "date": "2024-03-01T14:22:00Z",
    "message": "Added PaymentProcessed event"
  }
]
```

##### GET /api/org/:orgId/boards/:boardId/extensions/git/snapshot

Build a snapshot payload from a specific git commit. Pass ?hash=<commit-hash>. Returns gzip-compressed JSON (Content-Type: application/gzip).

##### POST /api/org/:orgId/boards/:boardId/extensions/git/restore

Create a new board from a specific git revision. The original board is untouched — a new board is created with all nodes, edges, comments, and images from that commit.

**Request body:**
```
{
  "hash": "a1b2c3d"
}
```

**Response:**
```
{
  "boardId":   "new-board-uuid",
  "boardName": "Order Management (restored)"
}
```

#### Archiving

Archived boards are compressed and stored in organization-scoped storage. Archiving frees up active-board capacity while keeping the data accessible.

##### GET /api/org/:orgId/archive/boards

List all archived boards for an organization.

**Response:**
```
[
  {
    "archive_id": "uuid",
    "board_id":   "board-uuid",
    "description": "Order Management",
    "orga_id":    "org-uuid",
    "archived_at": "2024-03-15T09:00:00Z"
  }
]
```

##### POST /api/org/:orgId/archive/boards

Archive a board. The board must belong to the organization. Returns 409 if already archived.

**Request body:**
```
{
  "boardId": "board-uuid"
}
```

**Response:**
```
{
  "ok": true,
  "archiveId": "uuid"
}
```

##### DELETE /api/org/:orgId/archive/boards/:archiveId

Delete an archived board permanently. Returns 409 if the board is not archived or already deleted.

#### Config Import

##### POST /api/org/:orgId/boards/:boardId/import-config

Import an EventModelingJson config and persist it to the board. Accepts either multipart/form-data with a file field or an application/json body. The payload must have a slices array.

**Request body:**
```
// multipart/form-data
file: <binary>   // JSON file with { slices: [...] }

// or application/json
{
  "slices": [ ... ]
}
```

**Response:**
```
{
  "nodes": [ ... ],
  "edges": [ ... ]
}
```

#### Invitations

##### POST /api/org/:orga_id/invitations

Invite a user to an organization. Returns a token-based invite link.

**Request body:**
```
{
  "role": "user",               // "user" or "admin"
  "description": "Invited via CI"  // optional
}
```

**Response:**
```
{
  "invitation_id": "uuid",
  "type": "organization",
  "token": "abc123",
  "orga_id": "uuid",
  "confirmed": false,
  "created_at": "2024-01-12T09:00:00Z"
}
```

##### POST /api/org/:orga_id/invitations/board

Invite a user to a specific board within an organization.

**Request body:**
```
{
  "board_id": "uuid",
  "role": "user",               // "user" or "admin"
  "description": "Optional note"   // optional
}
```

**Response:**
```
{
  "invitation_id": "uuid",
  "type": "board",
  "token": "abc123",
  "board_id": "uuid",
  "orga_id": "uuid",
  "confirmed": false,
  "created_at": "2024-01-12T09:00:00Z"
}
```

##### GET /api/org/:orga_id/invitations/:invitation_id/can-confirm

Check whether an invitation can still be confirmed — validates expiry and available license seats.

**Response:**
```
{
  "can_confirm": false,
  "reason": "No free seats available in the organization license"  // when can_confirm is false
}
```

##### DELETE /api/org/:orga_id/invitations/:invitation_id

Revoke an invitation. Only the original inviter can revoke.

##### GET /api/invitations/token/:token

Look up an invitation by its token value. Used to display invite details before confirmation.

**Response:**
```
{
  "invitation_id": "uuid",
  "type": "organization",
  "role": "user",
  "orga_id": "uuid",
  "board_id": null,
  "confirmed": false,
  "orga_name": "Acme Corp",
  "board_name": null
}
```

##### POST /api/invitations/:token/confirm

Confirm an invitation using its token. Grants the user access to the org or board.

## MCP

### MCP

*Marc connected Claude Code to his board in two ways: as himself for exploratory modeling sessions, and as a CI bot for automated analysis in the pipeline. The user flow opened a browser login he was already signed into — done in seconds. The bot flow used an API token he already had — one config line, no browser.*

Nebulit exposes an MCP (Model Context Protocol) server at `/mcp` so AI agents can read and write boards programmatically. Two authentication flows are supported: **user login via OAuth** (for individual developers) and **bot tokens** (for automation and CI/CD).

- **User Flow** — Authenticate as yourself using your Supabase account. Supports email/password, magic link, Google, GitHub, and GitLab.
- **Bot Flow** — Authenticate as a service account using an org-scoped API token. No browser required — ideal for CI/CD and automation.

#### User Flow — OAuth Login (Individual)

Use this when you want to connect Claude Code (or another MCP client) as your own Eventmodelers account. The MCP server uses the OAuth 2.0 PKCE flow — the client handles token exchange automatically after you log in once.

##### Setup — Claude Code

1. **Register the MCP server (no token needed)**
   Run in your terminal — or add to `~/.claude.json` under the relevant project:
   ```
   claude mcp add eventmodelers --transport http https://api.eventmodelers.ai/mcp
   ```
   Or add manually:
   ```
   // ~/.claude.json  →  projects → <your-project-path> → mcpServers
   {
     "eventmodelers": {
       "type": "http",
       "url": "https://api.eventmodelers.ai/mcp"
     }
   }
   ```
2. **Authenticate**
   Start Claude Code. It will detect the unauthenticated MCP server and show an **Authenticate** button. Click it — your browser opens the Eventmodelers login page. You can also trigger it manually at any time with `/mcp`.
3. **Sign in**
   The login page offers the same options as the main app:
   - Email + password
   - Magic link (passwordless email)
   - Google, GitHub, or GitLab OAuth

   If you are already logged into Eventmodelers in the browser, the page redirects automatically — no interaction needed.
4. **Done**
   Claude Code completes the OAuth handshake and shows "Authentication successful". The tools are now available. Tokens refresh automatically — you will not need to log in again unless you explicitly sign out.

##### Setup — Claude Desktop

Open **Claude Desktop → Settings → Developer → Edit Config** and add to `claude_desktop_config.json`:
```
{
  "mcpServers": {
    "eventmodelers": {
      "type": "http",
      "url": "https://api.eventmodelers.ai/mcp"
    }
  }
}
```
Restart Claude Desktop. On the next conversation that uses Eventmodelers tools, it will prompt you to authenticate via the browser.

#### Bot Flow — API Token (Automation / CI)

Use this for non-interactive environments: CI/CD pipelines, scripts, or a shared team agent. An API token is scoped to one organization and does not require a browser login.

##### Step 1 — Issue a token

Go to Account → API Tokens and click **New Token**. Give it a description (e.g. "Claude Code — CI pipeline") and copy the token value. It is shown only once — store it in a secrets manager or your `.env`.

##### Step 2 — Configure the MCP server

Add the token as an `x-token` header in your MCP client config:

Claude Code — `~/.claude.json`:
```
// projects → <your-project-path> → mcpServers
{
  "eventmodelers": {
    "type": "http",
    "url": "https://api.eventmodelers.ai/mcp",
    "headers": {
      "x-token": "<your-api-token>"
    }
  }
}
```

Claude Desktop — `claude_desktop_config.json`:
```
{
  "mcpServers": {
    "eventmodelers": {
      "type": "http",
      "url": "https://api.eventmodelers.ai/mcp",
      "headers": {
        "x-token": "<your-api-token>"
      }
    }
  }
}
```

`Authorization: Bearer <your-api-token>` is also accepted in place of `x-token` — the same token, just carried in the standard header. Use whichever fits your MCP client; if a request sends both, `x-token` takes precedence.

##### Step 3 — Verify

Restart the client. No browser authentication is needed. In Claude Code run `/mcp` — the server should show as connected immediately. You can also test with curl:
```
curl -s -X POST https://api.eventmodelers.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-token: <your-api-token>" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0" }
    }
  }'
```
A valid token returns the server's `InitializeResult`. A wrong or revoked token returns `401`.

##### Revoking a token

Go to Account → API Tokens, find the token by its description, and click **Revoke**. The token stops working immediately.

#### Available Tools

**Read**

| Tool | Description |
|---|---|
| `list_boards` | All boards for your organization. |
| `get_nodes` | Nodes on a board, filterable by type and/or a partial title match. |
| `get_node` | Single node by ID. |
| `get_node_comments` | Comments on a node. |
| `get_board_events` | All events in sequence order. |
| `search_board_events` | Search events by node name. |
| `get_chapter_bounds` | Absolute canvas bounding box of every chapter on a board, sized to each one's actual current row/column layout — not a guessed default. Use before picking x/y for a new chapter to avoid overlapping one that grew since it was created. |
| `validate_model` | Server-side Event Modeling structural checklist over one chapter — compact findings only (unplaced nodes, backward arrows with the todo-list exception, zero/multi-issuer commands, sourceless read models, screen-per-column collisions, missing scenarios). Replaces the repeated manual validation pass. |
| `get_board_outline` | One chapter's structure as a compact outline — per-column node lists ({id, type, title, lane}) plus a flat edge list, no HTML pages / field bodies / meta. The cheap "what is where and how is it wired" fetch. |

**Write**

| Tool | Description |
|---|---|
| `submit_node_events` | Raw node create / update / delete. `autoConnect: false` places nodes without wiring them to their timeline neighbors; `compact: true` returns `{persisted: <count>}` instead of the per-node hash map. `add_scenario`, `add_storyline` and `set_connections` take the same `compact` flag to suppress their full-object echo. |
| `create_chapter` | Add a new timeline chapter. |
| `add_column / delete_column / delete_columns` | Add or remove timeline columns. `add_column` accepts `count` to insert several columns contiguously in one call, and `beforeNodeId`/`afterNodeId` to position the insertion from an already-placed node instead of a computed index. `delete_columns` is the batch form of `delete_column` (an array of `columnIds`, applied in order). |
| `add_lane` | Add a row — actor, interaction, swimlane, spec, or feedback. |
| `drop_node_to_cell` | Place an existing node into a specific cell. |
| `create_slice` | Create a full slice (state-change, state-view, or automation). |
| `create_drawing` | Freehand SVG annotation on the canvas — pen stroke (with optional arrowheads), rectangle, or text label. Also used to draw a border/loop around a computed bounding box for grouping. |

**High-level**

| Tool | Description |
|---|---|
| `place_element` | Place a COMMAND, EVENT, or READMODEL into the correct lane automatically. Pass `lane` (row id or label) to target a specific one when the timeline has multiple lanes of that type — e.g. several swimlanes. `autoConnect: false` places without wiring to timeline neighbors. |
| `list_slices` | All slices with id, title, and status. |
| `get_slice_data` | Full element graph for a MODEL_CONTEXT. |
| `create_screen / create_screens` | Create a SCREEN or HTML_SCREEN node (image, sketch, or HTML content) and place it into a cell, atomically. Pass `fields` to set `meta.fields` in the same call. `autoConnect: false` places without wiring to timeline neighbors. The batch form (plural, HTML content only) takes an array of screens and applies each independently — prefer it whenever creating more than one HTML screen with content already authored. |
| `render_screen` | Update an existing screen's content — a 50×40 grid wireframe or an HTML_SCREEN's pages. |
| `verify_screen` | Confirm a screen node exists and has rendered content, regardless of its type. |

## Connect Agent

### Connect Your Agent

*Marc wanted to run a proper event storming session but his domain experts were scattered across time zones. He ran `npx @eventmodelers/cli init --modeling`, pasted his token, and opened Claude Code. He typed **/timeline** and started describing the returns process in plain English. As he talked, events appeared on the board live — ReturnRequested, ItemInspected, RefundIssued — each one placed automatically. His colleagues watched the board update in real time from their own browsers. When the session wrapped he ran **/wdyt** and got a list of questions posted directly as comments on the nodes that needed more thought.*

The **Eventmodelers CLI** turns Claude Code into a collaborative event modeling partner. Install it once and get a set of skills that let you run event storming sessions, generate wireframes, and analyze your model — all live on the board. A background agent loop picks up prompts sent from the platform and executes them autonomously in your project.

#### Getting your connection details

Navigate to **/account** and open the **Agent** tab. Click the green **Connect** button next to your board — it copies a ready-to-use install command including your token, organization ID, and board ID directly to the clipboard.

*(Screenshot: Account page showing the green Connect button)*

#### Installation

```
npx @eventmodelers/cli init --modeling
```

The installer asks for your API token and organization ID, then creates a `.agent-modeling-kit/` folder in your project with config resolution for the agent loop and your credentials. Skills are installed into `.claude/skills/` and are available in Claude Code immediately. See **CLI Configuration** for the full command reference, including non-interactive flags and env vars.

#### Running the agent

A modeling-kit install has exactly one runtime mode — `run` always requires `--modeling`. It keeps one Claude process warm across turns instead of spawning a fresh one per prompt, for low-latency voice/live use: prompts are written straight to the process's stdin, direct-dispatch, with no `tasks.json` queue involved. It requires a `boardId` in your config — a modeling agent always runs for exactly one board:

```
npx @eventmodelers/cli run --modeling
```

Plain `run` (and `--ollama`/`--bash`) are for the backend stacks' cold-spawn, `tasks.json`-driven loop instead — see **CLI Configuration** below. Neither mode falls back to the other: a modeling-kit install rejects plain `run`, and a backend-stack install rejects `--modeling`.

By default the loop logs a condensed, high-level line per step. Add `--verbose` to log every tool call's full input (commands, skill args, file paths) and the assistant's reasoning text as well — useful when you need to see exactly what a turn did, not just that it did something:

```
npx @eventmodelers/cli run --modeling --verbose
```

#### MCP server

Registering the Eventmodelers MCP server in `.claude/settings.json` is a separate step from installation, so it doesn't force a `.claude/settings.json` edit on setups that don't want one:

```
npx @eventmodelers/cli init-mcp
```

It also offers to connect the same MCP server to another harness (VS Code, Cursor, Windsurf). To connect Claude Code globally across all projects yourself:

```
claude mcp add eventmodelers --transport http https://api.eventmodelers.ai/mcp
```

For browser automation skills like `/discover-storyboard`, add the Chrome DevTools MCP:

```
claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest
```

#### Configuration

Credentials are stored in `.eventmodelers/config.json` at your project root (automatically gitignored) — shared by every kit installed in that project. You can edit this file directly to switch tokens or organizations without re-running the installer.

```
// .eventmodelers/config.json
{
  "organizationId": "<your-org-id>",
  "token": "<your-api-token>",
  "baseUrl": "https://api.eventmodelers.ai"
}
```

Config resolution is hierarchical: every command walks up from the current directory looking for a `.eventmodelers/config.json` in an ancestor directory, then — as a last resort, for projects that don't live under your home directory at all — checks `~/.eventmodelers/config.json`. That means you can store your `organizationId` and `token` once, globally, and only ever set a project-specific `boardId` per checkout:

```
npx @eventmodelers/cli init-config --global   # writes organizationId + token to ~/.eventmodelers/config.json
```

Run `npx @eventmodelers/cli init-config` (without `--global`) any time you want to (re)configure credentials for just the current project without re-running a full install — see **CLI Configuration** for the complete reference, including direct `--token` / `--board-id` / `--organization-id` / `--base-url` flags and env vars.

#### Manage the installation

```
npx @eventmodelers/cli status      # check what's installed
npx @eventmodelers/cli uninstall   # remove skills and agent
```

## CLI Configuration

### CLI Configuration

`@eventmodelers/cli` is the single installer for every stack — pick one, scaffold it, and connect it to a board. This CLI has a lot of surface area by now: most people only ever need the handful of commands under **Everyday commands** below. Everything under **Power users** further down — CI/scripted installs, multi-project config, MCP, and the board-status commands — is for customizing the install itself; skip it until you actually need it.

#### Getting started

Every stack is the same two commands: `init` scaffolds and configures it, `run` starts the agent against your board. Per-stack examples:

**node** — `npx @eventmodelers/cli init --stack node`
```
npx @eventmodelers/cli init --stack node   # scaffold + configure
npx @eventmodelers/cli run                 # start the agent
```
*Diego was building a returns workflow for an online store. He ran the installer, pasted his board's connection JSON, and had `.build-kit/` scaffolded with a working Express + event store skeleton in under a minute. He ran `run`, flipped the first slice to Planned on the board, and watched the ReturnRequested command handler land as a passing test four minutes later.*

**supabase** — `npx @eventmodelers/cli init --stack supabase`
```
npx @eventmodelers/cli init --stack supabase   # scaffold + configure
npx @eventmodelers/cli run                     # start the agent
```
*Aiko wanted realtime updates without standing up her own WebSocket server. The installer scaffolded a Supabase project with Realtime broadcast already wired into `src/common/`, and RLS-ready auth helpers in `src/supabase/`. Fifteen minutes later her OrderShipped projection was pushing live updates straight to a demo page.*

**axon** — `npx @eventmodelers/cli init --stack axon`
```
npx @eventmodelers/cli init --stack axon   # scaffold + configure
npx @eventmodelers/cli run                 # start the agent
```
*Lars' team was rebuilding a loan-approval service on Axon Framework. The installer dropped in the aggregate/command-handler skill set alongside a Maven-ready quickstart. The agent picked the first Planned slice, generated the LoanApplication aggregate and its @CommandHandler, and ran mvn test before flipping the slice to Done.*

**cratis-csharp** — `npx @eventmodelers/cli init --stack cratis-csharp`
```
npx @eventmodelers/cli init --stack cratis-csharp   # scaffold + configure
npx @eventmodelers/cli run                          # start the agent
```
*Noor's insurance-claims backend was already on Cratis. The installer matched her existing conventions file, and the first agent-built slice — ClaimSubmitted → ClaimAssessed — came back compiled, tested, and committed without her touching an IDE.*

**modeling only** — `npx @eventmodelers/cli init --modeling`
```
npx @eventmodelers/cli init --modeling   # skills + agent loop only, no backend scaffold
npx @eventmodelers/cli run --modeling    # start the agent (modeling-kit always needs --modeling)
```
*Before any code existed, Youssef ran `init --modeling` in an empty folder just to get skills and the agent loop — no backend opinion at all. He opened Claude Code, typed **/timeline**, and ran a 40-minute event-storming session with his domain experts before a single line of implementation code was ever discussed.*

#### Everyday commands

```
npx @eventmodelers/cli init --stack <name>   # scaffold a stack + install + configure (alias: install)
npx @eventmodelers/cli init --stack <name> --global   # same, but skills go to ~/.claude/skills/ (every project)
npx @eventmodelers/cli init --modeling       # skills + agent loop only, no backend scaffold — mutually exclusive with --stack
npx @eventmodelers/cli init --modeling --global   # same, but skills go to ~/.claude/skills/ (every project)
npx @eventmodelers/cli run                   # backend stacks only — start the agent loop (ralph-claude.js) from the installed kit dir
npx @eventmodelers/cli run --ollama          # same, via local Ollama (ralph-ollama.js)
npx @eventmodelers/cli run --bash            # bash-only loop, no realtime (ralph.sh)
npx @eventmodelers/cli run --modeling        # modeling-kit only, and required for it — warm process, direct-dispatch, requires boardId
npx @eventmodelers/cli run --verbose         # same as run, but logs full tool input + assistant reasoning text (ralph-claude.js / --modeling only)
npx @eventmodelers/cli fetch --context <name>                       # pull full slice detail for one context on the board into .slices/
npx @eventmodelers/cli fetch --context <name> --format yaml         # dump the context as yaml/textual/toon/emlang/esdm instead (default: json)
npx @eventmodelers/cli fetch --context <name> --slice-id <id>       # same, then print just the matching slice (requires --format json)
npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the matching slice (case-insensitive, requires --format json)
npx @eventmodelers/cli stacks                # list available stacks
npx @eventmodelers/cli status                # check what's installed
npx @eventmodelers/cli config                # print the fully resolved config (file + env), token masked
```

`run` is a thin dispatcher — it finds the installed kit dir (whatever it's named for the stack) and execs the runner file already sitting in it. The agent loop's actual logic stays in the scaffolded `<kit-dir>/`, not in this package, since you — and the agent itself, via `AGENT.md` — may customize those files per project.

`fetch` calls the `slicedata` API directly for the required `--context` and writes the result into `.slices/`. `--format` picks the exporter: `json` (default) builds the full `.slices/<context>/<slice>/slice.json` folder structure; `yaml`, `textual`, `toon`, `emlang`, and `esdm` are each dumped instead as a single `.slices/<context>/slicedata.<ext>` file (a transform of the same data — `textual` is JSON-wrapped, `emlang`/`esdm` are YAML documents, `toon` is its own format). Pass `--slice-id` or `--slice-title` to print just one slice's details (title, id, status, file path) after the fetch completes — both require `--format json`, since only that format produces the parsed slice list they look up against. If credentials are missing or the API rejects them (401/403/404), it prompts for credentials the same way `init-config` does and retries once.

##### Examples: run

**run** — `npx @eventmodelers/cli run`
Starts `ralph-claude.js` — the realtime agent and task loop in one process:
```
▶ Starting .build-kit/ralph-claude.js...

Ralph — kit: /Users/you/project/.build-kit
         project: /Users/you/project
```

**run --ollama** — `npx @eventmodelers/cli run --ollama`
Same loop, but driven by a local Ollama model instead of Claude Code — run `ollama serve` first:
```
▶ Starting .build-kit/ralph-ollama.js...

[ralph-ollama] model=qwen3:8b
Ralph — kit: /Users/you/project/.build-kit
         project: /Users/you/project
```

**run --bash** — `npx @eventmodelers/cli run --bash`
The bash-only loop — no realtime WebSocket connection, just polls the kit dir for status changes:
```
▶ Starting .build-kit/ralph.sh...

Ralph — kit: /Users/you/project/.build-kit
         project: /Users/you/project
```

**run --verbose** — `npx @eventmodelers/cli run --modeling --verbose`
Same loop, but every tool call logs its full input and the assistant's reasoning text instead of just the tool name — works with plain `run` too, only `--ollama`/`--bash` don't support it:
```
▶ Starting modeling loop (warm Claude process) for .agent-modeling-kit...

Deciding which slice to build next based on the current timeline...
→ Skill(place-element) { "type": "COMMAND", "cellName": "B3", "title": "ConfirmOrder" }
→ Bash { "command": "npx @eventmodelers/cli fetch --context Checkout" }
```

##### Examples: fetch

**fetch** — `npx @eventmodelers/cli fetch --context Checkout`
Pulls the given context's slice detail from the board and writes it into `.slices/`:
```
▶ Fetching context "Checkout" from https://api.eventmodelers.ai (board <uuid>)...
✅ Fetched 7 slices from context "Checkout" → .slices/
```

**fetch --slice-title** — `npx @eventmodelers/cli fetch --context Checkout --slice-title PlaceOrder`
Same fetch, then prints just the matching slice instead of leaving you to dig through `.slices/`:
```
▶ Fetching context "Checkout" from https://api.eventmodelers.ai (board <uuid>)...
✅ Fetched 7 slices from context "Checkout" → .slices/

Requested slice:
  Title:  PlaceOrder
  ID:     <uuid>
  Status: In Progress
  Folder: .slices/checkout/place-order/slice.json
```

**fetch --format** — `npx @eventmodelers/cli fetch --context Checkout --format yaml`
Non-`json` formats skip the per-slice folder structure and write a single file instead (here, `yaml`; swap in `textual`, `toon`, `emlang`, or `esdm` the same way). `--slice-id`/`--slice-title`/`--spec-kitty` aren't available in this mode:
```
▶ Fetching context "Checkout" from https://api.eventmodelers.ai (board <uuid>)...
✅ Fetched context "Checkout" as yaml → .slices/checkout/slicedata.yaml
```

#### Stacks

| Stack key | Description |
|---|---|
| `node` | Node.js / TypeScript |
| `supabase` | Supabase |
| `axon` | Axon Framework (Java/Kotlin) |
| `cratis-csharp` | Cratis (.NET/C#) |
| `init --modeling (not a --stack)` | Skills + agent loop only — no backend scaffold |

#### What gets installed

```
your-project/
├── .build-kit/                    ← agent runner (.agent-modeling-kit/ for the modeling-kit stack)
│   ├── .eventmodelers/
│   │   └── config.json            ← credentials + execution settings (gitignored)
│   ├── ralph-claude.js            ← realtime agent + task loop
│   ├── ralph-ollama.js            ← same, via local Ollama
│   ├── ralph.sh                   ← bash-only loop (no realtime)
│   └── lib/                       ← stack-specific agent prompts + helpers
├── .claude/
│   └── skills/                    ← eventmodelers skills for Claude Code
├── src/ … (or the stack's own layout)
└── CLAUDE.md                      ← agent instructions
```

The four backend stacks also scaffold a real project skeleton into your project root — source layout, build files, migrations, etc. `modeling-kit` only installs skills + the agent loop, with no backend opinion.

### Power users

Everything below customizes the install itself or automates it — pushing/pulling status changes to the board, scripted/CI installs, multi-project config sharing, and MCP registration. Day-to-day modeling never needs this section.

#### Advanced commands

```
npx @eventmodelers/cli init --stack <name> -f   # re-prompt for credentials even if a config already exists, overwriting it
npx @eventmodelers/cli init --stack <name> --hooks   # install the slice commit-scope guard (.githooks/pre-commit) — off by default
npx @eventmodelers/cli init-hooks            # install/refresh the guard and its git config without a full re-scaffold
npx @eventmodelers/cli init-hooks --stack <name>   # override which stack's .githooks/ template to use
npx @eventmodelers/cli disable-hooks         # unset core.hooksPath, turning the guard off — leaves .githooks/ on disk
npx @eventmodelers/cli init-mcp              # register the MCP server in .claude/settings.json (+ optionally another harness)
npx @eventmodelers/cli init-agents           # expose installed skills to other AI agent hosts (Cursor, Windsurf, Gemini CLI, Copilot, Codex CLI, Kiro, ...) as thin stub commands
npx @eventmodelers/cli init-config           # credentials only, no scaffold — writes ./.eventmodelers/config.json
npx @eventmodelers/cli init-config --global  # same, but writes organizationId + token to ~/.eventmodelers/config.json
npx @eventmodelers/cli re-init                # refresh the installed kit dir (.build-kit or .agent-modeling-kit) + its skills
npx @eventmodelers/cli re-init --modeling     # refresh the modeling kit (.agent-modeling-kit) instead of a build kit
npx @eventmodelers/cli re-init --stack supabase   # override which stack to refresh from, instead of trusting install-manifest.json
npx @eventmodelers/cli re-init --hooks        # install/refresh the commit-scope guard too, same as init --hooks
npx @eventmodelers/cli re-init --global       # re-install skills into ~/.claude/skills/ instead of the project
npx @eventmodelers/cli re-init -f             # re-prompt for credentials even if a config already has everything required
npx @eventmodelers/cli listen                # start the code-export listener (code-export.mjs) from the installed kit dir
npx @eventmodelers/cli listen --port 4000    # same, on a different port
npx @eventmodelers/cli activate-context      # pick which fetched context is active (writes .slices/current_context.json)
npx @eventmodelers/cli set-slice-status      # pick a slice from the active context and change its status in .slices/
npx @eventmodelers/cli set-slice-status --remote  # same, and also push the change to the board via the nodes/events API
npx @eventmodelers/cli release-notes         # print the CLI's own release notes
npx @eventmodelers/cli uninstall             # remove the installed kit dir
```

`listen` is the same kind of dispatcher as `run`, but for `<kit-dir>/code-export.mjs` — the local server behind the **Manual Code Export** workflow below. It listens on port 3001 by default; pass `--port` to use a different one. `fetch` is its pull-based counterpart: instead of waiting for the board UI to push slice/screen data over a websocket, it pulls the same data on demand — same destination shape as `listen`, minus screen images.

`activate-context` picks which of the contexts already pulled into `.slices/` is active. It lists every context directory that has an `index.json` — i.e. something `fetch` or `listen` actually wrote — lets you choose one from an arrow-key menu (or a numbered prompt on piped/CI input), and writes its name into `.slices/current_context.json`. That file is sticky: the agent loop only ever works within the one context it names and never crosses into another on its own, even if that other context has planned work waiting.

`set-slice-status` lists every slice in the active context, lets you pick one, then pick a new status — `Created`, `Done`, `Assigned`, `InProgress`, `Review`, `Blocked`, `Planned`, `Informational` — the same set the board's own status picker offers — and updates `.slices/` to match. Pass `--remote` to also push the change to the board itself via the same `nodes/events` API call (a `node:changed` event with `changedAttributes: ['sliceStatus']`) the board UI and the `update_slice_status` MCP tool both use internally. With `--remote`, missing credentials trigger the same prompt `fetch` uses, and a rejection because the slice is already at that status is reported as informational, not an error.

`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of. Pass `--stack <name>` to override the stack instead of relying on the manifest — useful if the manifest is missing/stale, or you want to point a `.build-kit` install at a different built-in stack's templates; it's mutually exclusive with `--modeling`. Credentials are left alone unless you pass `--force` — same rule `init` already follows when everything required is already configured. `--global` defaults to however skills were originally installed; pass it explicitly to move them. If the kit dir predates `install-manifest.json` tracking, or was installed via `init --git <url>` (a community/custom stack, not one of the built-in `STACKS` keys), and you don't pass `--stack` yourself, `re-init` can't tell what to re-copy and tells you to re-run the original `init` command by hand instead.

Every command except `init`/`install`, `init-config`, `stacks`, `status`, `config`, `uninstall`, `fetch`, `activate-context`, `set-slice-status`, and `release-notes` first checks that a kit dir is actually installed in the current directory and exits with a pointer to `init`/`init --modeling` if it isn't — those ten are exempt because they either create the install, only touch credentials, or are read-only/cleanup commands meant to work whether or not anything's installed yet.

`release-notes` prints `RELEASE_NOTES.md` as bundled with the installed CLI version — a plain read of a file shipped inside the package, no project state or credentials involved at all.

`--global` only changes where skills are copied — everything else (the kit dir, project scaffold, credentials, MCP registration) still targets the current directory as usual. `init` no longer registers the MCP server automatically — run `init-mcp` as a separate step whenever you're ready to connect a harness.

`init` and `init-config` also accept direct credential flags — `--token`, `--board-id`, `--organization-id`, `--base-url` — which win over both the config file and env vars, e.g.:

```
npx @eventmodelers/cli init --stack node \
  --organization-id ... --board-id ... --token ... --base-url https://api.eventmodelers.ai
```

By default, `init` skips the credential prompt entirely once a config already has everything required — pass `-f`/`--force` to re-prompt (and overwrite) anyway, e.g. to switch a project to a different board or token:

```
npx @eventmodelers/cli init --stack node -f
```

#### Commit-scope guard

`--hooks` installs the slice commit-scope guard: `.githooks/pre-commit` (copied into the project root, made executable) plus `git config core.hooksPath .githooks` — both done directly by `init`, so nothing else needs to be run by hand to activate it. It's opt-in and off by default; a plain `init` never touches git's hook wiring. Currently only the `node` and `supabase` stacks ship a `.githooks/` template — passing `--hooks` against any other stack prints a note and installs nothing.

`init-hooks` does the same install/wire-up on its own, outside of `init`/`re-init` — for turning the guard on after the fact, or picking up a newer `.githooks/pre-commit` template shipped by a later CLI version, without re-running a full install. It auto-detects which stack's template to use from `install-manifest.json` (the same file `re-init` reads); pass `--stack <name>` to override that:

```
npx @eventmodelers/cli init-hooks
```

Once active, the hook only wakes up for a commit that actually touches slice code — `src/slices/<context>/<slice>/` for either stack, or, for `supabase` specifically, a webhook's self-contained `supabase/functions/<fn>/index.ts`. An ordinary commit that never touches those paths — a README edit, a config tweak — passes straight through untouched. For a commit that does qualify, it loads every check under `.build-kit/lib/checks/` and rejects the commit if any one of them finds a problem:

- **Blocked paths.** `package.json` and every lockfile are off-limits — a slice commit can never add or change a dependency — and so is `server.ts`, since routes and processors are auto-discovered by a glob at startup rather than wired up by hand there.
- **Slice scope.** Everything else staged in the commit has to live inside the slice's own folder, or be one of a short list of documented shared-infra files a slice is allowed to register itself into without rewriting: the per-context event union (`<Context>Events.ts`), `loadPostgresEventstore.ts` (where a projection gets added to the pipeline), and, on `supabase` only, `supabase/config.toml` (where a webhook function is registered).
- **Append-only migrations.** A migration file may be added, but an existing one can never be edited or deleted in the same commit — a schema fix belongs in a new migration, not a rewrite of an old one that may already be applied elsewhere.
- **Test file present.** Any commit that changes a command handler, a projection, or a processor has to bring a sibling `*.test.ts` along with it — a slice with implementation but no test coverage at all is rejected outright.
- **No invented fields.** This one is a heuristic, not a full type-aware check: it reads the field names declared inside a slice's `Command<>`/`Event<>` type literals and read-model types, and flags any name that doesn't appear anywhere in that slice's own `slice.json`. When it can't confidently locate or parse the `slice.json` for a given slice, it skips that slice rather than risk a false rejection.
- **Spec coverage.** Also a heuristic: it counts `specifications[]` entries in `slice.json` and compares that to the number of `it(...)` blocks in the matching test file, rejecting the commit if there are fewer tests than declared specifications. It doesn't verify each specification is actually the one being tested — just that nobody quietly shipped fewer test cases than the slice calls for.
- **TypeScript build.** Finally, `npx tsc --noEmit` has to still pass against the project's own `typescript` devDependency — no new package added for this, just a type-check the slice work is already expected to pass before it's considered done. This one is skipped once an earlier check has already failed, since there's no point type-checking a commit that's being rejected anyway.

Run `npm run run:checks` any time to see what the guard would say about the currently staged files without actually committing — this is the manual/dry-run entry point into the exact same checks the hook runs (`node .build-kit/lib/check-commit-scope.cjs`). Since the checks live one-per-file under `.build-kit/lib/checks/`, adding a new one is just dropping in another file that follows the interface documented in that folder's own `README.md` — nothing else needs wiring up.

There's no per-check skip — it's all seven checks or none. To let one specific commit through anyway (a false positive from one of the two heuristic checks, say), use git's own `--no-verify`, which skips the whole hook for just that commit:

```
git commit --no-verify -m "..."
```

To turn the guard off for the project entirely instead of skipping it commit-by-commit, run `disable-hooks` — it unsets the hook path `init --hooks`/`init-hooks` configured (`.githooks/` itself is left on disk untouched). Run `init-hooks` again any time afterward to turn it back on:

```
npx @eventmodelers/cli disable-hooks
```

##### Examples: re-init

**re-init** — `npx @eventmodelers/cli re-init`
Refreshes the kit dir from whichever stack `install-manifest.json` recorded, leaving the project root and credentials untouched:
```
🚀 Eventmodelers CLI

Using: supabase (Supabase)

📦 Installing skills...
  ✓ Installed 1 item into .claude
  ✓ Installed 4 items into .claude/skills
📦 Installing agent kit into .build-kit/...
  ✓ Installed 8 items into .build-kit
  ✓ Installed 2 items into .build-kit
📦 Installing kit dependencies...
  ✓ kit dependencies installed
```

**re-init --stack** — `npx @eventmodelers/cli re-init --stack node`
Overrides the stack instead of trusting the manifest — for a missing/stale `install-manifest.json`, or to switch a `.build-kit` install to a different built-in stack's templates:
```
🚀 Eventmodelers CLI

Using: node (Node.js / TypeScript)

📦 Installing skills...
  ✓ Installed 1 item into .claude
  ✓ Installed 4 items into .claude/skills
📦 Installing agent kit into .build-kit/...
  ✓ Installed 8 items into .build-kit
```

##### Examples: activate-context

**activate-context** — `npx @eventmodelers/cli activate-context`
Lists every context already pulled into `.slices/` and lets you pick which one is active:
```
Which context should be active? (currently: Checkout)
  ● Checkout
  ○ Ordering

✅ Active context set to "Ordering" → .slices/current_context.json
```

##### Examples: set-slice-status

**set-slice-status** — `npx @eventmodelers/cli set-slice-status`
Picks a slice from the active context, then a new status, and updates `.slices/` locally:
```
Which slice in "Ordering" should change status?
  ● PlaceOrder   [Created]
  ○ CancelOrder  [Created]

New status for "PlaceOrder"? (currently: Created)
  ○ 🌱 Created (default)
  ○ ✅ Done
  ○ 👤 Assigned
  ● 🔄 InProgress
  ○ 🔍 Review
  ○ 🚫 Blocked
  ○ 📅 Planned
  ○ ℹ️ Informational

✅ "PlaceOrder": Created → InProgress (.slices/ordering/index.json)
```

**set-slice-status --remote** — `npx @eventmodelers/cli set-slice-status --remote`
Same picker, but also pushes the change to the board itself via the `nodes/events` API:
```
✅ "PlaceOrder": Created → InProgress (.slices/ordering/index.json)
✅ Pushed status change to the board (node <uuid>).
```

##### Examples: release-notes

**release-notes** — `npx @eventmodelers/cli release-notes`
Prints the release notes bundled with the installed CLI version:
```
## v0.0.38

### Features
- ...

### Fixes
- ...
```

`--config <path>` and `--print` are global flags accepted by every command — see **Environment variables** below.

#### Config resolution order

`init`, `status`, and `config` all build the effective config the same way, by layering these sources — each one overriding the last:

1. **Shared parent config.json (defaults)** — Walking up from the project root, the nearest `.eventmodelers/config.json` in a parent directory — e.g. `~/.eventmodelers/config.json`, if your project lives under your home directory — provides base values.
2. **Kit-dir config.json (per-project override)** — `<kit-dir>/.eventmodelers/config.json` — written by the installer, or edited by hand — overrides any field it also sets.
3. **~/.eventmodelers/config.json (last resort)** — If step 1's walk reaches the filesystem root without finding anything — which happens whenever the project doesn't live under your home directory at all, e.g. `/tmp/foo` — `~/.eventmodelers/config.json` is checked once more directly. Set it up with `npx @eventmodelers/cli init-config --global`.
4. **EVENTMODELERS_* env vars / direct flags (always win)** — Override the merged result of steps 1–3 — see the table below. A fully env- or flag-driven install never prompts for credentials or Claude execution settings.

`--config <path>` replaces steps 1–2 entirely with one explicit file (env vars still apply on top) — see **Environment variables** below.

Inspect the fully resolved result (token masked) at any time — it lists every file that contributed, in override order:

```
npx @eventmodelers/cli config
```

#### Example: shared defaults, per-project board

A common setup: one shared config above all your checkouts holding the values that don't change per-project, with each project overriding only its `boardId`. Set the shared file up once with:

```
npx @eventmodelers/cli init-config --global   # writes organizationId + token to ~/.eventmodelers/config.json
```

```
~/.eventmodelers/config.json                                   ← shared: organizationId, token
~/projects/checkout-app/.build-kit/.eventmodelers/config.json  ← { "boardId": "<checkout-app-board>" }
~/projects/billing-app/.build-kit/.eventmodelers/config.json   ← { "boardId": "<billing-app-board>" }
```

Running any command from inside `~/projects/checkout-app` resolves `organizationId`/`token` from the shared home config, `boardId` from the project's own file, and defaults `baseUrl` to `https://api.eventmodelers.ai` since nobody set it explicitly. Switch to `~/projects/billing-app` and only the board changes — nothing else to re-enter:

```
$ cd ~/projects/checkout-app && npx @eventmodelers/cli config
Config sources (later overrides earlier):
  - /Users/you/.eventmodelers/config.json
  - /Users/you/projects/checkout-app/.build-kit/.eventmodelers/config.json

{
  "organizationId": "...",
  "token": "toke...here",
  "baseUrl": "https://api.eventmodelers.ai",
  "boardId": "<checkout-app-board>"
}
```

#### Environment variables

Every config field can be set via an env var instead of the interactive prompts — useful for scripted or CI installs:

| Env var | Config field |
|---|---|
| `EVENTMODELERS_ORGANIZATION_ID` | `organizationId` |
| `EVENTMODELERS_BOARD_ID` | `boardId` |
| `EVENTMODELERS_TOKEN` | `token` |
| `EVENTMODELERS_BASE_URL` | `baseUrl` |
| `EVENTMODELERS_ANTHROPIC_BASE_URL` | `anthropicBaseUrl` |
| `EVENTMODELERS_MODEL` | `model` |

```
EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \
  npx @eventmodelers/cli init --stack node

npx @eventmodelers/cli --config ../shared/config.json status
```

#### Claude execution & MCP

During install you can optionally point the agent at a local LLM server (vLLM, Ollama) instead of the default Claude Code endpoint, and/or pin a specific model. Both are stored alongside credentials:

```
// <kit-dir>/.eventmodelers/config.json
{
  "organizationId": "...",
  "boardId": "...",
  "token": "...",
  "baseUrl": "https://api.eventmodelers.ai",
  "anthropicBaseUrl": "http://localhost:8000",
  "model": "claude-sonnet-5"
}
```

MCP registration is a separate step from installation — run `init-mcp` whenever you're ready to connect a harness. It registers the Eventmodelers MCP server in `.claude/settings.json` and prompts to connect it globally too:

```
npx @eventmodelers/cli init-mcp
claude mcp add eventmodelers --transport http https://api.eventmodelers.ai/mcp
```

Pass `--print` to skip that prompt and just print the command instead of running it — combined with the env vars or direct flags above, it makes both `init` and `init-mcp` fully non-interactive (handy for scripted setups or CI):

```
EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \
  npx @eventmodelers/cli --print init --stack node
```

## Agentic Modeling

### Agentic Event Modeling

*(Embedded video: "Nebulit AI Overview", https://www.youtube.com/embed/y2TFob2OZEg)*

*Leila's team had a requirements document and three hours blocked for a modeling session. She opened Claude Code, typed **/eventmodeling-orchestrating-event-modeling**, and pasted the requirements. Claude asked four questions to confirm scope, then started working. Events appeared on the board in real time. By the end of the session the board had a full timeline, role-annotated wireframes, commands, read models, Given/When/Then specs, and a PASS validation verdict — all without switching tools.*

*Priya didn't want her team's kickoff workshop to start from a blank board. The night before, she ran the same requirements doc through Claude Code unattended — full timeline, wireframes, commands, read models, and specs generated overnight. The next morning she opened the board with the whole team, walked through what the agent had built slice by slice, and spent the workshop fine-tuning names, catching a missed refund edge case, and reordering two events — instead of starting from zero. What used to take a full day of whiteboarding took ninety minutes of confirmation.*

The **Agent Modeling Kit** ships a set of skills that turn Claude Code into a full event modeling facilitator. You can run the entire 9-step workflow end-to-end with a single command, or invoke individual steps in isolation as your session demands. All skills write directly to your Nebulit board — elements appear live as Claude works.

**Prerequisite:** The agentic modeling skills require the **Eventmodelers CLI** to be installed in your project. See the **Connect Agent** section for installation instructions (`npx @eventmodelers/cli init --modeling`). All skills call `/connect` automatically to resolve board credentials.

**Prefer talking to typing?** See the dedicated **Model As You Speak** section for driving these same skills live by voice.

#### Skills

| Command | Title | Description |
|---|---|---|
| `/connect` | Connect to a board | Set up or switch your board connection. All other skills call this automatically if credentials are missing. |
| `/timeline` | Live event storming | Describe a business process in plain text. Claude extracts domain events and places them on the board in real time as the conversation unfolds — no waiting until the end. |
| `/wdyt` | What do you think? | Business analyst review mode. Claude reads your entire model, thinks through failure paths, edge cases, permissions, and timing gaps, then posts specific questions as comments on relevant nodes. |
| `/storyboard` | Generate a screen flow | Describe a user flow (login, checkout, onboarding …) and how many screens you need. Claude designs and renders wireframes into a new chapter on your board. |
| `/storyboard-screen` | Design a single screen | Render or redesign one wireframe onto an existing SCREEN node. |
| `/html-screen` | Design a single HTML screen | Render or redesign one or more real, styled HTML/CSS pages onto an HTML_SCREEN node. Explicit-use only — ordinary "design a screen" requests still default to /storyboard-screen. |
| `/discover-storyboard` | Discover storyboard from a live app | Navigate an existing web app with browser automation (Puppeteer, Playwright, or Chrome DevTools MCP), capture real screenshots at each step, and upload them as SCREEN nodes onto the board — grouped by flow into timeline chapters, ready for event modeling. |
| `/place-element` | Place an element | Drop a single COMMAND, EVENT, or READMODEL onto a specific position on a timeline without starting a full session. |
| `/analyze-existing-model` | Analyze existing model | Read-only board analysis — summarizes contexts, slices, element counts, status breakdown, spec coverage, and structural gaps. Useful as a starting point before a modeling session or when handing off to a team. |
| `/attributes` | Propagate an attribute | Add a new field or rename an existing attribute across a chain of elements (event → command → read model) from a source cell to a target cell, following inbound dependencies automatically. |
| `/examples` | Add example data | Find an element by name or cell position and populate its fields with realistic example values — using linked elements for context and consistency. |
| `/update-slice-status` | Update slice status | Change a slice's status (e.g. Planned, InProgress, Done) by updating the SLICE_BORDER node — the slice recolors on the board immediately. |
| `/handle-comment` | Manage comments | Place, resolve, or delete a comment on any board node. Pass the action as the first argument: place (default), resolve, or delete. |

#### Start here: the Orchestrator

The **Orchestrator** skill is the single entry point for a complete end-to-end modeling session. It coordinates all 9 steps in sequence, carries outputs between steps, and enforces the gate condition before moving on.

**`/eventmodeling-orchestrating-event-modeling`** (ENTRY POINT)

Invoke this skill and describe your domain — or paste in a requirements document. Claude runs a short interview to confirm scope and goal, then executes Steps 1–9 in order. If you already have outputs from earlier steps, tell Claude which steps are done; it picks up from where you are.

- **From scratch** — Describe domain → Claude interviews → runs all 9 steps.
- **Mid-workflow** — Tell Claude which steps are complete → resumes from next incomplete step.

#### The 9-step workflow

Each step below can also be invoked independently when you need to run a single phase in isolation.

**1. Brainstorm Events** — `/eventmodeling-brainstorming-events`
*Extract every state-changing event in the domain.*
Facilitates a collaborative brainstorming session: free-form event collection, gentle filtering to keep only true state-changing events, and role catalog creation. Each event is named in past tense (e.g. OrderPlaced, PaymentConfirmed). The role catalog — human roles and system actors — feeds every later step.
Why this step matters: Starting from events instead of database tables forces the team to agree on what actually happens in the business before designing anything. A shared event list is the most valuable artifact to walk out of a requirements session with.
Story: Ana pasted the product team's requirements doc into Claude and ran /eventmodeling-brainstorming-events. Claude asked who the main actors were, then started listing events. Within minutes the board showed 24 events — OrderPlaced, InventoryReserved, PaymentFailed — and a Role Catalog with Customer, Seller, and Payment Gateway. Two she hadn't thought of herself.
Input: Domain description, requirements doc, or verbal explanation. Output: Event list + Role Catalog (human roles and system processors). Gate: Role Catalog exists and events cover all known business processes.

**2. Plot Events** — `/eventmodeling-plotting-events`
*Arrange events chronologically on the timeline.*
Takes the raw event list and sequences it into a left-to-right causal narrative on the board. Events are grouped by business process, duplicates are merged, and causal dependencies are made explicit. The result should read like a story.
Why this step matters: Sequencing makes causal relationships visible. When events are in order the team immediately spots missing transitions ("what happens between OrderPlaced and OrderShipped if payment fails?") that are invisible in a flat backlog.
Story: After brainstorming, the board had events scattered with no order. Ana ran /eventmodeling-plotting-events and watched Claude rearrange them into a left-to-right flow: AccountCreated → CartItemAdded → OrderPlaced → PaymentConfirmed → OrderShipped. When Claude placed RefundIssued she realised the team had never discussed the cancellation path — a gap that would have shown up as a production bug three months later.
Input: Event list from Step 1. Output: Chronological timeline showing causal dependencies between events. Gate: Timeline reads as a coherent narrative before proceeding.

**3. Storyboard** — `/eventmodeling-storyboarding-events`
*Sketch UI mockups for every human role.*
For each human role in the catalog the skill creates a swimlane and designs wireframe screens showing what the user sees and what data they provide. Screens are rendered directly onto SCREEN nodes on the board using AI-generated sketchnote-style mockups.
Why this step matters: Storyboards make the product concrete for non-engineers. Seeing actual wireframes next to events on the same canvas helps product, design, and engineering converge on data requirements before a single line of code is written.
Story: Ana ran /eventmodeling-storyboarding-events. For the Customer swimlane Claude placed wireframes for the product listing, cart, checkout, and order-tracking screens — rendered as sketchnote mockups directly on the board. The Seller swimlane got an inventory dashboard and an order-confirmation screen. The designer on the team looked at the board and immediately started adding notes on the checkout wireframe.
Input: Event timeline + Role Catalog. Output: UI mockups with one swimlane per human role. Gate: Every human role has at least one screen on the board.

**4. Identify Inputs** — `/eventmodeling-identifying-inputs`
*Map user actions to Commands.*
Inspects the storyboards and extracts every user action (button click, form submit, API call) as a named Command. Each command is attributed to a specific role or system processor from the catalog. Commands are placed in the interaction row on the board.
Why this step matters: Commands name the user's intent before the system acts. Defining them explicitly prevents the common mistake of wiring UI actions directly to database writes — and makes it obvious when a user action has no corresponding business event.
Story: Looking at the checkout wireframe, Claude identified three buttons: "Place Order", "Apply Coupon", and "Save Address". It created PlaceOrder, ApplyCoupon, and SaveDeliveryAddress commands — each linked to the Customer role — and placed them in the interaction row above their corresponding events. The team noticed "Apply Coupon" had no matching event. They added CouponApplied on the spot.
Input: Storyboards + Role Catalog. Output: Command definitions, each attributed to a specific role/actor. Gate: Every UI action in the storyboards maps to a named command.

**5. Identify Outputs** — `/eventmodeling-identifying-outputs`
*Design Read Models from events.*
For each screen data requirement from the storyboards, defines a Read Model — a projection of events optimised for that specific query. Read Models are placed immediately after their source events on the timeline, not stacked at the end.
Why this step matters: Read Models separate what data users need from how it is stored. Defining them next to their source events prevents the "we'll figure out the query later" trap that leads to slow, coupled database reads in production.
Story: The order-tracking screen needed order status, estimated delivery, and item list. Claude defined an OrderTrackingView read model that projected OrderPlaced, OrderShipped, and DeliveryConfirmed. It placed it immediately after OrderShipped on the timeline — not at the far end — so the visual connection to its source events was obvious. The developer assigned to that screen had a clear contract before opening her IDE.
Input: Event list + Commands from Step 4. Output: Read model definitions satisfying all UI and processor query needs. Gate: Every screen data need from the storyboards is covered by a read model.

**6. Apply Conway's Law** — `/eventmodeling-applying-conways-law`
*Map events to team/system boundaries.*
Groups events and commands into autonomous system parts whose boundaries align with team structure. Each bounded context can be independently owned and deployed. Skip this step if team structure is not relevant to the current project.
Why this step matters: System architecture that mirrors team structure reduces coordination overhead and inter-team merge conflicts. Running this step during modeling — not during architecture review after implementation begins — makes the boundaries visible while they are still cheap to change.
Story: The team had two squads: Checkout and Fulfillment. Claude ran /eventmodeling-applying-conways-law and drew a boundary between PaymentConfirmed (Checkout owns it) and OrderShipped (Fulfillment owns it). The boundary highlighted that both squads were reading from the same Order table. That conversation happened in the modeling session — not during an incident six months later.
Input: Full event model (events, commands, read models). Output: System swimlanes mapping elements to team/bounded-context boundaries. Gate: Each boundary can be independently owned — or step explicitly skipped.

**7. Elaborate Scenarios** — `/eventmodeling-elaborating-scenarios`
*Write Given/When/Then specs for commands and views.*
For each command and read model, generates behavioral specifications in Given/When/Then format. Covers happy paths, validation failures, and edge cases. Specs are posted directly to spec cells on the board.
Why this step matters: Specs written during modeling are based on the same shared understanding that produced the events and commands — making them far more accurate than specs written weeks later from memory. They become the acceptance criteria developers and QA test against.
Story: For the PlaceOrder command Claude generated three scenarios: the happy path, a payment-declined failure, and an out-of-stock edge case. Each appeared as a spec card pinned to its command on the board. The QA engineer opened the board and started writing acceptance criteria directly from the specs. No separate test-planning meeting needed.
Input: Commands and read models. Output: Given/When/Then specifications on every command and read model node. Gate: At least one scenario per command before proceeding.

**8. Check Completeness** — `/eventmodeling-checking-completeness`
*Verify every field has an origin and a destination.*
Builds a field traceability matrix across the entire model. Confirms that every data field produced by an event is consumed somewhere (a read model, a screen, or another event), and that every field required by a command has an origin. Gaps are listed explicitly.
Why this step matters: Data gaps that survive to implementation turn into runtime nulls, missing migrations, and confused developers who have to reverse-engineer the model from the code. Finding them in a field-traceability matrix takes minutes; finding them in production takes days.
Story: The completeness check flagged that customerId appeared in PlaceOrder but no event captured how a customer was created — the AccountCreated event was missing customerId entirely. It also found that shippingAddress was required by the fulfillment event but never collected in any command. Two gaps, both caught before implementation, both cheap to fix at this stage.
Input: Full model — events, commands, read models, scenarios, Role Catalog. Output: Field traceability matrix + list of any gaps. Gate: All gaps resolved or explicitly accepted before proceeding.

**9. Validate** — `/eventmodeling-validating-event-models`
*Final architectural validation — PASS / FAIL verdict.*
Reviews the completed model against event sourcing principles: immutable events, deterministic state projections, minimal per-command state (no DDD aggregates), and correct slice layout. Returns a PASS / PASS WITH WARNINGS / FAIL verdict. A FAIL re-enters the fix cycle.
Why this step matters: A model that looks complete can still have subtle violations — a shared aggregate, a mutable event, a state projection that couples two commands. Validating before implementation prevents architectural problems from becoming load-bearing code that is painful to refactor.
Story: Validation returned PASS WITH WARNINGS: one read model was derived from three separate streams without a documented merge strategy. Claude described the risk and suggested a compensating event. The team accepted the warning and documented the decision. The implementation sprint started from a model everyone had confidence in.
Input: Complete event model. Output: Validation report with verdict. Gate: PASS verdict before declaring the model ready for implementation.

#### Optional follow-on skills

These skills extend the workflow for specific needs. They are not part of the 9-step main path but can be invoked at any point when the situation calls for them.

- **Design Event Models** — `/eventmodeling-designing-event-models` — Deep-dives into stream identity, per-command state shapes, and event causality. Use when those decisions are non-obvious or need explicit documentation. When: During or after Step 1, whenever stream design decisions arise.
- **Optimize Stream Design** — `/eventmodeling-optimizing-stream-design` — Validates stream growth estimates and snapshotting decisions. Ensures streams stay appropriately sized for performance. When: After model is complete — before committing to an implementation plan.
- **Translate External Events** — `/eventmodeling-translating-external-events` — Integrates webhooks, IoT signals, or third-party API callbacks into the domain model as first-class events. When: When external systems feed into the domain.
- **Integrate Legacy Systems** — `/eventmodeling-integrating-legacy-systems` — Maps existing system behavior into event modeling structures — reverse-engineers legacy flows into events, commands, and read models. When: When modernizing an existing system rather than designing from scratch.
- **Slice Event Models** — `/eventmodeling-slicing-event-models` — Breaks the complete model into independently deployable feature slices, identifies dependencies, and plans parallel team implementation. When: After Step 9 PASS — to prepare for team implementation.
- **Production Readiness Checklist** — `/eventmodeling-validating-event-models-checklist` — Runs 16 architectural checks across 7 phases — a rigorous production gate independent of Step 9 validation. When: When the model is destined for a production system.

#### Tips for productive sessions

- **Paste your requirements** — The richer the input — user stories, PRD, meeting notes — the more accurate Step 1 will be. Plain prose works fine.
- **Skip completed steps** — If events are already on the board, tell the orchestrator. It reads existing nodes first and starts from the first missing step.
- **Watch the board live** — Elements appear in real time as Claude works. Keep the board open in another window to give instant feedback during the session.
- **Intervene at any gate** — Each step has a gate. If the output looks wrong, correct it in Claude Code before saying "continue" — the orchestrator will not advance until you confirm.
- **Run steps standalone** — Any skill can be invoked on its own. Use /eventmodeling-brainstorming-events for a focused event discovery session without committing to the full workflow.
- **Validate before implementing** — Always run Step 9 (validate) before handing off to the Implementation Kit. A PASS verdict is the contract between the model and the code.

## Agentic Building

### Agentic Building

*(Step-by-step guide (PDF): "Model to Code in 30 Seconds" — download the walkthrough at /docs/model-to-code-in-30sec.pdf)*

*You finished modeling a slice on the board. You flip its status to **Planned**, lean back, and roughly thirty seconds later the command handler, the projection, and the tests exist in your repository — written in your stack, committed, green. You never opened your editor.*

**Agentic Modeling** turns a conversation into a precise, machine-readable Event Model. **Agentic Building** is the other half of that promise: it turns that model into running code. An autonomous agent loop watches your board, picks up slices the moment you mark them ready, reads the slice definition (events, commands, read models, fields, specifications), and implements them against a real, idiomatic tech stack — then runs the build, runs the tests, and commits.

The model *is* the specification. Because every slice carries its full structural intent — what data flows in, what state changes, what is read back — the agent does not have to guess. It maps the model onto patterns the chosen stack already knows well, so the generated code looks like code a senior engineer on that stack would have written, not like a generator's output.

**Prerequisite:** Agentic building requires the **Eventmodelers CLI** installed with the backend stack that matches your project (`npx @eventmodelers/cli init --stack <name>` — see **CLI Configuration** for the full list of stacks). All skills call `/connect` automatically to resolve board credentials.

**The Vision:** From model to generated code in 30 seconds. Mark a slice ready on the board and have working, tested, committed code in your repository before you finish your next sip of coffee — in whatever stack your team already runs.

#### One model, many stacks

A single Event Model is stack-agnostic, so the same board can drive a Java backend for one team and a Node.js backend for another. Each **build kit** is a self-contained agent setup tuned for one well-known technology stack — its skills, prompts, and quality checks know how that stack does command handling, event sourcing, projections, and testing.

**All build kits are open source and free to use.** They live in one public repository — Eventmodelers-Build-Kits (https://github.com/Nebulit-GmbH/Eventmodelers-Build-Kits) — so you can read every line, run them with no license, fork them for your own stack, and contribute back.

#### Current & planned build kits

| Tech stack | Status | Source |
|---|---|---|
| Axon Framework + Java | In Progress | View on GitHub — install: `npx @eventmodelers/cli init --stack axon` |
| nodejs + emmet | Ready | View on GitHub — install: `npx @eventmodelers/cli init --stack node` |
| nodejs + emmet + supabase | Ready | View on GitHub — install: `npx @eventmodelers/cli init --stack supabase` |
| Marten + .NET | Ready | Community Kit (https://github.com/Powerworks/K9DatingApp/) — install: `npx @eventmodelers/cli init --stack marten --git https://github.com/Powerworks/K9DatingApp/` |
| Cratis.io | Ready | Community Kit — install: `npx @eventmodelers/cli init --stack cratis-csharp` |
| python + pyeventsourcing | Ready | Community Kit (https://github.com/Midnighter/build-kit-pyeventsourcing) — install: `npx @eventmodelers/cli init --stack pyeventsourcing --git https://github.com/Midnighter/build-kit-pyeventsourcing` |
| UmaDB + Java | Adopted | No dedicated build kit yet — teams adopt this stack manually using patterns from the shared repo. |
| EventSourcingDB + Java | Planned | Planned — not yet available. Follow the repository for updates. |
| Kurrent + Java | Planned | Planned — not yet available. Follow the repository for updates. |
| Kurrent + DotNet | Planned | Planned — not yet available. Follow the repository for updates. |
| PHP | Planned | Planned — not yet available. Follow the repository for updates. |
| Golang | Planned | Planned — not yet available. Follow the repository for updates. |

The **nodejs + emmet** and **nodejs + emmet + supabase** kits are ready to use today — see the dedicated **Build With nodejs + emmet** and **Build with nodejs + emmet + supabase** sections for installation and the full agent loop. The **Axon** kit is in active development, and the remaining stacks are on the roadmap. Want a stack that isn't listed? See **Build Your Own Build Kit** — every kit shares the same structure, so `init --build-kit` gives you a TODO-marked scaffold to fill in against your stack, or you can open an issue on the repository.

#### Manual Code Export

You don't need the full autonomous loop just to get your model out of the board. Every build kit ships a small local server, `code-export.mjs`, that turns a one-click export from the board into a structured `.slices/` folder on disk — handy for feeding the model into your own tooling, an editor's AI assistant, or a one-off manual build.

Start it from your project root with the CLI's `listen` command — it finds the installed kit dir (whatever it's named for your stack) and runs `code-export.mjs` from it. It listens on port 3001 by default — pass `--port` to use a different one:

```
npx @eventmodelers/cli listen
npx @eventmodelers/cli listen --port 4000   # use a different port
```

On the board, open the menu and select **Code**. Pick a Model Context from the dropdown and click **Create config** — the board posts the current slice data for that context to `http://localhost:3001/api/generate`, and the server writes it straight to `.slices/`.

The resulting data structure:

```
.slices/
  current_context.json          # { name } — last context exported
  <context>/
    config.json                 # raw export payload for this context
    context.json                # { name, contextPackage }
    index.json                  # { slices: [{ id, slice, index, context, folder, status, group? }] }
    <slice-folder>/
      slice.json                # full slice definition — source of truth
      screen-<id>.png           # attached screen mockups, if any
```

Each slice gets its own folder, named by slugifying the slice title (lowercased, spaces stripped, any leading `slice:` tag removed). `slice.json` holds the complete slice — its events, commands, read models, fields, and specifications — exactly as modeled on the board.

| File | Purpose |
|---|---|
| `.slices/current_context.json` | Name of the last context exported from the board |
| `.slices/<ctx>/config.json` | Raw export payload posted from the Code panel |
| `.slices/<ctx>/context.json` | Context name and configured code-gen package |
| `.slices/<ctx>/index.json` | Slice metadata and status for every slice in the context |
| `.slices/<ctx>/<folder>/slice.json` | Full slice definition — source of truth |
| `.slices/<ctx>/<folder>/screen-<id>.png` | Screen mockups attached to the slice |

The server also exposes read endpoints for external tooling — `GET /api/slices` (all slices, optionally with images) and `GET /api/slice-info` (titles, status, and specifications for the current context) — plus `POST /api/git`, which stages and commits the `.slices/` folder into your project's Git repository.

## Build With nodejs + emmet

### Build With nodejs + emmet

*This build kit is being developed openly with community contributors (see the "Currently building together with the Event Modeling Community" banner). Expect rapid iteration, new skills, and evolving patterns as we shape it together.*

*Sarah's team had a backlog of 14 slices sitting on their Eventmodelers board. She ran the installer, started the realtime agent in one terminal and the ralph loop in another, then went back to the board. She changed the first slice to **Planned**. Thirty seconds later the slice turned InProgress on the board by itself. Four minutes later it was Done — tests green, committed, merged. She changed the second slice to Planned and walked away to grab coffee.*

Installed via `npx @eventmodelers/cli init --stack node`, this is an autonomous coding agent loop for Node.js projects. It watches your board for slice status changes, loads the slice definition, implements the code using the matching skill, runs quality checks, commits, and marks the slice Done — all without manual intervention.

**Architecture diagram:**
```
Board (Eventmodelers)
  │  slice status → "Planned"
  ▼
Realtime Agent  ──────────────────►  .build-kit/tasks.json
  │  listens on Supabase channel         │
  │  writes task on slice:changed        │
  ▼                                      ▼
ralph.sh loop ◄────────────────── Phase 1: load slice
  │  checks tasks.json every 3s          reads task → runs /connect + /load-slice
  │                                      fetches slice definition to .build-kit/.slices/
  │                                      removes task from tasks.json
  │
  ▼
Phase 2: build slice
  checks .build-kit/.slices/**/index.json for status "Planned"
  →  status InProgress on board
  →  /build-state-change | /build-state-view | /build-automation
  →  npm run build + test  →  commit + merge
  →  status Done on board  →  wait for next
```

#### Step 1 — Install

Run the installer in your project directory. It copies all required files, installs the realtime agent dependencies, and writes your credentials to `.eventmodelers/config.json` (automatically gitignored).

```
npx @eventmodelers/cli init --stack node
```

The installer prompts for three values. Navigate to Account → Team-Boards and click the **Connection Info** copy icon next to your board — it copies all values to your clipboard at once.

*(Screenshot: Account page showing the Connection Info copy button)*

| Field | Where to find it |
|---|---|
| API token | Workspace Settings → API Tokens |
| Organization ID | URL bar: .../org/<UUID>/... |
| Base URL | Default: https://api.eventmodelers.ai |

**Board connection is optional.** The agent can run entirely offline using local slice definitions already in `.build-kit/.slices/`. When no `.eventmodelers/config.json` is present, platform sync (realtime agent, status updates, slice loading from the board) is disabled automatically — code generation from local slice files still works.

Everything is installed inside a `.build-kit/` folder in your project root (gitignored automatically):

| Path | Description |
|---|---|
| `.build-kit/.eventmodelers/config.json` | Your credentials |
| `.build-kit/.claude/skills/connect` | Resolves board credentials for all other skills |
| `.build-kit/.claude/skills/load-slice` | Fetches slice definitions and writes to .slices/ |
| `.build-kit/.claude/skills/update-slice-status` | Changes a slice status on the board |
| `.build-kit/.claude/skills/build-state-change` | Implements command handler slices |
| `.build-kit/.claude/skills/build-state-view` | Implements projection / read model slices |
| `.build-kit/.claude/skills/build-automation` | Implements reactor / automation slices |
| `.build-kit/.claude/skills/learn-eventmodelers-api` | Full API reference for the agent |
| `.build-kit/realtime-agent/` | Node.js listener for board events (optional) |
| `.build-kit/ralph.sh` | The main two-phase agent loop |
| `.build-kit/prompt.md` | Phase 1 agent instructions (load slice from board) |
| `.build-kit/backend-prompt.md` | Phase 2 agent instructions (build and commit slice) |
| `.build-kit/AGENT.md` | Accumulated learnings shared across loop iterations |

#### Step 2 — Start the ralph loop

Open a terminal, enter the kit folder, and start the loop. It polls every 3 seconds when idle and runs forever unless you pass an iteration limit.

```
cd .build-kit && ./ralph.sh
```

By default ralph targets `../` (your project root). Pass a path to override:

```
./ralph.sh 0 /path/to/project   # custom project root
./ralph.sh 5                    # run 5 cycles then stop
```

#### Realtime agent (optional)

The realtime agent is only needed if you want **automatic notifications** when a slice status changes on the board. If you prefer to trigger runs manually you can skip it entirely.

When you do want it, install its dependencies and start it:

```
cd .build-kit/realtime-agent && npm install && npm run dev
```

On startup the agent fetches platform config, gets a short-lived realtime token, syncs all slices locally, then subscribes. Expected output:

```
[agent] Starting — org=48b548e9-..., board=d886f666-..., base=https://api.eventmodelers.ai
[agent] Persisted 12 slice(s) to .../.build-kit/slices
[agent] Realtime channel "board:d886f666-...-slicechanged" status: SUBSCRIBED
```

Keep this process running when you want automatic board notifications. The realtime token is refreshed automatically every 10 minutes.

#### The full flow — end to end

**TRIGGER — Change a slice status on the board**
Open your board, find a slice, and set its status to **Planned**. The moment you save, the board broadcasts a `slice:changed` event over Supabase Realtime to every connected listener.

**REALTIME AGENT — Agent picks it up → writes tasks.json**
The realtime agent receives the broadcast and immediately appends a task to `.build-kit/tasks.json`:
```
[
  {
    "id": "uuid-...",
    "createdAt": "2026-05-17T12:00:01.000Z",
    "payload": {
      "event": "slice:changed",
      "boardId": "d886f666-...",
      "sliceId": "a3f2c891-...",
      "sliceTitle": "Place Order",
      "sliceStatus": "Planned",
      "timestamp": 1716000000000
    }
  }
]
```
It also re-fetches all board slices and updates the local `.build-kit/slices/` snapshots before writing the task.

**PHASE 1 — ralph loop loads the slice**
The loop detects a non-empty `tasks.json` and runs the Phase 1 agent with `prompt.md`:
1. Read AGENT.md — Loads accumulated learnings from previous iterations before doing anything else.
2. Run /connect — Resolves `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from `.build-kit/.eventmodelers/config.json`.
3. Run /load-slice — Fetches the full slice definition from the board API and writes it to `.build-kit/.slices/<context>/Place-Order/slice.json`. Updates `.build-kit/.slices/<context>/index.json` with metadata and status.
4. Clear the task — Removes the completed task from `tasks.json`. Writes `[]` if the queue is now empty.
5. Log progress — Appends a progress entry to `progress.txt` and updates `AGENT.md` with any new reusable learnings.

**PHASE 2 — ralph loop builds the slice**
In the next cycle the loop finds `"status": "Planned"` in `.slices/**/index.json` and runs the Phase 2 agent with `backend-prompt.md`:
1. Set status InProgress on board — Updates `.build-kit/.slices/<context>/index.json` and calls `/update-slice-status`. The slice changes color on the board in real time.
2. Detect slice type and load matching skill — Reads `slice.json` and selects the right skill:
   - State change — Has commands[] entries → `/build-state-change`
   - State view — Has readModel{} definition → `/build-state-view`
   - Automation — Has non-empty processors[] → `/build-automation`
3. Implement the slice — The skill guides the agent step by step — event types, command handler, DB migration, tests, and route. The slice.json is the source of truth; the code follows what is defined there.
4. Run quality checks — `npm run build` and `npm run test` (slice tests only). If checks fail the agent fixes the issue and retries before committing.
5. Commit and merge — Commits all changes with message `feat: Place Order` and merges the feature branch back to main as a fast-forward merge.
6. Set status Done on board — Updates `.build-kit/.slices/<context>/index.json` to `"status": "Done"` and calls `/update-slice-status`. The slice turns green on the board.
7. Log and wait — Appends a progress entry to `.build-kit/progress.txt`, updates `.build-kit/AGENT.md` with reusable learnings, and returns to idle — polling every 3 seconds for the next slice.

#### Slice statuses

| Status | Description |
|---|---|
| Created | Slice exists on the board, not yet queued |
| Planned | Queued for the agent — triggers Phase 2 |
| InProgress | Agent is currently implementing |
| Review | Implementation complete, awaiting review |
| Done | Fully implemented and merged |
| Blocked | Waiting on an external dependency |
| Assigned | Assigned to a specific person |
| Informational | Documentation-only slice, not implemented |

#### Project files reference

| File | Written by | Purpose |
|---|---|---|
| `.build-kit/.eventmodelers/config.json` | installer | Credentials — token, boardId, orgId, baseUrl |
| `.build-kit/tasks.json` | realtime agent | Task queue consumed by Phase 1 |
| `.build-kit/slices/<id>.json` | realtime agent | Raw board slice snapshots |
| `.build-kit/.slices/<ctx>/index.json` | /load-slice skill | Slice metadata and status |
| `.build-kit/.slices/<ctx>/<folder>/slice.json` | /load-slice skill | Full slice definition — source of truth |
| `.build-kit/progress.txt` | Phase 1 + 2 agents | Work log with codebase patterns section |
| `.build-kit/AGENT.md` | Phase 1 + 2 agents | Accumulated learnings read at every startup |
| `.build-kit/prompt.md` | installer | Phase 1 agent instructions (load slice) |
| `.build-kit/backend-prompt.md` | installer | Phase 2 agent instructions (build slice) |

#### Choosing a runner

The kit ships three ways to run the ralph loop. All share the same `lib/ralph.js` core and the same two-phase logic — the only difference is which model executes the prompts.

- **`./ralph.sh`** (Default) — Recommended for most projects. Pure bash. Calls `lib/agent.sh` which spawns Claude via the shell. No extra Node.js process for the loop itself. Start with: `cd .build-kit && ./ralph.sh`
- **`node ralph-claude.js`** (Node.js) — When you need programmatic control or CI integration. Node.js wrapper around the same ralph core. Spawns `claude --dangerously-skip-permissions` directly. Same behavior as ralph.sh but easier to embed in Node-based tooling.
- **`node ralph-ollama.js`** (Local LLM) — For fully local, offline, or privacy-preserving setups. Replaces Claude with a local Ollama model (default: qwen3:8b). Run `ollama serve` first. Override with `OLLAMA_MODEL=<model>` or `OLLAMA_URL=http://host:11434`.

#### CLI commands

```
npx @eventmodelers/cli init --stack node    # install and configure
npx @eventmodelers/cli status     # check what is installed
npx @eventmodelers/cli uninstall --build-kit  # remove all installed files
```

## Build with Axon

### Build with Axon

*This build kit is being developed openly with community contributors. Expect rapid iteration, new skills, and evolving patterns as we shape it together.*

*Tom's team had 12 slices on the board for their new Axon Framework service. He ran the installer, started the realtime agent, then set the first slice to **Planned**. The ralph loop picked it up, ran `./mvnw compile` and `./mvnw test`, committed the code, and turned the slice green — all without touching the keyboard. He queued the next three slices at once and refilled his coffee.*

Installed via `npx @eventmodelers/cli init --stack axon`, this is an autonomous coding agent loop for **Axon Framework (Java / Spring Boot)** projects. It watches your board for slice status changes, loads the slice definition, implements the code using the matching skill, runs Maven quality checks, commits, and marks the slice Done — all without manual intervention.

**Architecture diagram:**
```
Board (Eventmodelers)
  │  slice status → "Planned"
  ▼
Realtime Agent  ──────────────────►  .build-kit/tasks.json
  │  listens on Supabase channel         │
  │  writes task on slice:changed        │
  ▼                                      ▼
ralph.sh loop ◄────────────────── Phase 1: load slice
  │  checks tasks.json every 3s          reads task → runs /connect + /load-slice
  │                                      fetches slice definition to .build-kit/.slices/
  │                                      removes task from tasks.json
  │
  ▼
Phase 2: build slice
  checks .build-kit/.slices/**/index.json for status "Planned"
  →  status InProgress on board
  →  /build-state-change | /build-state-view | /build-automation
  →  ./mvnw compile + ./mvnw test  →  commit + merge
  →  status Done on board  →  wait for next
```

#### Step 1 — Install

Run the installer in your project directory. It copies all required files, installs the realtime agent dependencies, and writes your credentials to `.eventmodelers/config.json` (automatically gitignored).

```
npx @eventmodelers/cli init --stack axon
```

The installer prompts for three values. Navigate to Account → Team-Boards and click the **Connection Info** copy icon next to your board — it copies all values to your clipboard at once.

*(Screenshot: Account page showing the Connection Info copy button)*

| Field | Where to find it |
|---|---|
| API token | Workspace Settings → API Tokens |
| Organization ID | URL bar: .../org/<UUID>/... |
| Base URL | Default: https://api.eventmodelers.ai |

**Board connection is optional.** The agent can run entirely offline using local slice definitions already in `.build-kit/.slices/`. When no `.eventmodelers/config.json` is present, platform sync (realtime agent, status updates, slice loading from the board) is disabled automatically — code generation from local slice files still works.

Everything is installed inside a `.build-kit/` folder in your project root (gitignored automatically):

| Path | Description |
|---|---|
| `.build-kit/.eventmodelers/config.json` | Your credentials |
| `.build-kit/.claude/skills/connect` | Resolves board credentials for all other skills |
| `.build-kit/.claude/skills/load-slice` | Fetches slice definitions and writes to .slices/ |
| `.build-kit/.claude/skills/update-slice-status` | Changes a slice status on the board |
| `.build-kit/.claude/skills/build-state-change` | Implements command handler slices (Axon aggregate + command handler) |
| `.build-kit/.claude/skills/build-state-view` | Implements projection / read model slices |
| `.build-kit/.claude/skills/build-automation` | Implements reactor / automation slices |
| `.build-kit/.claude/skills/learn-eventmodelers-api` | Full API reference for the agent |
| `.build-kit/realtime-agent/` | Node.js listener for board events (optional) |
| `.build-kit/ralph.sh` | The main two-phase agent loop |
| `.build-kit/prompt.md` | Phase 1 agent instructions (load slice from board) |
| `.build-kit/backend-prompt.md` | Phase 2 agent instructions (build and commit slice) |
| `.build-kit/AGENT.md` | Accumulated learnings shared across loop iterations |

#### Step 2 — Start the ralph loop

Open a terminal, enter the kit folder, and start the loop. It polls every 3 seconds when idle and runs forever unless you pass an iteration limit.

```
cd .build-kit && ./ralph.sh
```

By default ralph targets `../` (your project root). Pass a path to override:

```
./ralph.sh 0 /path/to/project   # custom project root
./ralph.sh 5                    # run 5 cycles then stop
```

#### Realtime agent (optional)

The realtime agent is only needed if you want **automatic notifications** when a slice status changes on the board. If you prefer to trigger runs manually you can skip it entirely.

When you do want it, install its dependencies and start it:

```
cd .build-kit/realtime-agent && npm install && npm run dev
```

On startup the agent fetches platform config, gets a short-lived realtime token, syncs all slices locally, then subscribes. Expected output:

```
[agent] Starting — org=48b548e9-..., board=d886f666-..., base=https://api.eventmodelers.ai
[agent] Persisted 12 slice(s) to .../.build-kit/slices
[agent] Realtime channel "board:d886f666-...-slicechanged" status: SUBSCRIBED
```

#### The full flow — end to end

**TRIGGER — Change a slice status on the board**
Open your board, find a slice, and set its status to **Planned**. The moment you save, the board broadcasts a `slice:changed` event over Supabase Realtime to every connected listener.

**PHASE 1 — ralph loop loads the slice**
The loop detects a non-empty `tasks.json` and runs the Phase 1 agent with `prompt.md`:
1. Read AGENT.md — Loads accumulated learnings from previous iterations before doing anything else.
2. Run /connect — Resolves `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from `.build-kit/.eventmodelers/config.json`.
3. Run /load-slice — Fetches the full slice definition from the board API and writes it to `.build-kit/.slices/<context>/Place-Order/slice.json`. Updates `.build-kit/.slices/<context>/index.json` with metadata and status.
4. Clear the task — Removes the completed task from `tasks.json`. Writes `[]` if the queue is now empty.
5. Log progress — Appends a progress entry to `progress.txt` and updates `AGENT.md` with any new reusable learnings.

**PHASE 2 — ralph loop builds the slice**
In the next cycle the loop finds `"status": "Planned"` in `.slices/**/index.json` and runs the Phase 2 agent with `backend-prompt.md`:
1. Set status InProgress on board — Updates `.build-kit/.slices/<context>/index.json` and calls `/update-slice-status`. The slice changes color on the board in real time.
2. Detect slice type and load matching skill — Reads `slice.json` and selects the right skill:
   - State change — Has commands[] entries → `/build-state-change`
   - State view — Has readModel{} definition → `/build-state-view`
   - Automation — Has non-empty processors[] → `/build-automation`
3. Implement the slice — The skill guides the agent step by step — Axon aggregate, command handler, event sourcing handler, projection, tests, and REST endpoint. The slice.json is the source of truth; the code follows what is defined there.
4. Run quality checks — `./mvnw compile -q` and `./mvnw test -Dtest="<SliceName>*" -q` (slice tests only). If checks fail the agent fixes the issue and retries before committing.
5. Commit and merge — Commits all changes with message `feat: Place Order` and merges the feature branch back to main as a fast-forward merge.
6. Set status Done on board — Updates `.build-kit/.slices/<context>/index.json` to `"status": "Done"` and calls `/update-slice-status`. The slice turns green on the board.
7. Log and wait — Appends a progress entry to `.build-kit/progress.txt`, updates `.build-kit/AGENT.md` with reusable learnings, and returns to idle — polling every 3 seconds for the next slice.

#### Axon Framework specifics

The Axon build kit ships skills tuned for Axon Framework patterns. Each skill follows the Axon way: aggregates handle commands via `@CommandHandler`, emit events via `@EventSourcingHandler`, and projections update read models via `@EventHandler`.

| Skill | Description |
|---|---|
| `/build-state-change` | Aggregate + @CommandHandler + @EventSourcingHandler + REST endpoint + unit tests |
| `/build-state-view` | Projection class + @EventHandler + query handler + read model + integration tests |
| `/build-automation` | Saga or event processor + @SagaEventHandler / @EventHandler + compensation logic |
| `/build-automation-workflow` (PREVIEW) | Multi-step durable process using AF5 @Workflow — handles compensation, human approval, fan-out/fan-in, and timed steps. Analyzes your automation slices and decides which ones need a Workflow vs a plain event handler. |

The installer also scaffolds a ready-to-run Spring Boot + Axon project with Maven wrapper, `docker-compose.yml` for AxonServer, and a base `QuickstartApplication` — so you can go from zero to a running Axon service in minutes.

#### Slice statuses

| Status | Description |
|---|---|
| Created | Slice exists on the board, not yet queued |
| Planned | Queued for the agent — triggers Phase 2 |
| InProgress | Agent is currently implementing |
| Review | Implementation complete, awaiting review |
| Done | Fully implemented and merged |
| Blocked | Waiting on an external dependency |
| Assigned | Assigned to a specific person |
| Informational | Documentation-only slice, not implemented |

#### Project files reference

| File | Written by | Purpose |
|---|---|---|
| `.build-kit/.eventmodelers/config.json` | installer | Credentials — token, boardId, orgId, baseUrl |
| `.build-kit/tasks.json` | realtime agent | Task queue consumed by Phase 1 |
| `.build-kit/slices/<id>.json` | realtime agent | Raw board slice snapshots |
| `.build-kit/.slices/<ctx>/index.json` | /load-slice skill | Slice metadata and status |
| `.build-kit/.slices/<ctx>/<folder>/slice.json` | /load-slice skill | Full slice definition — source of truth |
| `.build-kit/progress.txt` | Phase 1 + 2 agents | Work log with codebase patterns section |
| `.build-kit/AGENT.md` | Phase 1 + 2 agents | Accumulated learnings read at every startup |
| `.build-kit/prompt.md` | installer | Phase 1 agent instructions (load slice) |
| `.build-kit/backend-prompt.md` | installer | Phase 2 agent instructions (build slice) |

#### Choosing a runner

The kit ships three ways to run the ralph loop. All share the same `lib/ralph.js` core and the same two-phase logic — the only difference is which model executes the prompts.

- **`./ralph.sh`** (Default) — Recommended for most projects. Pure bash. Calls `lib/agent.sh` which spawns Claude via the shell. No extra Node.js process for the loop itself. Start with: `cd .build-kit && ./ralph.sh`
- **`node ralph-claude.js`** (Node.js) — When you need programmatic control or CI integration. Node.js wrapper around the same ralph core. Spawns `claude --dangerously-skip-permissions` directly. Same behavior as ralph.sh but easier to embed in Node-based tooling.
- **`node ralph-ollama.js`** (Local LLM) — For fully local, offline, or privacy-preserving setups. Replaces Claude with a local Ollama model (default: qwen3:8b). Run `ollama serve` first. Override with `OLLAMA_MODEL=<model>` or `OLLAMA_URL=http://host:11434`.

#### CLI commands

```
npx @eventmodelers/cli init --stack axon    # install and configure
npx @eventmodelers/cli status     # check what is installed
npx @eventmodelers/cli uninstall --build-kit  # remove all installed files
```

## Build with nodejs + emmet + supabase

### Build with nodejs + emmet + supabase

*Ana wanted to ship a new event-sourced service fast without setting up a Java stack. She ran the Supabase kit installer in an empty folder — it scaffolded a complete TypeScript project with Supabase, Flyway migrations, and Express routes, then immediately started implementing her first slice. When she set the slice to Planned on the board, the ralph loop picked it up, wrote the handler, ran the tests, committed, and turned the slice green. She had working, tested code in minutes.*

Installed via `npx @eventmodelers/cli init --stack supabase`, this is an autonomous coding agent kit for **Node.js + TypeScript** projects backed by **Supabase (PostgreSQL)**. Unlike the other build kits, it also scaffolds a complete project structure into your directory — server, migrations, auth helpers, and event store — so you can start from scratch and have a running backend in one command.

**Architecture diagram:**
```
Board (Eventmodelers)
  │  slice status → "Planned"
  ▼
Realtime Agent  ──────────────────►  .build-kit/tasks.json
  │  listens on Supabase channel         │
  │  writes task on slice:changed        │
  ▼                                      ▼
ralph loop ◄───────────────────── Phase 1: load slice
  │  checks tasks.json every 3s          reads task → runs /connect + /load-slice
  │                                      fetches slice definition to .build-kit/.slices/
  │
  ▼
Phase 2: build slice
  checks .build-kit/.slices/**/index.json for status "Planned"
  →  status InProgress on board
  →  /build-state-change | /build-state-view | /build-automation
  →  npm run build + test  →  Flyway migration  →  commit + merge
  →  status Done on board  →  wait for next
```

#### Step 1 — Install

Run the installer in your project directory. In addition to installing the agent kit, it copies a complete TypeScript + Supabase project scaffold into your project root — server, auth helpers, DB schema, and Flyway migration config.

```
npx @eventmodelers/cli init --stack supabase
```

The installer asks for your credentials. Navigate to Account → Team-Boards and click the **Connection Info** copy icon next to your board — it copies all values at once.

| Field | Where to find it |
|---|---|
| Organization ID | URL bar: .../org/<UUID>/... |
| Board ID | URL bar or Account → Team-Boards |
| Token | Workspace Settings → API Tokens |

**Board connection is optional.** The agent can run entirely offline using local slice definitions already in `.build-kit/.slices/`. When no `.eventmodelers/config.json` is present, platform sync (realtime agent, status updates, slice loading from the board) is disabled automatically — code generation from local slice files still works.

#### What gets installed

The installer writes two things: agent kit files into `.build-kit/`, and a project scaffold into your project root.

Agent kit — `.build-kit/` (gitignored):

| Path | Description |
|---|---|
| `.build-kit/.eventmodelers/config.json` | Your credentials — token, boardId, orgId |
| `.build-kit/.claude/skills/connect` | Resolves board credentials for all other skills |
| `.build-kit/.claude/skills/load-slice` | Fetches slice definitions from the board API |
| `.build-kit/.claude/skills/update-slice-status` | Changes a slice status on the board |
| `.build-kit/.claude/skills/build-state-change` | Implements command handler slices (PostgreSQL event store) |
| `.build-kit/.claude/skills/build-state-view` | Implements projection / read model slices |
| `.build-kit/.claude/skills/build-automation` | Implements reactor / automation slices |
| `.build-kit/.claude/skills/learn-eventmodelers-api` | Full platform API reference for the agent |
| `.build-kit/ralph-claude.js` | Primary runner — uses Claude Code |
| `.build-kit/ralph-ollama.js` | Alternative runner — uses local Ollama model |
| `.build-kit/ralph.sh` | Bash runner — calls lib/agent.sh |
| `.build-kit/lib/prompt.md` | Phase 1 agent instructions (load slice from board) |
| `.build-kit/lib/backend-prompt.md` | Phase 2 agent instructions (build and commit slice) |
| `.build-kit/AGENT.md` | Accumulated learnings shared across loop iterations |

Project scaffold — project root:

| Path | Description |
|---|---|
| `server.ts` | Express server entry point with route registration |
| `src/supabase/` | Supabase client, auth helpers, protected-page utilities |
| `src/common/` | DB connection, event store loader, Supabase Realtime broadcast, replay helpers |
| `supabase/migrations/` | Flyway-style SQL migrations (V1__schema.sql.example as starting point) |
| `supabase/config.toml` | Supabase project configuration |
| `flyway.conf` | Flyway migration runner configuration |
| `.env.example` | Environment variable template — copy to .env and fill in your Supabase credentials |
| `tsconfig.json / vercel.json` | TypeScript and deployment configuration |

#### Step 2 — Start the ralph loop

The supabase kit uses Node.js runners. Start the loop with one of the following from your project root:

```
# Claude (default)
node .build-kit/ralph-claude.js

# Local Ollama model (run `ollama serve` first)
OLLAMA_MODEL=qwen3:8b node .build-kit/ralph-ollama.js

# Pass a custom project directory as the first argument
node .build-kit/ralph-claude.js /path/to/project
```

#### Realtime agent (optional)

The realtime agent listens for `slice:changed` events over Supabase Realtime and writes tasks to `.build-kit/tasks.json`. Without it you can still trigger builds by manually editing `tasks.json` or by having a Planned slice already in `.build-kit/.slices/`.

```
cd .build-kit && npm install && node realtime-agent.js
```

#### Supabase specifics

The skills in this kit target a PostgreSQL-backed event store via Supabase. Each slice is implemented as:

| Skill | Description |
|---|---|
| `/build-state-change` | Command handler that appends events to the PostgreSQL event store, REST route, and tests |
| `/build-state-view` | Projection that reads from the event store and materializes a read model in a Supabase table |
| `/build-automation` | Reactor that listens for events via Supabase Realtime and dispatches follow-up commands |

Database schema changes are implemented as Flyway SQL migrations under `supabase/migrations/`. The agent runs `npm run build` and `npm run test` for quality checks before committing.

#### Choosing a runner

Unlike the Node and Axon kits, the Supabase kit uses Node.js runners as the primary interface (the CLI prints these as the recommended next step after install):

- **`node ralph-claude.js`** (Default) — Recommended — uses Claude Code. Node.js wrapper that spawns `claude --dangerously-skip-permissions` with your board credentials prepended to the prompt. Same two-phase logic as ralph.sh.
- **`node ralph-ollama.js`** (Local LLM) — For fully local, offline, or privacy-preserving setups. Uses a local Ollama model instead of Claude. Run `ollama serve` first. Override the model with `OLLAMA_MODEL=<name>` or point to a remote instance with `OLLAMA_URL=http://host:11434`.
- **`./ralph.sh`** (Bash) — Alternative bash-based runner. Identical two-phase loop but pure bash. Calls `lib/agent.sh` which spawns Claude via the shell. Use if you prefer no Node.js dependency on the loop process itself.

#### Slice statuses

| Status | Description |
|---|---|
| Created | Slice exists on the board, not yet queued |
| Planned | Queued for the agent — triggers Phase 2 |
| InProgress | Agent is currently implementing |
| Review | Implementation complete, awaiting review |
| Done | Fully implemented and merged |
| Blocked | Waiting on an external dependency |

#### CLI commands

```
npx @eventmodelers/cli init --stack supabase    # install kit + scaffold project
npx @eventmodelers/cli status     # check what is installed
npx @eventmodelers/cli uninstall --build-kit  # remove .build-kit/ folder
```

## Build Your Own Build Kit

### Build Your Own Build Kit

*Jonas's team runs Go microservices over PostgreSQL — none of the four built-in stacks fit. He ran `npx @eventmodelers/cli init --build-kit` in an empty repo and got the exact same shape as the Supabase kit — `.build-kit/CLAUDE.md`, three build skills, an AGENT.md — except every file was full of TODOs instead of real content. He kept the Supabase kit open in a second tab as a reference for what a filled-in PostgreSQL event store actually looks like, then spent an afternoon replacing each TODO with his own project's conventions: `go build ./...` instead of `npm run build`, `internal/slices/{name}/` instead of `src/slices/`, `sqlx` instead of the Supabase client. He pointed it at one real slice on the board, let the ralph loop run, fixed what broke, and repeated until a Planned slice reliably came out the other side as tested, committed Go code. Two weeks later he copied his finished `.build-kit/` into `stacks/go-postgres/templates/`, added one entry to `STACKS` in `cli.js`, and opened a PR — now anyone can run `init --stack go-postgres` the same way he ran `--stack supabase`.*

Every build kit — Node, Axon, Cratis, Supabase — is the same three ingredients: a `CLAUDE.md` describing the stack's conventions, three skills (`build-state-change`, `build-state-view`, `build-automation`) that turn a slice definition into real code, and a runner loop that watches the board and dispatches to them. `init --build-kit` installs that exact shape — **with TODO-marked placeholders instead of real content** — for a stack this CLI doesn't support yet, so you're never starting from a blank page.

#### Step 1 — Install the blank scaffold

```
npx @eventmodelers/cli init --build-kit
```

Mutually exclusive with `--stack`, `--modeling`, and `--bridge` — this is a fourth, separate mode. It still asks for your board credentials, since the runner loop underneath (`lib/ralph.js`) is the identical cold-spawn/`tasks.json` engine every real stack uses.

What gets installed — all TODO-marked:

| Path | Description |
|---|---|
| `.build-kit/CLAUDE.md` | Stack conventions, file-structure constraints, build-a-slice flow |
| `.build-kit/lib/AGENT.md` | Where the loop records reusable learnings across iterations |
| `.build-kit/lib/prompt.md` | Phase 1 agent instructions (load slice from board) |
| `.build-kit/lib/backend-prompt.md` | Phase 2 agent instructions (build and commit slice) |
| `.claude/skills/build-state-change/SKILL.md` | How a command-handler slice is implemented |
| `.claude/skills/build-state-view/SKILL.md` | How a projection / read-model slice is implemented |
| `.claude/skills/build-automation/SKILL.md` | How a reactor / automation slice is implemented |
| `README.md, .gitignore` | Placeholder project root — replace with your stack's real scaffold |

#### Step 2 — Keep a real stack open as your reference

Every TODO placeholder tells you which existing kit to study for "the level of detail expected" — `stacks/node`, `stacks/supabase`, `stacks/axon`, or `stacks/cratis-csharp` under this CLI's own source. **Build with nodejs + emmet + supabase** above is a good default reference if your stack also talks to a SQL-backed event store — it shows what a finished `CLAUDE.md`, finished `build-state-change` skill, and finished migration/runner setup actually look like once every TODO is gone.

#### Step 3 — Fill in the TODOs against your real stack

| Blank file | Filled with |
|---|---|
| `.build-kit/CLAUDE.md` | Path constraints, language, module system, build-a-slice flow — copy the shape from Supabase's CLAUDE.md, replace the content |
| `build-state-change/SKILL.md` | File layout for a command handler that validates against replayed events and appends new ones — Supabase's version targets a Postgres event store + Express route |
| `build-state-view/SKILL.md` | How a projection materializes into a queryable read model — Supabase's version writes into a Supabase table |
| `build-automation/SKILL.md` | How a reactor listens for an event and dispatches a follow-up command — Supabase's version uses Supabase Realtime |
| `root/` (README, gitignore, …) | A real minimal starter: build/dependency file, source layout, a slices directory, local infra (docker-compose, migrations) — Supabase's root/ has server.ts, supabase/migrations/, flyway.conf |

One line must survive verbatim in all three skills: *"read the slice definition from `.slices/{Context}/{slicename}/slice.json` before doing anything else"* — that contract is what lets every stack's skills plug into the same board API and runner loop unchanged.

#### Step 4 — Dogfood it on a real slice

Set one slice to `Planned` on your board and start the loop exactly as you would for any built-in stack — it's the same runner. Watch where it stalls or invents something not in `slice.json`, fix the relevant skill or `CLAUDE.md` section, and run it again. Repeat until a Planned slice reliably comes out the other side as working, tested, committed code.

Re-running `init --build-kit` (or any `init --stack`) into a non-empty kit directory now asks for confirmation before overwriting — so the TODOs you've already filled in aren't silently clobbered by a repeat install.

#### Step 5 — Promote it to a first-class stack

Once it works end to end, contribute it back so `init --stack <name>` picks it up for everyone:

```
stacks/<name>/templates/build-kit/          # copy from your .build-kit/
stacks/<name>/templates/.claude/skills/     # copy your build-* skills
stacks/<name>/templates/root/               # copy your real project scaffold
```

Then register the stack in `cli.js`:

```
// STACKS object in cli.js
'<name>': {
  label: '<Human-readable label>',
  kitSubdir: 'build-kit',
  kitDirName: '.build-kit',
  useShared: true,
  needsBoardId: true,
},
```

Finally, add `<name>` to the README's stack list and "What gets installed" section — the `stacks` command's own output is generated from `STACKS`, so nothing else to update there. From this point on, `npx @eventmodelers/cli init --stack <name>` works the same way `--stack supabase` does today.

#### CLI commands

```
npx @eventmodelers/cli init --build-kit         # install the blank scaffold to fill in
npx @eventmodelers/cli status                   # check what is installed
npx @eventmodelers/cli uninstall --build-kit    # remove the .build-kit/ folder
```

## Extensions

### Extensions

Extensions connect Nebulit boards to external systems. Each extension is configured per board and uses the Nebulit API for read and write access.

#### Git Extension (BETA)

The Git Extension syncs your board to a Git repository. Every change made on the board is automatically committed — giving you a full version history of your event model alongside your source code.

*(Screenshot: Git Extension configuration dialog)*

##### How it works

The extension uses the Nebulit API to read and write board data. When you connect a repository, the extension commits the board state to a dedicated branch every time a change is saved. The commit author defaults to **EventModeler Bot** (`platform@eventmodelers.ai`) unless you configure a different name and email.

- **Every change is tracked** — board saves produce a Git commit with a timestamped message.
- **Branch defaults to board ID** — if you leave the branch field empty, the extension uses the board's UUID as the branch name, keeping each board isolated.
- **Subfolder defaults to `boards`** — board files are written under a `boards/` subfolder unless you specify otherwise.

##### Access Token

The extension requires a personal access token with **read_repository** and **write_repository** scopes so it can clone the repo and push commits. The token is stored encrypted and never exposed after saving. You also need a Nebulit API token — generate one under **Account → API Tokens** — which the extension uses to read board data.

The token requires **write_repository** access because the extension pushes commits on every board change. Create a dedicated bot token with minimal repository access rather than using your personal account token.

##### Configuration fields

| Field | Required | Description |
|---|---|---|
| Repository URL | required | Full HTTPS URL of the repository, e.g. https://gitlab.com/your-org/your-repo. |
| Branch | optional | Branch to commit to. Defaults to the board ID (UUID) if left empty. |
| Subfolder | optional | Path within the repository. Defaults to boards if left empty. |
| Provider | required | Git provider: GitLab or GitHub. |
| Access Token | optional | Personal access token with read_repository and write_repository scopes. |
| Author Name | required | Name used for commits. Defaults to EventModeler Bot. |
| Author Email | required | Email used for commits. Defaults to platform@eventmodelers.ai. |

## Data Trail

### Data Trail

The Data Trail traces a single field back through every element it passed through — Screen, Command, Event, Read Model, and back again — so you can answer "where did this value actually come from?" without manually following connectors across the board.

#### Starting a trace

Open any element's field editor and click the trace icon next to a field to launch the Data Trail for that field.

*(Screenshot: Field editor with the Data Trail trace icon highlighted)*

#### Reading the trail

The trail opens as a left-to-right graph, starting at the field you selected and walking backwards through each inbound dependency until it reaches the origin. Each node shows its element type, title, and the field name being traced at that step; a legend maps colors to element types. Click any node to zoom to it on the canvas.

*(Screenshot: Data Trail view tracing a field back through Screen, Command, Event, and Read Model nodes)*

A dashed blue edge means the field was renamed via a mapping on that hop; a solid black edge means the field name passed through unchanged.

#### Copies and duplicated elements

If an element was duplicated on the board (copy/paste), the trail treats the copy and its original as the same element — dependencies discovered through either one are merged, so the trace follows the full chain regardless of which instance the connector was drawn from.