@eventmodelers/cli 1.0.36 → 1.0.37

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-translating-external-events/references/examples.md

@@ -0,0 +1,306 @@
+# Translating External Events — Worked Examples
+
+These are conceptual worked examples of the translation reasoning this skill applies — useful for understanding the reasoning, but the actual mechanics are the numbered Workflow steps in the main SKILL.md.
+
+## 1. Identify External Event Sources
+
+```
+External System: Payment Gateway (Stripe)
+
+Events received:
+  - charge.succeeded
+  - charge.failed
+  - charge.refunded
+  - charge.dispute.created
+
+Example payload: charge.succeeded
+{
+  "id": "ch_1234567890",
+  "amount": 15000,
+  "currency": "usd",
+  "customer": "cus_9876543210",
+  "status": "succeeded",
+  "created": 1640995200
+}
+
+External System: GPS Location Service (Google Maps)
+
+Events received:
+  - location_update
+  - geofence_enter
+  - geofence_exit
+
+Example payload: geofence_exit
+{
+  "userId": "user-123",
+  "geoFenceId": "hotel-front-entrance",
+  "timestamp": 1640995200,
+  "latitude": 40.7128,
+  "longitude": -74.0060
+}
+```
+
+## 2. Analyze Technical Representation
+
+```
+External Event: charge.succeeded (Stripe)
+
+Technical fields:
+  - id: UUID of charge in Stripe (not meaningful to us)
+  - amount: Integer cents (15000 = $150.00)
+  - currency: ISO code ("usd")
+  - customer: Stripe customer ID (not our customer ID)
+  - status: String indicating success
+  - created: Unix timestamp
+
+Problems with using directly:
+   We don't use Stripe customer IDs (we have our own customer IDs)
+   Currency and amount require interpretation
+   Status is one field in their model, we care about the fact it succeeded
+   Stripe charge ID isn't the same as our order ID
+   We need to correlate back to our Order stream
+```
+
+## 3. Define Domain Translation Rules
+
+```
+Translation: External charge.succeeded → Domain PaymentAuthorized
+
+Mapping rules:
+  charge.id (Stripe) → paymentGatewayRef (store for reconciliation, don't use as primary)
+  charge.customer (Stripe) → Look up: Which of OUR customers has this Stripe ID?
+  charge.amount → paymentAmount (convert from cents)
+  charge.currency → paymentCurrency
+  created → timestamp
+[NEED TO FIND] → orderId (Stripe doesn't tell us! This is critical—how do we know which order?)
+
+Problem identified:
+Stripe webhook comes with charge details but NOT our order ID.
+
+Solutions:
+A. Store Stripe charge ID in our Order when we initiate payment
+     When webhook arrives: charge.id → Look up in OrderPaymentReference
+     Find orderId → Create PaymentAuthorized event
+
+B. Store custom metadata in Stripe charge
+     When creating charge: Include our orderId in metadata
+     When webhook arrives: Extract orderId from metadata
+
+Choose A or B based on Stripe integration approach.
+```
+
+## 4. Handle Correlation
+
+```
+Pattern: Correlation via Reference Tracking
+
+Our system flow:
+  1. Order created in our system: order-123
+  2. We initiate payment with Stripe:
+     - Send amount, customer info
+     - Receive charge ID: ch_1234567890
+     - Store reference: OrderPaymentReference { orderId: order-123, stripeChargeId: ch_1234567890 }
+
+When webhook arrives:
+  1. Webhook: charge.succeeded { id: ch_1234567890, amount: 15000, ... }
+  2. Look up: Find OrderPaymentReference where stripeChargeId = ch_1234567890
+  3. Get orderId from reference
+  4. Create PaymentAuthorized event: { orderId: order-123, amount: 150.00, ... }
+
+Key insight: You must create the correlation bridge when initiating external action.
+```
+
+## 5. Define Translation Scenarios
+
+```
+External Event: charge.succeeded
+Trigger: Stripe webhook arrives with charge details
+Precondition: OrderPaymentReference exists for this charge ID
+Translation logic:
+  1. Extract charge.id from webhook
+  2. Look up OrderPaymentReference.orderId
+  3. Validate order exists and is in Confirmed state
+  4. Create domain event: PaymentAuthorized { orderId, amount, timestamp, ... }
+Success: Domain event produced
+Failure scenarios:
+  - Charge ID not found in references → Log error, don't produce event (manual review)
+  - Order not in Confirmed state → Log error, don't produce event
+  - Duplicate webhook → Idempotent handling (check if event already exists)
+
+--- External Event: geofence_exit
+Trigger: Guest leaves hotel area (GPS geofence)
+Precondition: Guest has opted in to location tracking
+Translation logic:
+  1. Extract userId and geoFenceId from webhook
+  2. Validate guest is currently in hotel
+  3. Check geofence_exit is "hotel-front-entrance" (not just any geofence)
+  4. Create domain event: GuestLeftHotel { guestId: userId, timestamp, ... }
+Success: Domain event produced
+Failure scenarios:
+  - Guest hasn't opted in → Don't produce event (respect privacy)
+  - Guest not checked in → Don't produce event (shouldn't be in geofence)
+  - Unknown geofence → Log error, don't produce event
+```
+
+## 6. Handle Duplicates and Ordering
+
+```
+Problem: Stripe retries charge.succeeded webhook
+Webhook 1: charge.succeeded { id: ch_123 } → Arrives at 10:00 AM
+Webhook 2: charge.succeeded { id: ch_123 } → Arrives at 10:05 AM (retry)
+
+Solution: Idempotent translation
+
+Check before creating event:
+  1. Extract external ID: ch_123
+  2. Query: Does PaymentAuthorized event exist with paymentGatewayRef = ch_123?
+  3. If yes: Do nothing (already processed)
+  4. If no: Create event
+
+This requires storing the external ID in the event:
+PaymentAuthorized event {
+    orderId: order-123,
+    amount: 150.00,
+    paymentGatewayRef: ch_123,  ← Store external ID for deduplication
+    ...
+  }
+```
+
+## 7. Handle Partial or Missing Information
+
+```
+External Event: geofence_exit
+
+Available data:
+  - userId 
+  - geoFenceId 
+  - timestamp 
+  - latitude, longitude (raw GPS)
+
+Missing data:
+  - Guest name (not in webhook payload)
+  - Reason for leaving (not tracked)
+  - Expected return time (not available)
+
+Handling strategy:
+A. Translation enriches from our system:
+     Domain event: GuestLeftHotel {
+       guestId: userId,  ← From webhook
+       timestamp: ...,   ← From webhook
+       guestName: "John Smith",  ← Looked up from guest stream
+       roomNumber: "502",  ← Looked up from guest stream
+       geoFenceId: "front-entrance"  ← From webhook
+     }
+
+B. Some data we don't need:
+     We ignore: latitude, longitude (we just care that guest left)
+
+C. Some data we can infer:
+     We can assume: Guest is now outside hotel
+                    Cleaning crew can visit room
+```
+
+## Legacy markdown structure (superseded — kept for reference only)
+
+Older versions of this skill wrote the translation analysis as a standalone markdown document. The actual output mechanism today is placing each translated domain event on the board (see "Output Format" in the main SKILL.md) — this template is kept only so the shape of the information (what a complete translation write-up covers) stays documented somewhere.
+
+````markdown
+# External Event Translation: [Domain Name]
+
+## External Systems & Events
+
+### System: [External System Name]
+
+**Connection Type**: [Webhook/API polling/WebSocket/Streaming]
+
+**Events Received**:
+- event1_name
+- event2_name
+- event3_name
+
+---
+
+## Translation Rules
+
+### External Event: [Event Name]
+
+**Source System**: [System name]
+
+**Technical Representation**:
+```json
+{
+  "field1": "value",
+  "field2": "value"
+}
+```
+
+**Domain Translation**:
+| External Field | Our Field | Mapping | Notes |
+|---|---|---|---|
+| externalId | n/a | Stored for deduplication | Reference only |
+| customer | [lookup] | Look up our customer ID | Must correlate |
+
+**Correlation Method**:
+[How do we link back to our domain entities?]
+
+**Domain Event Produced**:
+- Event Name: [EventName]
+- Fields: [List with sources]
+
+**Translation Logic**:
+```
+1. Extract from webhook
+2. Validate preconditions
+3. Enrich from our system
+4. Create domain event
+```
+
+**Success Scenario**:
+[What success looks like]
+
+**Failure Scenarios**:
+- Scenario 1: Consequence
+- Scenario 2: Consequence
+
+**Duplicate Handling**: [Idempotent strategy]
+
+--- [Repeat for each external event]
+
+---
+
+## Correlation Reference
+
+Track how external IDs map to our domain:
+
+| Our Entity | External System | External ID Field | Storage | Lookup |
+|---|---|---|---|---|
+| Order | Stripe | charge.id | OrderPaymentReference | By charge ID |
+| Guest | GPS Service | userId | Guest stream | By userId |
+
+---
+
+## Failure & Recovery
+
+### Webhook Arrives for Non-existent Order
+**Symptom**: Stripe sends charge.succeeded for unknown order
+**Cause**: Race condition or data inconsistency
+**Detection**: OrderPaymentReference lookup returns nothing
+**Recovery**: Log error, queue for manual review
+
+### Duplicate Webhooks
+**Symptom**: Same webhook received multiple times
+**Cause**: Stripe retry mechanism or network duplication
+**Detection**: Domain event already exists with same externalRef
+**Recovery**: Idempotent check prevents duplicate event creation
+
+---
+
+## Testing Recommendations
+
+- [ ] Test happy path: External event → Correct domain event
+- [ ] Test missing correlation: External event arrives before our order created
+- [ ] Test duplicate: Same webhook processed twice
+- [ ] Test invalid data: Webhook with missing required fields
+- [ ] Test partial data: Webhook with some fields missing
+- [ ] Test ordering: Multiple webhooks arrive out of order
+````

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-validating-event-models
-description: "Step 9 of Event Modeling - Validate event-sourced models for completeness, consistency, and event sourcing principles. Ensures events are immutable facts, state projections are deterministic, and commands are pure. Identifies gaps and suggests improvements before code generation. Use when reviewing models before code generation. Do not use for: the structured 23-check production checklist (use eventmodeling-validating-event-models-checklist) or field-level completeness verification (use eventmodeling-checking-completeness)."
+description: "Step 9 of Event Modeling - Validate event-sourced models for completeness, consistency, and event sourcing principles. Ensures events are immutable facts, state projections are deterministic, and commands are pure. Identifies gaps and suggests improvements before code generation. Use when reviewing models before code generation. Do not use for: the structured 17-check production checklist (use eventmodeling-validating-event-models-checklist) or field-level completeness verification (use eventmodeling-checking-completeness)."
 allowed-tools:
   - Write
   - Bash
@@ -33,16 +33,7 @@ mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "COMMAND" }
 mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "READMODEL" }
 ```
 
-**Fallback (no MCP):**
-
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Context".
 
 After validation, use the `handle-comment` skill to post findings on the relevant nodes — `TASK` for critical violations that must be fixed, `QUESTION` for warnings and recommendations. (That skill already handles the `add_comment` MCP-vs-curl choice internally — no separate rewrite needed here.)
 
@@ -53,6 +44,16 @@ Ensures event-sourced models are complete, correct, and follow pure event sourci
 
 When given an event model, perform comprehensive validation:
 
+### 0. Automated structural pass — run `validate_model` first
+
+Before the manual checks below, run the server-side checklist once per chapter:
+
+```
+mcp__eventmodelers__validate_model { "boardId": "$BOARD_ID", "chapterId": "<chapterId>" }
+```
+
+It returns a compact `findings` list (no node dumps) covering: unplaced nodes, backward arrows among the forward-only pairs (with the todo-list `EVENT → READMODEL` exception already applied), COMMANDs with zero or multiple issuers, READMODELs with no inbound EVENT, columns with more than one screen, and COMMAND/READMODEL columns with no SCENARIO. This replaces the per-type `get_nodes` scans and the `get_node` `projection: "edges"` spot-checks those manual checks would otherwise need — start from its `findings`, then use the sections below for the semantic checks it can't make (naming, immutability, field-source traceability, scenario coverage depth). A `verdict` of `PASS` on `validate_model` is necessary but not sufficient — still do the semantic pass.
+
 ### 1. Swimlane Completeness Check
 
 Verify each swimlane has:

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models/references/api-fallback.md

@@ -0,0 +1,14 @@
+# Validating Event Models — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Board Context
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/SKILL.md

@@ -45,15 +45,9 @@ mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "COMMAND" }
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "READMODEL" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Context".
+
+Also run `validate_model` (`{boardId, chapterId}`) once per chapter up front — several checklist items (Command With Multiple Issuers in Phase 1, backward-arrow / event-flow in Phase 6, read-model-source distinctions in Phase 3) have a purely structural half the tool answers directly, so start each of those from its `findings` and spend the manual effort on the semantic judgement the tool can't make.
 
 Use the board nodes as the model input. After the checklist, use `handle-comment` to post `TASK` comments on nodes that fail checks (that skill covers the MCP `add_comment`/curl choice for comment-posting itself).
 
@@ -154,20 +148,8 @@ CalculationPerformed {
 **Why**: Calculations change multiple times as source data changes. Events are immutable.
 
 ### 2. Shared vs Handler-Owned State
-```
- ANTI-PATTERN:
-One shared "OrderAggregate" class used by all handlers
-- ConfirmOrderHandler shares OrderAggregate state
-- ShipOrderHandler modifies same OrderAggregate
-- Result: Tight coupling, hard to parallelize
 
- CORRECT:
-Each handler owns its own [CommandHandler]State class
-- ConfirmOrderState (only ConfirmOrderHandler uses)
-- ShipOrderState (only ShipOrderHandler uses)
-- CancelOrderState (only CancelOrderHandler uses)
-- All reconstruct state from same events, but independently
-```
+The DDD-aggregate anti-pattern — one shared state class used by every handler — versus the correct pattern of one minimal, handler-owned state class per command. See `eventmodeling-designing-event-models`'s "Core Architectural Rule" for the full worked example (`OrderAggregate` vs. per-command state).
 
 **Why**: Each handler is a micro-slice. Separate state classes maintain isolation, enable parallel teams, prevent merge conflicts.
 
@@ -206,22 +188,10 @@ Reconstruct [CommandHandler]State on-demand
 **Why**: State is derived from events, never stored. Events are source of truth. This enables consistent replay, audit trails, and time-travel debugging.
 
 ### 5. Command With Multiple Issuers
-```
- ANTI-PATTERN:
-FlagLoanOverdue (COMMAND) has two inbound edges:
-- "Flag Overdue Loans" (AUTOMATION, same column)
-- "Adjust Due Date" (SCREEN, previous column)
-- Result: unclear who/what actually triggers the command; validation and UI-vs-automation
-  authority checks (e.g. Role & Actor Attribution) can no longer be answered
 
- CORRECT:
-FlagLoanOverdue (COMMAND) has exactly one inbound edge, from the AUTOMATION that owns it.
-If the SCREEN's user genuinely needs to trigger the same outcome, that's a second,
-distinctly-named command (or the SCREEN issuing it directly, with the automation removed) —
-not two issuers sharing one command.
-```
+A command is never issued by more than one thing — a COMMAND with 2+ inbound SCREEN/AUTOMATION edges hides which actor is actually responsible. See `place-element`'s Step 7c for the full check-and-fix mechanics (which edge to keep, how to remove the rest).
 
-**Why**: A command is never issued by more than one thing. Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node hides which actor is actually responsible, and usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against this — see `learn-eventmodelers-api` §3). Fix by removing the extra edge via `set_connection` (`action: "remove"`), not by keeping both.
+**Why**: Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against fresh occurrences — see `learn-eventmodelers-api` §3).
 
 ---
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/references/api-fallback.md

@@ -0,0 +1,14 @@
+# Event Model Validation Checklist Skill — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Board Context
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```

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

@@ -45,93 +45,11 @@ mcp__eventmodelers__add_field_examples { "boardId": "$BOARD_ID", "cellName": "<t
 
 If this succeeds, skip straight to Step 6 (report back), describing the fields the tool reports as changed. Use the manual fallback flow below (Steps 2–5) only if MCP isn't connected.
 
-### Fallback (no MCP) — Step 2: Resolve the element
-
-Try the resolution strategies in order until one succeeds.
-
-### 2a — UUID
-If `target` looks like a UUID (pattern `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), fetch it directly:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$target" \
-  -H "x-user-id: examples-skill"
-```
-
-### 2b — Name search
-If `target` is not a UUID, search by name:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/events/search?name=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$target")" \
-  -H "x-user-id: examples-skill"
-```
-
-Pick the best match (exact title match preferred; case-insensitive). If multiple matches exist, list them and ask the user to pick one.
-
-### 2c — Cell name (spreadsheet-style, e.g. "B3")
-If `target` matches the pattern `[A-Z]+[0-9]+`:
-
-1. Fetch all chapters on the board to find the relevant timeline:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER" \
-  -H "x-user-id: examples-skill"
-```
-
-If multiple chapters exist, ask the user which one to use.
-
-2. Fetch the chapter **fresh** to decode the grid — never use cached chapter data, as cells are updated frequently:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID" \
-  -H "x-user-id: examples-skill"
-```
-
-From `meta.timelineData`, decode the cell name into a `cellId`:
-- Column letter(s) → 0-based column index (A=0, B=1, … Z=25, AA=26, …)
-- Row digit → 0-based row index (1→0, 2→1, …)
-- Find the matching column in `columns` and the matching row in `rows`.
-- Compute: **`CELL_ID = row.id + "-" + column.id`** (cell IDs are always `<rowId>-<columnId>`).
-
-3. **Always fetch the cell live** to get the current node list — do not rely on the `nodeId` in the chapter's cell data, as it may be stale. No MCP equivalent: `get_nodes` only filters by `type`, not `cellId`:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID" \
-  -H "x-user-id: examples-skill"
-```
-
-Use the first non-CHAPTER result (filter out CHAPTER type).
-
-If no element is found after all strategies, stop and tell the user what was tried.
-
-Save the resolved node as `TARGET_NODE` (full JSON including `id`, `meta`, `edges`).
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 2 — Resolve the element".
 
 ---
 
-### Fallback (no MCP) — Step 3: Load linked elements for context
-
-Collect nearby elements to understand the domain context and generate consistent examples. **Never fetch all board nodes.** Only fetch specific nodes you already have IDs for.
-
-### 3a — Nodes from edges
-If `TARGET_NODE.edges` is non-empty, fetch each connected node individually by its ID:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<EDGE_NODE_ID>" \
-  -H "x-user-id: examples-skill"
-```
-
-Fetch all edge-connected nodes in parallel (one request per node ID).
-
-### 3b — Nodes from the same column (cell-based resolution only)
-If you resolved `TARGET_NODE` via a cell name (Step 2c), you already have the full chapter `cells` array in memory. Use it — **no extra API call needed**:
-
-- Find all cells that share the same `colId` as `TARGET_NODE`'s cell.
-- Collect their `nodeId` values (skip the target itself and any cell without a `nodeId`).
-- Fetch each of those nodes individually by ID (in parallel):
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<NODE_ID>" \
-  -H "x-user-id: examples-skill"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 3 — Load linked elements for context".
 
 ### 3c — Read neighbour fields
 For each neighbour element collected above (COMMAND, EVENT, READMODEL), extract its `meta.fields` and their existing `example` values. This gives you a pool of consistent values to reuse — e.g. if a COMMAND already has `email: "jane@example.com"`, use the same email in the linked EVENT.
@@ -183,32 +101,7 @@ mcp__eventmodelers__submit_node_events {
 }
 ```
 
-**Fallback (no MCP at all)** — build the payload with Python to avoid shell JSON-escaping issues, then POST it:
-
-```bash
-python3 - <<EOF > /tmp/examples_payload.json
-import json, time, uuid
-payload = [{
-  "id": str(uuid.uuid4()),
-  "eventType": "node:changed",
-  "nodeId": "<TARGET_NODE.id>",
-  "boardId": "<BOARD_ID>",
-  "timestamp": int(time.time() * 1000),
-  "changedAttributes": ["meta.fields"],
-  "meta": {
-    "fields": <updated-fields-array as Python list>
-  }
-}]
-print(json.dumps(payload))
-EOF
-
-curl -s -w "\n%{http_code}" -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
-  -H "Content-Type: application/json" \
-  -H "x-token: $TOKEN" \
-  -H "x-board-id: $BOARD_ID" \
-  -H "x-user-id: examples-skill" \
-  --data-binary @/tmp/examples_payload.json
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 5 — Write the update".
 
 Verify the response is HTTP 200. If it fails, report the error and stop.