@eventmodelers/cli 1.0.36 → 1.0.37

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

@@ -174,181 +174,13 @@ InventoryLevelView
 
 ## Workflow
 
-Given commands and events, identify all outputs:
-
-### 1. Map Event Data to UI Screens
-For each screen, identify source events:
-
-```
-Screen: Order Status View
-Displays data from events:
-  orderId ← OrderCreated event
-  customerId ← OrderCreated event
-  items ← OrderCreated event
-  total ← OrderCreated event
-  status ← OrderConfirmed event (or OrderCancelled)
-  confirmedAt ← OrderConfirmed event
-  paymentId ← PaymentAuthorized event
-  shipmentId ← OrderShipped event
-  shippedAt ← OrderShipped event
-
-This screen is a projection of these events:
-  - OrderCreated
-  - OrderConfirmed
-  - PaymentAuthorized
-  - OrderShipped
-```
-
-### 2. Define Read Models
-Create optimized views from event data:
-
-```
-ReadModel: OrderStatusView
-Purpose: UI displays current order status
-Events subscribed: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped, OrderCancelled
-Data:
-{
-  orderId: string (from OrderCreated)
-  customerId: string (from OrderCreated)
-  status: enum (from events: Draft → Confirmed → Authorized → Shipped → Delivered)
-  createdAt: Date (from OrderCreated)
-  confirmedAt: Date (from OrderConfirmed)
-  paymentId: string (from PaymentAuthorized)
-  shipmentId: string (from OrderShipped)
-  shippedAt: Date (from OrderShipped)
-}
-```
-
-### 3. Document Event → Data Mapping
-Show exactly what data each event provides:
-
-```
-Event: OrderCreated
-Provides to UI/Processors:
-  orderId
-  customerId
-  items[]
-  total
-  shippingAddress
-  createdAt
-
-Event: OrderConfirmed
-Provides to UI/Processors:
-  orderId (link to stream)
-  paymentMethod (user selected method)
-  confirmedAt (timestamp)
-  paymentId (payment system reference)
-
-Event: PaymentAuthorized
-Provides to UI/Processors:
-  orderId (link to stream)
-  paymentId
-  authCode
-  authorizedAt (timestamp)
-  amount (verified amount)
-
-Event: OrderShipped
-Provides to UI/Processors:
-  orderId (link to stream)
-  shipmentId
-  shippedAt (timestamp)
-  carrier (shipping company)
-  trackingNumber (for delivery tracking)
-```
-
-### 4. Create Output Catalog
-List all read models:
-
-```
-ReadModel Catalog: Order System
-
-1. OrderStatusReadModel
-   Purpose: UI shows current order status
-   Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped, OrderCancelled
-   Data: orderId, status, createdAt, confirmedAt, paymentId, shipmentId
-   Consumed by:
-     - Order Status screen (UI)
-     - Customer Dashboard (UI)
-     - Order Processing Processor (decides if can ship)
-
-2. OrderListReadModel
-   Purpose: UI lists all orders for a customer
-   Events: OrderCreated, OrderConfirmed, OrderCancelled
-   Data: orderId, customerId, total, status, createdAt
-   Consumed by:
-     - Customer Order History (UI)
-     - Order Search/Filter (UI)
-
-3. PaymentStatusReadModel
-   Purpose: UI shows payment status
-   Events: OrderConfirmed, PaymentAuthorized, PaymentFailed
-   Data: orderId, paymentId, status, authCode, failureReason, timestamp
-   Consumed by:
-     - Payment Status screen (UI)
-     - Accounting Processor (reconciliation)
-
-4. ShipmentTrackingReadModel
-   Purpose: UI shows tracking information
-   Events: OrderShipped, DeliveryConfirmed
-   Data: orderId, shipmentId, trackingNumber, carrier, shippedAt, estimatedDelivery
-   Consumed by:
-     - Order Tracking screen (UI)
-     - Customer notifications (Processor)
-```
-
-### 5. Identify Missing Data
-Check if all UI needs are covered:
-
-```
-Question: What if UI needs "estimated delivery date"?
-Event: OrderShipped has carrier + trackingNumber
-Action needed: Add estimatedDelivery to OrderShipped event
-  (or compute from carrier info)
-
-Question: What if UI needs to show "payment method" on status?
-Event: OrderConfirmed has paymentMethod
-Action needed: Include paymentMethod in relevant read models
-
-Question: What if UI needs "item descriptions"?
-Event: OrderCreated has items[]
-But: items[] only has productId
-Action needed: Enrich with product descriptions from catalog
-  (via join with product service)
-```
-
-### 6. Processor Outputs
-Identify what processors consume:
-
-```
-Processor: Inventory System
-Consumes from read models:
-  - Orders in "PaymentAuthorized" status
-  - Items and quantities needed
-Produces commands:
-  - ReserveInventory
-
-Processor: Fulfillment System
-Consumes from read models:
-  - Orders in "InventoryReserved" status
-  - Items and quantities
-  - Shipping address
-Produces commands:
-  - CreateShipment
-
-Processor: Notification System
-Consumes from read models:
-  - OrderCreated (sends confirmation)
-  - OrderConfirmed (sends receipt)
-  - OrderShipped (sends tracking)
-  - DeliveryConfirmed (sends thank you)
-Does not produce commands (info-only)
-```
+Given commands and events, identify all outputs: for each screen, trace which events its data comes from; define a read model per component; document the event→data mapping; catalog the resulting read models; check for UI needs with no event source; and identify what processors consume. A full worked example of this reasoning (Order/Payment domain) is in `references/examples.md`.
 
 ## Output Format
 
-Instead of writing a markdown document, **place each READMODEL (and any missing AUTOMATION) on the board** using the `node:created` API. Screens are typically already placed from Step 3 (storyboarding) as one plain screen per screen state — Step 3 does not pre-split anything, so working out how many components a screen actually has is this step's job (Step 5a below), not something to re-derive from storyboarding's output. Do not re-place an existing screen unless one is clearly missing. Automations are placed here when analysis reveals a processor that reads state and issues commands but is not yet on the board.
+Instead of writing a markdown document, **place each READMODEL (and any missing AUTOMATION) on the board** using the `node:created` API. Screens are typically already placed from Step 3 (storyboarding) as one plain screen per screen state — Step 3 does not pre-split anything, so working out how many components a screen actually has is this step's job (Step 5a below), not something to re-derive from storyboarding's output. Do not re-place an existing screen unless one is clearly missing. Automations are placed here only in the rare case where analysis reveals a processor that reads state and issues commands but was missed entirely in Step 4 — if that happens, immediately apply `eventmodeling-designing-automation-chains`'s rules to it (todo-list read model, translation chain if externally triggered) before continuing, rather than leaving it for Step 5i's defensive re-check to catch.
 
-This step proceeds as a sequence of lettered sub-steps: identify each screen's components (5a), identify todo-list read models for automations (5b), break multi-component screens apart into copies (5c), then design and place one read model per component (5d onward).
+This step proceeds as a sequence of lettered sub-steps: identify each screen's components (5a), break multi-component screens apart into copies (5c), then design and place one read model per component (5d onward). Every automation's todo-list read model and any translation chain is designed in **Step 4b** (`eventmodeling-designing-automation-chains`), immediately after Step 4 — not here. This step only ever designs screen-facing read models; Step 5i below re-checks automations defensively, not as this step's primary job.
 
 > **CRITICAL: Every READMODEL node MUST include `meta.fields` with a `mapping` on every field.** A read model without fields — or with fields that lack `mapping` — has no data lineage and cannot be traced back to its source events.
 
@@ -372,7 +204,7 @@ Automations follow:
 READ MODEL → AUTOMATION → COMMAND → EVENT
 ```
 
-Treat any screen or automation without an incoming read model as a gap. A screen may be exempt if it provably needs no prior state at all (e.g., a blank registration form) — an **automation is never exempt**: every automation gets a todo-list read model, even a trivial one that opens and closes within the same slice (see Step 5b).
+Treat any screen or automation without an incoming read model as a gap. A screen may be exempt if it provably needs no prior state at all (e.g., a blank registration form) — an **automation is never exempt**: every automation gets a todo-list read model, even a trivial one that opens and closes within the same slice. For automations, that read model was already designed in **Step 4b** (`eventmodeling-designing-automation-chains`); this step's job is limited to the defensive re-check in Step 5i below.
 
 ### Step 5a — Enumerate consumers and identify components
 
@@ -380,7 +212,7 @@ Treat any screen or automation without an incoming read model as a gap. A screen
 
 Read models exist to serve the elements already on the board:
 - Every **view screen** (output/read model screen) needs at least one read model to supply its data.
-- Every **automation** needs at least one read model to read from — its todo list. This applies to every automation without exception, not only ones that visibly "decide" something; see Step 5b for how to identify it.
+- Every **automation** needs at least one read model to read from — its todo list. This applies to every automation without exception, not only ones that visibly "decide" something; this was already handled in Step 4b (`eventmodeling-designing-automation-chains`) for every automation placed in Step 4.
 - Every **command/input screen** needs a read model unless it is a blank creation form with no prior state to display (this is the rare exception, not the rule).
 
 For each SCREEN node, look at its rendered layout and its `meta.fields` and identify its components — groups of fields/UI elements a user would perceive as one area: a stats tile, a list below it, a summary card, a detail panel, a status column in a table, etc. **Most screens genuinely have exactly one component — do not force a split.** A screen has more than one component only when a user would point at two separate areas and describe them as different things.
@@ -391,42 +223,9 @@ Once a component's fields are genuinely homogeneous (every field needs the same
 
 After this step is done, **every SCREEN and every AUTOMATION on the board must be connected to at least one read model** via a `READMODEL → SCREEN` or `READMODEL → AUTOMATION` connection, and every screen identified above as having 2+ components must have been broken apart per Step 5c before any read model is placed. If a screen or automation has no incoming read model connection, it is a gap — either a read model is missing or the connection arrow is missing.
 
-> **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.
-
-### Step 5b — Identify todo-list read models for automations
-
-**Every AUTOMATION needs a todo-list read model — this is not optional, and there is no "pure relay" exemption.** An automation is a processor: it reacts to events, decides what work is outstanding, and issues commands to get that work done. The read model that tells it what's outstanding is its **todo list** — a queue of pending work items, not a snapshot of current entity state.
-
-**The pattern**: one or more events *open* an item on the todo list (something now needs doing); one or more events *close* it (the work is done — remove the item). A todo list can be opened and closed by more than one event type on either side, and the set of opening events doesn't need to match the set of closing events in count or shape — whatever the domain calls for.
-
-**Worked example**: an automation that reacts to `CustomerRegistered` by sending a welcome notification.
-- Todo list: **NotificationsToSend** — one row per pending notification.
-- `CustomerRegistered` **opens** a row (a notification now needs sending).
-- `NotificationSent` (the event this automation's own resulting command produces) **closes** that row (removes it — the list only ever shows outstanding work).
-- The automation (`Send Welcome Notification`) reads `NotificationsToSend`, and for every open row issues `SendNotification`.
+> **Placement rule**: A read model must be placed immediately upstream of the SCREEN or AUTOMATION it serves — sharing that column when possible (a SCREEN with a free interaction row), or one column to the left when not (any AUTOMATION; a SCREEN whose column is already occupied). Do not place a read model with no screen or automation in the very next column — doing so creates an orphaned read model that will never have a consumer.
 
-Even an automation that looks like a "pure signal relay" still has a todo list — model it anyway: it documents that the automation is idempotent/complete once its own event fires, and keeps every automation consistent with the same `READMODEL → AUTOMATION → COMMAND → EVENT` pattern instead of silently exempting some as "too simple to need one."
-
-**There is no such thing as an invisible or informal "signal" — a trigger is always a real EVENT node, placed in a second swimlane when it belongs to another system.**
-
-**An automation can only ever be directly triggered by an internal event — never by another system's event.** A "trigger" arriving from a second swimlane is not itself the thing that drives your domain's work; it first has to be *translated* into an internal event. Do not model this as one automation whose todo list is opened by the external EVENT and that also does the real work (e.g. an automation reading a todo list opened by `ReservationRequested` from another system's swimlane and directly issuing `ReserveCopy`) — that lets an external system trigger domain work with no translation step, which this model doesn't allow. **Apply this now, in Step 5** — Conway's Law (Step 6) only confirms the boundary, it doesn't introduce the chain. When an integration trigger comes from another team's system, model it as **two chained automations**, never one:
-
-1. **Translation automation** — converts the external fact into an internal one; the other system's own decision logic is out of scope. Its todo list is opened by the external EVENT and closed by the internal EVENT its own command produces — the one and only place an external EVENT may open a todo list.
-   - **Three separate columns**, left to right: `[external EVENT] → [todo-list READMODEL] → [AUTOMATION + COMMAND + internal EVENT]`. Never crammed into one or two — the "one EVENT per column" rule applies here too.
-   - **Name the internal EVENT for its business meaning, not the transport** — usually the same name as the external EVENT (e.g. external `CopyReserved` → internal `CopyReserved`; the swimlane already shows which is which), never a mechanical `<X>SignalReceived`/`<X>RequestReceived` suffix. Same for the automation/command: `Record Reservation`/`RecordReservation`, not `Record Reservation Signal`/`RecordReservationSignal`.
-   - Its command and event carry no business decision — they only exist to produce the internal fact the next automation needs.
-2. **Worker automation** — the one that does the actual work (the domain reaction the process is really about, e.g. `ReserveCopy`). Its todo list is opened **only** by the internal EVENT the translation automation produced (this chapter's own swimlane) — never by the external EVENT directly — and closed by whatever event marks that work done.
-
-Wire the todo lists the standard way for each automation separately: for the translation automation, the external EVENT (second swimlane) **opens** the row and its own resulting internal EVENT **closes** it; for the worker automation, that same internal EVENT **opens** its row and its own resulting EVENT **closes** it. `EVENT → READMODEL` connections from both swimlanes are unaffected by which swimlane the event sits in.
-
-**Fields**: a todo-list read model's fields describe the pending item — the identity it's about (e.g. `customerId`) plus enough context to act on it (e.g. `email`, `notificationType`). Do not add a `status` field to mark items done — a todo list's "open" state is *membership in the list itself* (the row exists at all), not a status flag on a row that never leaves. If the same underlying data is also useful with an explicit status column for a different consumer, that is a different read model, not this one.
-
-**Connections and placement**: the todo-list read model goes in the interaction lane, same column as its automation (actor lane) — the same `READMODEL → AUTOMATION` placement covered in Step 5f below.
-- Connect READMODEL → AUTOMATION **first** (the automation reads its own todo list) — the closing connection below is only accepted once this edge exists.
-- Connect every **opening** EVENT → READMODEL.
-- Connect every **closing** EVENT → READMODEL — including the automation's own resulting event, even though that event is produced by the command this same automation issues. This is not a backward arrow: `EVENT → READMODEL` connections are exempt from column ordering when the read model already feeds an AUTOMATION (see `learn-eventmodelers-api` §3) — this todo-list read model qualifies because of the `READMODEL → AUTOMATION` edge above. A read model in this shape is a live projection, not a frozen snapshot — a later event closing an earlier-opened item is the normal case, not an exception to reach for only when convenient.
-
-After this step, every AUTOMATION on the board must have an incoming `READMODEL → AUTOMATION` connection to a todo-list read model — treat a connectionless automation exactly like a connectionless screen with no exemption: a gap to fix, not something to note and move past.
+> **Automation todo-list read models are designed in Step 4b, not here.** The full pattern — every automation's todo-list read model, the "no invisible signal" rule, and the two-chained-automation translation requirement for externally-triggered automations — now lives in `eventmodeling-designing-automation-chains` (Step 4b), which runs immediately after Step 4, before this step. If Step 4b ran, every automation already on the board has its todo-list read model wired; Step 5i below only re-checks this defensively. The rare exception is an automation discovered only now, during output analysis (see "Output Format" above) — if that happens, apply `eventmodeling-designing-automation-chains`'s rules to it directly rather than re-deriving them here.
 
 ### Step 5c — Break apart multi-component screens into copies
 
@@ -435,7 +234,7 @@ After this step, every AUTOMATION on the board must have an incoming `READMODEL
 - Each copy is the **same page**, so it **keeps the same screen name/title** — do not rename copies after their component (e.g. don't title one copy `"Librarian Dashboard — Statistics"` and another `"Librarian Dashboard — Recently Added"`; both stay `"Librarian Dashboard"`).
 - Distinguish copies visually, not by name: **mark/highlight the one component each copy is about**, using the `html-screen` skill's native Marks feature — see that skill's "Marks" section for the full mechanism. In short: the component of interest gets `data-em-mark-id`/`em-mark em-mark-<colorhex>` baked onto it in the page HTML, paired with a matching `meta.marks` entry (`{id, color, pageIndex, blurOutside: true}`) that blurs every other top-level section. Never hand-roll this with inline `filter`/`outline`/`opacity` CSS — that does not match how the app itself renders a mark.
 - Use the `html-screen` skill to produce each copy: pass it the original screen's markup, explicitly asking it to mark/highlight the one component to keep crisp and blur the rest (this satisfies `html-screen`'s "only when the user explicitly asks for one" condition for its Marks feature — the ask comes from this step). This is the skill's job — don't hand-roll the markup here.
-- Place each copy in its own column, one column to the right of the read model that will feed it — this is normally a different column per copy, since each component typically has a different natural source event.
+- Place each copy in its own column, the **same column** as the read model that will feed it (insert a new column immediately before if that copy's column is already occupied) — this is normally a different column per copy, since each component typically has a different natural source event.
 
 Why this matters, beyond tidiness:
 - **It prevents backward arrows.** A single screen-wide read model is forced to aggregate from whatever events each of its components needs, which often means reaching back across many columns to events scattered throughout the timeline — and the read model can only sit in one column, so some of those connections end up spanning a wide gap or, worse, pushing the read model's column later than some of its screen's other consumers require. Splitting by component lets each narrower read model sit close to its own natural source event(s), keeping every `EVENT → READMODEL` arrow short and forward.
@@ -489,9 +288,9 @@ Every field must also set `"cardinality"` — use `"Single"` unless the field ge
 }
 ```
 
-Read models go in the `interaction` lane — **in the same column as the SCREEN or AUTOMATION they serve** (READMODEL in interaction row, SCREEN in actor row of the same column).
+Read models go in the `interaction` lane. For a **SCREEN**, the primary read model shares the SCREEN's column (READMODEL in interaction row, SCREEN in actor row of the same column) — unless that column's interaction row is already occupied (e.g. a command/input screen, where the COMMAND already sits there), in which case the read model goes one column to the left instead. For an **AUTOMATION**, the read model always goes one column to the left, never the same column — an automation's own column already holds the COMMAND it issues. If a consumer needs more than one read model, only the primary one gets this placement; every additional read model goes further left still.
 
-> **Timeline alignment rule**: Place the read model in the same column as its consumer screen/automation. If that column already holds a COMMAND (state-change slice occupies the interaction row), insert a new column immediately after (`{"index": N+1}`) and place both the READMODEL and any new SCREEN there. Do not append read model columns to the end of the timeline — doing so severs the visual left→right flow from data projection to UI consumption.
+> **Timeline alignment rule**: Place the read model in the same column as its consumer screen when that column is free, or one column before its consumer (screen or automation) when it isn't. Insert the new column immediately **before** the consumer's column (`{"index": consumerColumnIndex}`, shifting the consumer right) rather than after — the read model must sit upstream of (to the left of) the element it feeds. Do not append read model columns to the end of the timeline — doing so severs the visual left→right flow from data projection to UI consumption.
 
 ### Step 5f — Placing READMODEL and AUTOMATION nodes with `cellId` (Mandatory)
 
@@ -499,14 +298,16 @@ Read models go in the `interaction` lane — **in the same column as the SCREEN
 
 **For a READMODEL** (interaction lane):
 
-**Prefer MCP** — `place_element` collapses finding/creating the empty interaction cell (including inserting a new column when the target column is already occupied by a COMMAND) and creating the node into one call:
+**Prefer MCP** — `place_element` collapses finding/creating the empty interaction cell and creating the node into one call, but it does **not** resolve an occupied target column for you: passing an already-occupied `columnIndex` fails outright rather than auto-inserting a column before it (it only auto-extends when `columnIndex` is *past* the current column count — a different situation). **Target column depends on the consumer type**:
+- **SCREEN**: target the screen's own column index. First check whether that column's interaction row is already occupied (e.g. a command/input screen) — `get_node` with `projection: "cells"` on the chapter. If it is, insert a new column immediately before the screen first (`add_column` with `beforeNodeId` set to the screen's own node id), then pass *that* new column's index to `place_element` instead of the screen's original one.
+- **AUTOMATION**: target `consumerColumnIndex - 1` (one column to the *left* of the automation) — never the automation's own column index, since it already holds the COMMAND the automation issues.
 ```
 mcp__eventmodelers__place_element {
   "boardId": "<BOARD_ID>",
   "timelineId": "<CHAPTER_ID>",
   "elementType": "READMODEL",
   "title": "ActiveReservationView",
-  "columnIndex": <consumerScreenOrAutomationColumnIndex>
+  "columnIndex": <consumerScreenColumnIndex>  // or <automationColumnIndex - 1> for an AUTOMATION consumer
 }
 ```
 Then set `meta.fields` (with `mapping`/`generated`/`cardinality`) on the returned node id:
@@ -520,45 +321,17 @@ mcp__eventmodelers__submit_node_events {
   }]
 }
 ```
-To determine the consumer's column index beforehand, or to check whether a specific interaction cell is already occupied (there is no `cellId` filter on `get_nodes` — see the note under "Wire connections" below), fetch the chapter and read its cell map:
+To determine the consumer's column index beforehand, or to check whether a specific interaction cell is already occupied (there is no `cellId` filter on `get_nodes` — see the note under "Wire connections" below), fetch the chapter and read its cell map — `projection: "cells"` returns just `{rows, columns, cells}`, not the whole chapter node:
 ```
-mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
-# → meta.timelineData.rows (find "interaction"/"actor" rows) and meta.timelineData.cells (sparse; absent id = empty)
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>", "projection": "cells" }
+# → rows (find "interaction"/"actor" rows) and cells (sparse; absent id = empty)
 ```
 
-**Fallback (no MCP)** — the full manual sequence:
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 5f — Placing a READMODEL node (full manual sequence)".
 
-1. Find the column where the consumer SCREEN or AUTOMATION lives. Fetch the timeline to get the interaction row ID:
-   ```bash
-   curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-     "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
-   # → timelineData.rows — find the row where type === "interaction"
-   ```
-2. Check if the interaction cell is already occupied (existing COMMAND):
-   ```bash
-   curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=<interactionRowId>-<columnId>" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID"
-   ```
-   If a COMMAND occupies that cell, insert a new column immediately after (`{"index": currentIndex + 1}`) and use that column's ID instead.
-3. `cellId = interactionRow.id + "-" + columnId`
-4. Create the READMODEL:
-   ```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: identifying-outputs" \
-     -H "Content-Type: application/json" \
-     -d '[{
-       "id": "<event-uuid>",
-       "eventType": "node:created",
-       "nodeId": "<node-uuid>",
-       "boardId": "<BOARD_ID>",
-       "timestamp": 1234567890,
-       "chapterId": "<CHAPTER_ID>",
-       "cellId": "<interactionRowId>-<columnId>",
-       "meta": {"type": "READMODEL", "title": "ActiveReservationView", "fields": [...]}
-     }]'
-   ```
+**Pass `autoConnect: false` on every `place_element` / `node:created` call in this step.** Output read-model columns are inserted right next to automation-chain and command columns whose events are *not* the read model's sources — the default auto-connect would wire the new READMODEL to the nearest event on its left, which is exactly the stray-edge cleanup this step has repeatedly generated. Suppress it here and wire every `EVENT → READMODEL` / `READMODEL → SCREEN` / `READMODEL → AUTOMATION` edge explicitly in Step 5h's `set_connections` batch. After the batch, run `validate_model` (`{boardId, chapterId}`) — its `backward-arrows` and `readmodel-sources` findings confirm the wiring is what you intended and no stray edge slipped in.
 
-**For an AUTOMATION** (actor lane, same column as its READMODEL):
+**For an AUTOMATION** (actor lane) — its READMODEL always goes **one column to its left**, never the same column: the automation's own column already holds the COMMAND it issues (interaction row), so the read model can't also live there.
 
 **Prefer MCP** — same `place_element` call with `"elementType": "AUTOMATION"`, then `submit_node_events` for fields, as above.
 
@@ -571,27 +344,26 @@ mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>"
 
 ### Step 5g — Preventing backward arrows (mandatory pre-placement check)
 
-The timeline must always progress left-to-right. A `READMODEL → SCREEN` connection going right-to-left is a layout error.
+The timeline must always progress left-to-right, or downward within the same column. A `READMODEL → SCREEN` connection going right-to-left is a layout error.
 
-The correct layout is: **READMODEL in column N, SCREEN in column N+1** (the screen is always one column to the right of its read model). Before placing each read model, find the view screen it serves and verify the column order:
+The correct layout is: **READMODEL and its (primary) view SCREEN share the same column** — READMODEL in the interaction row, SCREEN in the actor row, a downward connection. The read model only sits in a separate column, immediately **before** the screen's, when the screen's column is already unavailable to it (its interaction row is occupied by something else, e.g. a COMMAND on a command/input screen). If a screen displays more than one read model, only the primary read model shares the screen's column — every additional read model goes further left, never to the right. Before placing each read model, find the view screen it serves and verify the column order:
 
 ```
-For each view screen S that queries this read model:
-  If column(S) <= intended column(READMODEL):
-    → The screen is not to the right of the read model. Fix before placing.
-    Option A: Insert a new column immediately after the read model's column
-              and move screen S there.
-    Use POST /timelines/:tl/columns {"index": N} to insert,
-    then node:changed to update the screen node's cell.
-  If column(S) == intended column(READMODEL) + 1:
-    → Screen is already in the correct column directly to the right. No adjustment needed.
-  If column(S) > intended column(READMODEL) + 1:
-    → Gap between read model and screen. Move the read model to column(S) - 1, or move the screen to column(READMODEL) + 1.
+For each view screen S that queries this read model as its primary read model:
+  If column(S)'s interaction row is free:
+    → Place the READMODEL in column(S) itself (same column as S). No adjustment needed.
+  If column(S)'s interaction row is already occupied:
+    → Insert a new column immediately before column(S) and place the READMODEL there instead.
+    mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "beforeNodeId": "<S's node id>" }
+    (fallback, no MCP: POST /timelines/:tl/columns {"index": N} with N computed by hand),
+    then node:changed to update any node whose cell needs to move.
+  If the read model ends up more than one column away from S with nothing in between:
+    → Gap between read model and screen. Close it: move the read model into column(S) (if free) or column(S) - 1.
 ```
 
-**View screens go in the column immediately to the right of the read model they display** — either because they were placed there in Step 3, or because you move them here now.
+**View screens normally share the column of the (primary) read model they display** — either because they were placed there in Step 3, or because the read model was placed into the screen's own column just now (per the check above). A screen's own position is never moved to resolve a read model placement conflict — when the shared column isn't available, the **read model** gets a new column immediately before the screen's, not the other way around (this preserves the screen's narrative order from Step 3).
 
-**The same rule applies to `EVENT → READMODEL`.** If a later event needs to update data a read model already feeds to a SCREEN, do not connect that later event back into the existing read model — the platform only accepts an `EVENT → READMODEL` backward connection when the read model already has a `READMODEL → AUTOMATION` edge (the todo-list pattern from Step 5b). For any read model feeding a SCREEN, resolve the update the same way Step 5c resolves multi-component screens: place a **new copy of the read model** in (or immediately after) the later event's column, connect the later event forward into that copy, and place a matching copy of the same screen there — same title, updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature. Never link the new copy back to the earlier read model instance.
+**The same rule applies to `EVENT → READMODEL`.** If a later event needs to update data a read model already feeds to a SCREEN, do not connect that later event back into the existing read model — the platform only accepts an `EVENT → READMODEL` backward connection when the read model already has a `READMODEL → AUTOMATION` edge (the todo-list pattern from Step 4b, `eventmodeling-designing-automation-chains`). For any read model feeding a SCREEN, resolve the update the same way Step 5c resolves multi-component screens: place a **new copy of the read model** in (or immediately after) the later event's column, connect the later event forward into that copy, and place a matching copy of the same screen there — same title, updated data, optionally re-marked/highlighted via `html-screen`'s Marks feature. Never link the new copy back to the earlier read model instance.
 
 ### Step 5h — Wire connections after placing each READMODEL (and its SCREEN)
 
@@ -599,43 +371,26 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
 
 1. **EVENT → READMODEL** — find the primary source EVENT node in the swimlane row of the same column.
 
-   **Prefer MCP** — `get_nodes` has no `cellId` filter (only `type`); look up occupancy via the chapter's cell map instead, then connect with the type-checked edge tool (auto-corrects direction, skips duplicates):
+   **Prefer MCP** — `get_nodes` has no `cellId` filter (only `type`); look up occupancy via the chapter's cell map instead (`projection: "cells"`), then connect with the type-checked edge tool (auto-corrects direction, skips duplicates):
    ```
-   mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
-   # → read meta.timelineData.cells["<swimlaneRowId>-<columnId>"] for the occupying node id
+   mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>", "projection": "cells" }
+   # → read cells["<swimlaneRowId>-<columnId>"] for the occupying node id
    mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "source": "<eventNodeId>", "target": "<readmodelNodeId>", "action": "connect" }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=<swimlaneRowId>-<columnId>" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs"
-   ```
-   Connect it:
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
-     -H "Content-Type: application/json" \
-     -d '{"source":"<eventNodeId>","target":"<readmodelNodeId>"}'
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.1 — Wire EVENT → READMODEL".
 
-2. **READMODEL → SCREEN** — connect to the existing SCREEN node in the actor row of the next column (screens are typically already placed from Step 3).
+2. **READMODEL → SCREEN** — connect to the existing SCREEN node in the actor row of the same column (or the column immediately after, only when that column wasn't available to the read model — screens are typically already placed from Step 3).
 
    **Prefer MCP:**
    ```
    mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "source": "<readmodelNodeId>", "target": "<screenNodeId>", "action": "connect" }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
-     -H "Content-Type: application/json" \
-     -d '{"source":"<readmodelNodeId>","target":"<screenNodeId>"}'
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.2 — Wire READMODEL → SCREEN".
 
 3. **READMODEL → AUTOMATION** — if the read model is consumed by an automatic process (scheduler, background job, external trigger), place the AUTOMATION node and connect it:
-   - Place the AUTOMATION in the automation lane, in the column immediately to the right of its read model (same rule as screens).
+   - Place the AUTOMATION in the automation lane, in the column immediately to the right of its read model — unlike a view screen, this is unconditional for automations: the automation's own column always holds the COMMAND it issues, so its read model never shares that column.
    - Then connect:
 
    **Prefer MCP:**
@@ -643,16 +398,12 @@ After `place-element` returns the READMODEL node ID, create the arrows that comp
    mcp__eventmodelers__set_connection { "boardId": "<BOARD_ID>", "source": "<readmodelNodeId>", "target": "<automationNodeId>", "action": "connect" }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
-     -H "Content-Type: application/json" \
-     -d '{"source":"<readmodelNodeId>","target":"<automationNodeId>"}'
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Step 5h.3 — Wire READMODEL → AUTOMATION".
 
 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"`.
 
+If this step is processing more than one read model in the same pass, collect every connection resolved above (across all of them) into one `set_connections` call instead of one `set_connection` per pair — this was the single largest source of individual tool calls in this step. Pass `compact: true` on that call: with `autoConnect: false` set at placement, every edge here is one you're deliberately creating, so a `{connected, existed, removed, notFound, failed, errors}` tally is all you need back — not a row per edge.
+
 4. **Document the reasoning for each connected event** — for every EVENT → READMODEL edge wired in step 1 (including any added later, e.g. via Step 5g's backward-connection exemption or a Step 5c/copy pattern), record why that event feeds this read model: which field(s) it sets or updates, and why. Use one MARKDOWN note per read model, in that read model's own column (same feedback-lane + MARKDOWN mechanics as `eventmodeling-orchestrating-event-modeling`'s "Documenting decisions inline, at any step" / Step 11 — add the chapter's feedback lane first if it doesn't already exist, then place the note at `cellId = "<feedbackLaneId>-<readModelColumnId>"`). Extend the existing note (don't create a second one) when the read model later gains another connected event.
 
    Example body:
@@ -670,133 +421,33 @@ Do not declare Step 5 complete on the strength of the read models you happened t
 
 1. Does it now have an incoming `READMODEL → SCREEN` or `READMODEL → AUTOMATION` connection?
 2. If it's a SCREEN and not connected — 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`). This exemption applies to screens only.
-3. If it's an AUTOMATION and not connected, it is **never** exempt — go back to Step 5b and identify its todo-list read model now.
+3. If it's an AUTOMATION and not connected, it is **never** exempt — this should already be resolved by Step 4b (`eventmodeling-designing-automation-chains`); if it isn't, apply that skill's rules now to identify its todo-list read model.
 4. If a SCREEN is 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.
 5. Does any screen still carry more than one component undivided (a Step 5a/5c miss)? If so, break it apart now per Step 5c before counting it as resolved.
 6. **Re-fetch every READMODEL too** and run the >3-events heuristic (`eventmodeling-orchestrating-event-modeling`) on each one field by field — including read models a MARKDOWN note already justified as a roll-up. A prior note documents one field's irreducible fan-in; it does not exempt the rest of that node's fields from this check. The failure mode this catches: a wide-fan-in field (e.g. live per-copy availability) bundled together with a cheap, low-fan-in identity/fact field (e.g. a title set by 1-2 events) that has nothing to do with the roll-up — that pairing is always two read models, never one, no matter how the note reads.
 7. **Every READMODEL has its event-reasoning MARKDOWN note (Step 5h.4)**, and that note accounts for *every* inbound `EVENT → READMODEL` edge on the node — not just the one from when it was first placed. If a read model gained a connected event later and the note wasn't extended, fix it now rather than carrying the gap forward.
 
+Run `validate_model` (`{boardId, chapterId}`) once as the mechanical half of this pass — its `readmodel-sources` findings list every READMODEL with no inbound EVENT, `screen-collisions` flags any column that ended up with two screens, and `backward-arrows` catches a `READMODEL → SCREEN` that points left. Then do the judgement checks above (blank-form exemptions, the >3-events heuristic, note completeness) that the tool can't make.
+
 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.
 
 ---
 
-For reference, the full markdown structure is:
-
-```markdown
-# Outputs: [Domain Name]
-
-## Read Models Summary
-
-| ReadModel | Purpose | Events | Consumed By |
-|-----------|---------|--------|-------------|
-| OrderStatus | Show order state | OrderCreated, OrderConfirmed | UI, Processor |
-| OrderList | List orders | OrderCreated, OrderCancelled | UI |
-| PaymentStatus | Payment info | OrderConfirmed, PaymentAuthorized | UI, Accounting |
-| Shipment Tracking | Track delivery | OrderShipped, DeliveryConfirmed | UI, Notifications |
-
----
-
-## Detailed Read Models
-
-### ReadModel: OrderStatusView
-
-**Purpose**: Order Status screen displays current order state
-
-**Events subscribed**:
-- OrderCreated
-- OrderConfirmed
-- PaymentAuthorized
-- OrderShipped
-- OrderCancelled
-- DeliveryConfirmed
-
-**Data**:
-```
-{
-  orderId: string
-  customerId: string
-  status: 'Draft' | 'Confirmed' | 'Authorized' | 'Shipped' | 'Delivered' | 'Cancelled'
-  items: Array<{productId, quantity, unitPrice}>
-  total: number
-  shippingAddress: Address
-
-  createdAt: Date
-  confirmedAt: Date
-  paymentId: string
-  paymentMethod: 'card' | 'transfer'
-  authorizedAt: Date
-
-  shipmentId: string
-  carrier: string
-  trackingNumber: string
-  shippedAt: Date
-  estimatedDelivery: Date
-}
-```
-
-**Update Logic**:
-- OrderCreated: Insert with status='Draft'
-- OrderConfirmed: Update status='Confirmed'
-- PaymentAuthorized: Update status='Authorized', set paymentId
-- OrderShipped: Update status='Shipped', set shipmentId, carrier, trackingNumber
-- DeliveryConfirmed: Update status='Delivered'
-- OrderCancelled: Update status='Cancelled'
-
-**Consumed By**:
-- Order Status Screen (displays)
-- Order Processing Processor (checks status)
-- Notification System (sends updates)
-
---- [Repeat for each read model]
-
----
-
-## Data Completeness Check
-
-### Events → UI Needs
-
-Verify all UI needs have event sources:
-
-| UI Need | Event Source | Status |
-|---------|-------------|--------|
-| Order status | OrderConfirmed, OrderShipped |  |
-| Tracking number | OrderShipped |  |
-| Order items | OrderCreated |  |
-| Estimated delivery | OrderShipped |  |
-| Cancellation reason | OrderCancelled |  |
-
-### Missing Data
-
-Identify UI needs without event sources:
-- None identified 
-
----
-
-## Processor Consumption
-
-### Processors and their reads:
-
-| Processor | Reads From | Writes Commands |
-|-----------|-----------|-----------------|
-| Inventory | OrderStatusView (Authorized) | ReserveInventory |
-| Fulfillment | OrderStatusView (InventoryReserved) | CreateShipment |
-| Notification | OrderStatusView (all) | None (info-only) |
-| Accounting | PaymentStatusView | None (reporting) |
-```
+Older versions of this skill wrote the read model catalog as a markdown document rather than placing nodes on the board — that legacy template is kept in `references/examples.md` for reference only; it is not the actual output mechanism.
 
 ## Quality Checklist
 
 ### 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 — verified via the mandatory per-node pass above, not assumed
-- [ ] **Every AUTOMATION from storyboarding is connected to at least one todo-list read model** (via `READMODEL → AUTOMATION`, Step 5b) — no exemption for automations, unlike screens; even a simple relay automation gets one
-- [ ] **No automation's todo list is opened directly by another system's (second-swimlane) EVENT unless that automation is itself the translation automation** (Step 5b) — an automation doing the actual domain work is only ever opened by an internal event; a second-swimlane EVENT feeding straight into a work automation's todo list is a missing translation automation
+- [ ] **Every AUTOMATION from storyboarding is connected to at least one todo-list read model** (via `READMODEL → AUTOMATION`, Step 4b) — no exemption for automations, unlike screens; even a simple relay automation gets one
+- [ ] **No automation's todo list is opened directly by another system's (second-swimlane) EVENT unless that automation is itself the translation automation** (Step 4b) — an automation doing the actual domain work is only ever opened by an internal event; a second-swimlane EVENT feeding straight into a work automation's todo list is a missing translation automation
 - [ ] **No read model is placed without a connected SCREEN or AUTOMATION consumer**
 - [ ] **No read model spans more than one component** — a screen with N distinct components gets N read models and N highlighted screen copies (same screen name, one component crisp per copy), not one screen-wide read model
 - [ ] **Every multi-component screen was broken apart in Step 5c** — each copy keeps the original screen's name, differs only in which component is marked/highlighted
-- [ ] **Every automation's todo-list read model identifies its opening and closing events** (Step 5b) — including the automation's own resulting event as a closing event where applicable, not just the triggering event
+- [ ] **Every automation's todo-list read model identifies its opening and closing events** (Step 4b) — including the automation's own resulting event as a closing event where applicable, not just the triggering event
 - [ ] **A field's genuinely irreducible wide fan-in is documented per-field** (inline MARKDOWN note, per "Documenting decisions inline") — and that note is never treated as clearing every other field on the same read model from the >3-events check; a cheap identity/fact field bundled alongside a wide roll-up field is always split out, never excused by the roll-up's own note
 - [ ] **Every read model has an event-reasoning MARKDOWN note** (Step 5h.4) covering every connected event and which field(s) it sets or updates
 - [ ] Every read model has clear purpose