@eventmodelers/cli 1.0.20 → 1.0.21

package/cli.js

@@ -1413,6 +1413,22 @@ async function runModeling(kitDir, projectDir, verbose = false) {
 
   const channelName = `org:${cfg.organizationId}`;
   const realtime = await createRealtimeAdapter(cfg, realtimeToken);
+
+  let lastTokenRefreshAt = 0;
+  async function refreshRealtimeToken(reason) {
+    // Guard against hammering the token endpoint: a rejected channel retries every
+    // ~14s on its own, so without this a bad token would trigger a refresh call per retry.
+    if (Date.now() - lastTokenRefreshAt < 5000) return;
+    lastTokenRefreshAt = Date.now();
+    try {
+      realtimeToken = await getRealtimeToken();
+      await realtime.setAuth(realtimeToken);
+      log(`token refreshed (${reason})`);
+    } catch (err) {
+      log(`token refresh failed (${reason}): ${err.message}`);
+    }
+  }
+
   realtime.subscribe(
     channelName,
     {
@@ -1429,19 +1445,19 @@ async function runModeling(kitDir, projectDir, verbose = false) {
     (status) => {
       log(`channel "${channelName}": ${status}`);
       if (status === 'SUBSCRIBED') drain().catch((err) => log(`initial drain error: ${err.message}`));
+      // A bad/stale token otherwise sits in realtime-js's own rejoin-retry loop until the
+      // next scheduled refresh below — up to 10 minutes of failed joins. Refresh immediately
+      // instead of waiting on the clock.
+      if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
+        refreshRealtimeToken(status).catch(() => {});
+      }
     },
   ).catch((err) => {
     log(`realtime subscribe failed, prompts won't be pushed live: ${err.message}`);
   });
 
-  setInterval(async () => {
-    try {
-      realtimeToken = await getRealtimeToken();
-      await realtime.setAuth(realtimeToken);
-      log('token refreshed');
-    } catch (err) {
-      log(`token refresh failed: ${err.message}`);
-    }
+  setInterval(() => {
+    refreshRealtimeToken('scheduled').catch(() => {});
   }, 10 * 60 * 1000);
 
   const ping = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/SKILL.md

@@ -384,6 +384,16 @@ After the step is done, **every SCREEN and every AUTOMATION on the board must be
 
 > **Placement rule**: A read model must be placed in a column that already contains a SCREEN or AUTOMATION it serves. Do not place read models in columns with no screen or automation — doing so creates orphaned read models that will never have a consumer.
 
+### Pull field mappings from Step 3 — they are the spec, not a guess
+
+**Do not re-derive read model needs from a screen's title or description alone, and do not rely on the orchestrator's phase-summary handoff for this** — if you arrived here via `eventmodeling-orchestrating-event-modeling`, the handoff after Step 3 is a short hand-written prose summary (`.trogonai/interviews/.../EVENTMODELING.md`), not the actual field data. It will not reliably carry the per-field mappings forward. Go back to the board itself:
+
+For every SCREEN node, fetch it directly (`get_node`/`get_nodes`, never from memory) and read its `meta.fields`. Step 3 already required every field to carry a `mapping`, and for view fields that mapping is already in the exact form `"<ReadModelTitle>.<fieldName>"` — recorded specifically so this step doesn't have to re-guess it.
+
+- **Group the screen's fields by the `<ReadModelTitle>` already named in their `mapping`.** That grouping — not a fresh read of the screen's visuals — is the read model's title and field list. Build the READMODEL node from it directly.
+- If a field's `mapping` names a read model that isn't `"<CommandTitle>.<fieldName>"` or `"session:..."` or `"derived:..."`, it is a read-model reference — treat it as a requirement, not a suggestion.
+- A screen with no fields, or with fields that carry no read-model-shaped mapping, is **not** evidence that it needs no read model. Re-check it against the three rules above (view screen / automation / command screen showing prior state) before concluding it's the rare blank-form exception — and say explicitly why it qualifies.
+
 ### Field data lineage — the `mapping` attribute on READMODEL fields
 
 Every field on a READMODEL must carry a `mapping` that says exactly which event (or command) field it is projected from. Use one of these forms:
@@ -582,6 +592,16 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
 
 Skip a connection silently if the target cell is empty. Log each created arrow: `→ connected EVENT→READMODEL "OrderPlaced"→"OrderStatusView"`, `→ connected READMODEL→SCREEN "OrderStatusView"→"Order Status Screen"`, or `→ connected READMODEL→AUTOMATION "OrderStatusView"→"Fulfillment Processor"`.
 
+### Mandatory per-node verification (run before declaring this step done)
+
+Do not declare Step 5 complete on the strength of the read models you happened to design. Instead, **re-fetch every SCREEN and AUTOMATION node on the board** (`get_nodes` per type — don't rely on the list built earlier in this step, the board may have moved on) and check each one individually:
+
+1. Does it now have an incoming `READMODEL → SCREEN` or `READMODEL → AUTOMATION` connection?
+2. If not — is it a provably blank creation form with no prior state? State the reason in one line (e.g. `"Register Account" screen: blank form, no prior state — exempt`).
+3. If it's neither connected nor exempt, it is an **unresolved gap**. Fix it now: design the missing read model (pulling from its `meta.fields`/`mapping` as above) and wire the connection. Do not move to Step 6 with an unresolved gap silently carried forward — either fix it or explicitly flag it to the user as accepted debt.
+
+List the result of this pass (connected / exempt / fixed) for every screen and automation checked — this list is the evidence the orchestrator's Step 5 gate ("every screen data need is satisfied by a read model") actually holds, not just an assumption.
+
 After all read models, screens, automations, and connections are in place, present the Read Model Catalog summary as text to the user.
 
 ---
@@ -694,8 +714,8 @@ Identify UI needs without event sources:
 
 ### Read Model Design
 - [ ] **Typical pattern applied**: most screens follow `READ MODEL → SCREEN → COMMAND → EVENT`
-- [ ] **Every SCREEN from storyboarding is connected to at least one read model** (via `READMODEL → SCREEN`); only blank creation forms may be exempt
-- [ ] **Every AUTOMATION from storyboarding is connected to at least one read model** (via `READMODEL → AUTOMATION`)
+- [ ] **Every SCREEN from storyboarding is connected to at least one read model** (via `READMODEL → SCREEN`); only blank creation forms may be exempt — verified via the mandatory per-node pass above, not assumed
+- [ ] **Every AUTOMATION from storyboarding is connected to at least one read model** (via `READMODEL → AUTOMATION`) — same per-node verification
 - [ ] **No read model is placed without a connected SCREEN or AUTOMATION consumer**
 - [ ] Every read model has clear purpose
 - [ ] Every data field has event source

package/stacks/modeling-kit/templates/.claude/skills/html-screen/SKILL.md

@@ -79,6 +79,8 @@ This skill only has a `pages`/`backgroundColor` field to send (no separate marks
 
 Apply these only to the specific element(s) the request describes — don't guess at additional areas to call out.
 
+**Marked screens and field scoping**: when the same underlying screen is rendered multiple times as separate nodes — once per slice, each with a different mark/highlight calling out a different part of the UI — scope each node's `meta.fields` (Step 5 below) to only the data inside that node's highlighted area, not the full screen. Three slice-specific screen nodes sharing one visual base should end up with three different, narrower field lists, each matching what that node's mark calls out.
+
 ## Step 4 — Render the pages
 
 **Updating an existing node** (`nodeId` was given) — always sends the **complete** pages array, not just the changed/new entry:
@@ -133,7 +135,54 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/html-screen-nodes/$N
 
 Expect `204 No Content` on success from either curl call.
 
-## Step 5 — Report back
+## Step 5 — Define field data lineage (mandatory)
+
+Every screen — new or updated — needs `meta.fields`: one entry per piece of data the screen displays or captures, each with a `mapping` naming where that data comes from. A screen with only a title and no fields is an empty placeholder from a data-lineage standpoint, even if the mockup itself looks complete.
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Read from session | `"session:<fieldName>"` | `"session:customerId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only renders the screen, it does not create READMODEL nodes or connections (that's `eventmodeling-identifying-outputs` or `place-element`, if the model is taken that far). But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. If you can't say which read model a displayed field comes from, that's a sign the model is missing something — not a reason to skip the field.
+
+If this node is one of several sharing the same visual base with different marks/highlights (see "Marked screens and field scoping" above), only list the fields that fall inside *this* node's highlighted area — not every field the shared screen shows.
+
+Set `cardinality` too (`"Single"` unless the field is a repeated/list value), then push the fields onto the node:
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]'
+```
+
+## Step 6 — Report back
 
 Tell the user:
 - The node ID that was created or updated

package/stacks/modeling-kit/templates/.claude/skills/storyboard/SKILL.md

@@ -35,6 +35,9 @@ Before making any API calls, plan all N screens. For each screen, decide:
 - `screenTitle` — human-readable name (e.g. "Enter Credentials")
 - `pages` (default) — one or more complete HTML/CSS fragments for this screen (see "HTML page design" below), or `elements` — a minimal list of grid elements (see "Sketch path" below, aim for 5–8 elements) **only** when the sketch path applies for this storyboard
 - `visualDescription` — a prose description of the screen's visual layout and content (2–4 sentences) that lets someone who cannot see the image understand what is shown: what UI sections appear, what text/labels are visible, where buttons and inputs are placed, and the overall purpose of the screen
+- `fields` — one entry per piece of data this screen displays or captures, each with a `mapping` naming its source (see "Field data lineage" in Step 5b below). Plan this alongside the visuals, not as an afterthought — every displayed value needs a named source.
+
+If several screens in this storyboard share the same visual base but each highlights a different part of it (e.g. one shared mockup, marked up differently per slice), scope each screen's `fields` to only the data inside *that* screen's highlighted area — not the full shared mockup. Different highlight, different (narrower) field list.
 
 Then **create one task per screen** using TaskCreate, naming each task after the screen title. This gives you a visible queue of work. Create the screens directly after each task has been planned.
 
@@ -257,6 +260,44 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/image-nodes/$SCREEN_
 
 Pass the already-computed `actorCellId` directly as `cellId` in either path. Expect success (MCP: `created: true`; curl: `204`). On failure, read the validation error, fix the payload, and retry once before reporting failure.
 
+### Step 5b(ii) — Set field data lineage (mandatory)
+
+Push the `fields` planned in Step 2 onto the node with a `node:changed` call. Every field needs a `mapping`:
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only creates SCREEN/HTML_SCREEN nodes, never READMODEL nodes or connections. But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. Set `cardinality` too (`"Single"` unless it's a repeated/list value).
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<SCREEN_NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [ /* planned fields */ ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<SCREEN_NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "HTML_SCREEN", "fields": [ /* planned fields */ ] }
+  }]'
+```
+
 ### Step 5c — Mark the task complete
 
 After the node and sketch succeed, mark the task for this screen as completed using TaskUpdate.

package/stacks/modeling-kit/templates/.claude/skills/storyboard-screen/SKILL.md

@@ -129,7 +129,52 @@ curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/$NODE_ID/sket
 
 Expect `204 No Content` on success.
 
-## Step 5 — Report back
+## Step 5 — Define field data lineage (mandatory)
+
+Every screen — new or updated — needs `meta.fields`: one entry per piece of data the screen displays or captures, each with a `mapping` naming where that data comes from. A screen with only a title and no fields is an empty placeholder from a data-lineage standpoint, even once the wireframe is rendered.
+
+| Field type | `mapping` | Example |
+|---|---|---|
+| User types a value, sent as a command | `"<CommandTitle>.<fieldName>"` | `"ReserveBike.bikeId"` |
+| Read from session | `"session:<fieldName>"` | `"session:customerId"` |
+| Displayed data, sourced from a read model | `"<ReadModelTitle>.<fieldName>"` | `"ActiveReservationView.status"` |
+| Calculated/formatted only for display | `"derived:<expression>"` | `"derived:formatDuration(durationMinutes)"` |
+
+Name the read model even if it doesn't exist as a board node yet — this skill only renders the screen, it does not create READMODEL nodes or connections. But naming the source is **not optional**: a screen displaying data should almost never have a field with no mapping. If you can't say which read model a displayed field comes from, that's a sign the model is missing something — not a reason to skip the field.
+
+Set `cardinality` too (`"Single"` unless the field is a repeated/list value), then push the fields onto the node:
+
+**Prefer MCP:**
+```
+mcp__eventmodelers__submit_node_events {
+  "boardId": "<BOARD_ID>",
+  "events": [{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]
+}
+```
+
+**Fallback (no MCP):**
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: agent" \
+  -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<event-uuid>", "eventType": "node:changed", "nodeId": "<NODE_ID>",
+    "boardId": "<BOARD_ID>", "timestamp": <NOW_MS>,
+    "changedAttributes": ["meta.fields"],
+    "meta": { "type": "SCREEN", "fields": [
+      {"name": "status", "type": "String", "example": "confirmed", "mapping": "ActiveReservationView.status", "cardinality": "Single"}
+    ] }
+  }]'
+```
+
+## Step 6 — Report back
 
 Tell the user:
 - The node ID that was updated