@milehimikey/em 1.4.0 → 1.6.0

package/.claude/skills/event-modeling/reference/em-dsl.md

@@ -15,10 +15,13 @@ em init [file]                 # scaffold a starter model.em (default: model.em)
 em render <file> -o out.svg    # render (extension picks format: svg, png, pdf)
 em render <file> --emit-dot    # print the Graphviz DOT instead of rendering
 em render <file> --keep-empty-lanes   # keep the API lane even when empty
+em render <file> --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
 em watch  <file> -o out.svg    # re-render on every save (file-based)
 em watch  <file> -o out.svg --serve   # + localhost live viewer, instant SSE push-reload (--port N)
 em validate <file>             # check event-modeling rules; exit 0 if only warnings/clean
 em validate <file> --list-issues       # print only open `issue "..."` clauses (slice, element, line, text)
+em validate <file> --list-divergences  # print only `divergence "..."` clauses (slice, element, line, text)
+em validate <file> --list-public       # print only events marked `public` (slice, name, line)
 em validate <file> --fail-on-issues    # opt-in CI gate: exit non-zero while any issue remains open
 ```
 
@@ -35,7 +38,7 @@ model "Name"                     # diagram title
 persona Name                     # a UI swimlane row (actor)
 context Name                     # an event swimlane row (bounded context / aggregate)
 
-slice "Name" {                   # one vertical time step (a column)
+slice "Name" [source "url"] {    # one vertical time step (a column); source is optional
   ui   Free Text @Persona        # screen; @Persona picks its row (defaults to first/"User")
   command Free Text              # state-changing request (API band)
   view Free Text from "Event A", "Event B"   # read model fed by event(s)
@@ -45,16 +48,18 @@ slice "Name" {                   # one vertical time step (a column)
 }
 
 arrow From Element -> To Element    # explicit cross-slice edge (overrides inferred flow)
+
+type Name { field: Type, ... }      # named structured type, reusable from any field (see Named types)
 ```
 
 ### Element kinds (8 keywords, nothing else)
 | Keyword | Band | Meaning | Tag | Extra clauses |
 |---|---|---|---|---|
-| `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `{ fields }` |
-| `command` | API | state-changing request | — | `note`, `issue`, `{ fields }` |
-| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `{ fields }` |
-| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `{ fields }` |
-| `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `{ fields }` |
+| `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
+| `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `{ fields }` |
+| `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `{ fields }` |
+| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `{ fields }` |
+| `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }` |
 
 ### Clauses
 - **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a row.
@@ -64,9 +69,10 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
 - **`again`** (views only): `view <Name> again [from "Event", …]` declares a later instance of an
   already-declared read model — the forward-only device for a view that evolves as later events
   land. Instances are ONE logical view: the first declaration owns the `note` binding; each
-  instance's `from` lists only the NEW events landing at that point (not cumulative); instances are
-  linked left-to-right with a continuity arrow; a reaction (`from "View"`) reads the nearest
-  instance at-or-before its own slice. `again` with no earlier declaration is a validation error.
+  instance's `from` lists only the NEW events landing at that point (not cumulative); a reaction
+  (`from "View"`) reads the nearest instance at-or-before its own slice. Instances are NEVER
+  connected to one another — continuity is implied by the shared name, and the events reaching each
+  instance are what show the view changing. `again` with no earlier declaration is a validation error.
   Use `again` (not a plain repeated `view` name) whenever the view is referenced by a
   `from`/`arrow` — plain repeats are only warning-free while unreferenced.
 - **`note "path.md"`** on ANY element links a markdown doc. Relative to the `.em` file. Renders as
@@ -76,10 +82,49 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
   on one element) plus a legend entry; `em validate` warns on every open issue. **Prefer this
   over a `# TBD` comment for anything that should show up on the rendered diagram** — `# TBD` is
   invisible once rendered, `issue` isn't.
+- **`divergence "text"`** on ANY element records a reasoned, ratified deviation between this
+  element and its implementation — the *resolved* sibling of `issue` (lint-suppression-with-
+  rationale for the `conform` phase). Renders as a teal corner marker (bottom-right — distinct
+  from `note`'s top-right and `issue`'s top-left, so all three can coexist) plus a legend entry.
+  Raises **no** `em validate` warning by design; use `--list-divergences` to audit. `em diff
+  --json` carries it forward as `acceptedDivergence` on the affected change/removal entry, so
+  `conform` can cite an already-ratified deviation instead of re-flagging it as drift every run.
+- **`public`** (events only): marks this event as part of the published integration surface
+  (e.g. an AsyncAPI contract), as opposed to an internal-only fact. Plain structural flag, no
+  free text and no diagram marker (same posture as `again`). Write it as the last token on the
+  line, optionally right before a trailing `@Context` — `event X @Context public` or
+  `event X public @Context` both work. `em export` carries it as `public: true`/`false`;
+  `em diff` reports a flip as `event marked public`/`event unmarked public`;
+  `em validate --list-public` audits which events are public.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
-  one-per-line. Types are free text (no semantic checking). Keep these light; full field specs
-  with rules live in the slice doc.
+  one-per-line. Types are free text (no semantic checking) UNLESS the type string names a
+  declared `type` (see Named types below), in which case it resolves to a structured
+  reference. Keep these light; full field specs with rules live in the slice doc.
 - **Comments:** `# ...` anywhere outside quotes (full-line or trailing).
+- **`source "url"` on a slice header** (the only slice-level clause — everything above is
+  per-element) links the slice back to the ticket/conversation it traces to, e.g.
+  `slice "Checkout" source "https://linear.app/team/issue/MIL-60" { ... }`. Exports as
+  `model.slices[].source` via `em export`, so an intake loop stays machine-traversable instead
+  of relying on prose. Purely metadata — no visual marker, not validated. Don't confuse it with
+  an element's `note "path.md"` (a markdown file link, not a URL).
+
+### Named types
+
+`type Name { field: Type, ... }` declares a reusable structured shape at the top level (any
+order relative to `persona`/`context`/`slice`, no clauses). Reference it from any field
+anywhere — bare (`winner: QuoteAcceptedLine`) for a nested object, `Name[]` for an array
+(`lines: QuoteAcceptedLine[]`). Resolution is opportunistic: a type string only becomes a
+structured reference when it names a declared type (case/whitespace-insensitive match); every
+other type string stays free text exactly as before, so declaring no `type` blocks changes
+nothing. Recursion between declared types is allowed as a DAG (e.g. a diamond shape like
+`Order` referencing `Address` twice) — a bare/singular self- or mutual-cycle
+(`type Node { child: Node }`) is a validation error, but the same shape through an array
+(`type Node { children: Node[] }`) is legal since the array can terminate at runtime; this is
+how tree/recursive data (categories, org charts, comment threads, BOMs) gets expressed.
+`em export` lists every declared type under `model.types[]` (stable `ref`, e.g.
+`types/quote-accepted-line`) and adds an additive `typeRef` key to every field (declared-type
+fields and ordinary element fields alike) — `{ name, ref, array }` when resolved, `null`
+otherwise. `em diff` tracks types added/removed and field changes on surviving types.
 
 ### Swimlane band order (top → bottom)
 Header row → **Automation** (only if used) → **persona** rows (in declared order) → **API**
@@ -106,7 +151,7 @@ slice "Open Orders" {
   ui Order List @Customer
 }
 
-# 3. Automation: split across TWO slices
+# 3. Automation: split across TWO slices (plus the read slice that consumes the event)
 slice "Orders To Fulfill" {
   view Orders To Fulfill from "Order Placed"
   processor Fulfillment Service
@@ -115,8 +160,12 @@ slice "Ship Order" {            # the triggered command goes in the NEXT slice
   command Ship Order
   event Order Shipped @Shipping
 }
+slice "Open Orders — shipped" {
+  view Open Orders again from "Order Shipped"   # every event needs a reader
+  ui Order List @Customer                       # ...and every read model needs a consumer
+}
 
-# 4a. Translation (external trigger): external input -> translation -> command -> event
+# 4a. Translation (external trigger, no durable artifact): external call -> translation -> command -> event
 slice "Carrier Webhook" {
   translation Carrier Adapter         # inbound from outside the model; no internal `from`
 }
@@ -124,8 +173,36 @@ slice "Confirm Delivery" {            # the triggered command goes in the NEXT s
   command Confirm Delivery
   event Delivery Confirmed @Shipping
 }
+slice "Open Orders — delivered" {
+  view Open Orders again from "Delivery Confirmed"
+  ui Order List @Customer
+}
+
+# 4b. Translation (external trigger, durable artifact): persisted inbound queue -> translation -> command -> event
+slice "Receive Carrier Event" {           # ingest: persist the raw webhook before reacting to it
+  ui Webhook Endpoint @Carrier
+  command Receive Carrier Event
+  event Carrier Event Received @Shipping  # scoped to @Shipping's fact, not the @Carrier caller
+}
+slice "Inbound Carrier Events" {
+  view Inbound Carrier Events from "Carrier Event Received"   # the persisted inbound queue
+  translation Carrier Adapter
+}
+slice "Acknowledge Carrier Event" {
+  command Acknowledge Carrier Event
+  event Carrier Event Acknowledged @Shipping
+}
+slice "Inbound Carrier Events — processed" {
+  view Inbound Carrier Events again from "Carrier Event Acknowledged"
+  ui Delivery Board @Ops
+}
 
-# 4b. Translation (internal trigger): read model -> translation -> command -> event
+# 4c. Translation (internal trigger, durable artifact): read model -> translation -> command -> event
+slice "Accept Quote" {
+  ui Quote Screen @Customer     # every command needs a trigger: a ui, or a reaction before it
+  command Accept Quote
+  event Quote Accepted @Quote
+}
 slice "Quotes To Sync" {
   view Accepted Quotes from "Quote Accepted"
   translation CRM Sync                # reacts to our own state via the read model in this slice
@@ -134,40 +211,79 @@ slice "Record Sync" {
   command Record Crm Sync
   event Quote Synced @Quote
 }
+slice "Accepted Quotes — synced" {
+  view Accepted Quotes again from "Quote Synced"
+  ui Sync Status @Customer
+}
 ```
 
+Trigger source (external/internal) and durable artifact (`view`-backed or not) are independent
+axes — 4a and 4b are both "externally triggered" but only 4b has a queue, and a `view`-backed
+translation reacts the same whether the view was filled by an outside system (4b) or the model's
+own event (4c). An inbound message earns `event` status the same way any event does: scope it to
+the context/lane whose fact it represents (e.g. `Carrier Event Received @Shipping` or its own
+`Carrier` context), not by who committed it — that keeps it a legitimate boundary fact (à la an
+Anti-Corruption-Layer event in DDD) instead of a technical artifact leaking foreign vocabulary
+into the model.
+
 A `translation` (like a `processor`) is a **reaction**: it triggers a command and never carries an
 `event` in its own slice. Same two-slice split as the Automation pattern above.
 
-### Headless / API systems (no UI) & repeated read models
+Note the read slice closing each pattern: **every event must be read by some read model**
+(warning 4 below). A command slice is not finished until the slice that projects its event
+exists. Reactions don't count — they read *views*, not events.
+
+### Headless / API systems & repeated read models
 
-When the system is headless (no UI — clients call an API), drop `ui`/`persona` entirely:
+A headless system (no screens — clients call an API) still uses `ui`/`persona`: a slice **is**
+trigger → command → event, read vertically, so the trigger belongs *in* the slice, never split into
+one of its own. Declare a persona per external caller/role and treat its `ui` boxes as API calls
+instead of shipped screens — same two patterns (State Change, State View) as any other slice, no new
+shape:
 
 ```em
-# Write: external translation -> command -> event (name the inbound adapter for the caller/role)
-slice "Create Quote (request)" { translation SalesRep BU Create Quote }
-slice "Create Quote"           { command Create Quote  event QuoteCreated @Quote }
+persona IntegratorAPI   # API-flagged lane: its `ui` boxes are API calls, not shipped screens
 
-# Read: event(s) -> read model -> READ translation (the external caller's API query, replaces UI)
-slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation SalesRep BU Read Quote }
+slice "Create Quote" {
+  ui Create Quote @IntegratorAPI
+  command Create Quote
+  event QuoteCreated @Quote
+}
+
+slice "Read Quote — created" {
+  view Quote from "QuoteCreated"
+  ui Read Quote @IntegratorAPI
+}
 ```
 
-- A **read translation triggers no command** (it returns data outbound) — it is the headless analog
-  of `view → ui`, *not* a reaction. Only *reaction* translations/processors trigger commands. A read
-  slice has no `command` and no `event`, so `em validate` stays quiet about it.
-- **Repeat the read model** in every slice where it's read so the timeline flows left-to-right.
-  Recurring `view`/`translation` names **render cleanly and stay warning-free** as long as nothing
-  references the repeated name via `from`/`arrow` (the duplicate-name warning fires only for a
-  *referenced* duplicate, resolving to the first). **Wire each event to a read model exactly once:**
-  a repeated instance's `from` lists only the **new** events since the previous instance (not
-  cumulative), or the event draws a duplicate arrow to the same read model at every repeat. (An
-  event may still feed several *different* read models, once each.) When a repeated view **must be
-  referenced** — e.g. a reaction reads it via `from` — declare its later instances with
-  `view X again` instead (see Clauses); instances resolve properly and draw continuity arrows.
+- **`translation` stays reserved for genuine reactions and real external-system boundaries** — an
+  internal automation, or a webhook/adapter crossing into another system (see the Automation and
+  4a/4b/4c Translation examples above, unchanged). It is **not** how you model a synchronous
+  request/response API call — that's Pattern 1 (State Change) with an API persona, exactly like the
+  `Create Quote` slice above.
+- **Internal-only commands and views (no public route) carry no `ui` at all.** They follow the
+  ordinary Automation pattern already documented: the reaction sits in the previous slice, and an
+  internal-only read model is consumed by that reaction, not by a screen or an API query.
+- **Repeat the read model** in every slice where it's read so the timeline flows left-to-right, and
+  **prefer `view X again`** for every instance after the first (see Clauses) — **each instance
+  carries its own consumer** (the `ui` that reads it, or a reaction), not just the last one. `again`
+  instances are exempt from the duplicate-name warning even when referenced, and each reference
+  resolves to the right instance — a plain repeat only stays warning-free while nothing references it by name, and
+  resolves to the *first* declaration when something does. **Wire each event to a read model exactly
+  once:** a repeated instance's `from` lists only the **new** events since the previous instance
+  (not cumulative), or the event draws a duplicate arrow to the same read model at every repeat. (An
+  event may still feed several *different* read models, once each.)
+- **Instances are never joined to one another.** No arrow between two instances of one read model,
+  ever — an explicit one is a validation error. The repeat is a timeline device: continuity is
+  implied by the shared name, and the events arriving at each instance are what show it changing.
 - **Keep arrows span-1: put each repeat right after its feeding event.** Place a read-model instance
-  immediately after the event that updates it, sourcing only that single adjacent event. A read
-  model far from its source events draws long arrows that cross the read-model row and read as
-  read→read (an Event Modeling violation) — repeat the read model next to each event instead.
+  immediately after the event that updates it, sourcing only that single adjacent event. The
+  renderer routes a long arrow *around* intervening boxes rather than through them, so it no longer
+  reads as a forbidden read→read link — but distance is still a real problem: the arrowhead lands
+  columns away from the event that produced it, so **the write slice reads as dangling**, as if
+  nothing consumed its event. You have to trace a line across the diagram to see the connection.
+  Keep the read model adjacent to its event, and keep a sub-flow that detours into another context
+  together rather than parking it at the end of the model.
 
 ### Slice-ordering gotchas (edge inference)
 
@@ -175,12 +291,17 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 - A **reaction** (`processor`/`translation` that triggers a command) wires to the command in the
   **immediately next** slice. So a reaction slice must be *directly* followed by its command slice —
   don't insert a read slice between them.
-- A **read** slice (read model → read translation, no command) must **not** be immediately followed
-  by a `command` slice, or the read translation will be mis-wired to that command. Put reads after a
-  command+event slice, or before another read / a reaction / an inbound `(request)` slice.
+- A read slice whose consumer is a **reaction** (`view` + `processor`/`translation`, no command in
+  the same slice) must **not** be immediately followed by a `command` slice, or the reaction will be
+  mis-wired to that command. Put it after a command+event slice, or before another read/reaction
+  slice instead. (A `ui`-consumed read slice has no such risk — `ui` never wires as a reaction.)
 - A read model fed by an early event (e.g. a queue or to-do view) can't always sit directly after
   its source event when a reaction must immediately precede its command slice — placing the read
   later, in narrative order with a longer arrow, is the correct trade-off, not something to force-fix.
+- A `ui` never triggers a reaction — no pattern has a `ui` wired to `processor`/`automation`/
+  `saga`/`translation`, only to `command`. A `ui` left in the reaction's own slice (instead of the
+  read-model or command slice) renders with no outgoing edge, disconnected, and `em validate` now
+  warns on it.
 
 ---
 
@@ -197,27 +318,68 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
    there), a reaction reading a view before any instance of it exists, or an explicit backward
    `arrow`.
 6. **`again` without an earlier declaration** — declare the view plainly the first time it appears.
+7. **Illegal connection** — an `arrow` joining kinds the patterns don't connect. Only
+   `ui -> command`, `command -> event`, `event -> view`, `view -> ui`, `view -> reaction`, and
+   `reaction -> command` are allowed. A command straight to a view is the CQRS violation (an event
+   has to sit between them); a view straight to a command needs a reaction between them; and two
+   instances of one view are never connected at all. Inferred edges are always legal, so this only
+   ever fires on a hand-written `arrow`.
+8. **Cyclic type reference** — a declared `type` nesting itself with no array to terminate it
+   (`type Node { child: Node }`, or the same shape across several types). Break the cycle, or
+   route the self/mutual reference through an array (`children: Node[]`) if the data is
+   genuinely tree-shaped.
 
 **Warnings (should fix):**
 1. **Automation/translation shares slice with its command** — both `automation`/`processor` and
    `translation` are reactions; put the triggered command in the *next* slice.
-2. **Command without event** — every command should record at least one event.
-3. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
-4. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
-5. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
+2. **`ui` shares slice with a reaction, no command** — a `ui` only ever wires to a `command`; no
+   pattern has a `ui` triggering an automation/processor/saga/translation. Left in the reaction's
+   own slice it renders disconnected, with no edge. Move it to the read-model slice, or to the
+   slice with the command this eventually triggers.
+3. **Command with no trigger** — nothing issues it. A command needs a `ui` in its slice, or a
+   reaction (automation/processor/saga/translation) in the slice *before* it. The input-side mirror
+   of (5): a command nothing points at is a write nobody can start.
+4. **Command without event** — every command should record at least one event.
+5. **Event nobody reads** — the mirror of (4): recording an event no read model projects is a
+   write with no reader. Follow every write slice with the read slice that consumes its event.
+   Counts as read when a `view` names it in `from` (any `again` instance will do), when a
+   fieldless-`from` view sits in its slice, or via an explicit `event -> view` arrow.
+6. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
+7. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
+   (A duplicate `type` name always warns, unlike a duplicate element name — there's no
+   legitimate unreferenced-duplicate case for a named type.)
+8. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
    clause. `em validate --list-issues` prints just these; `--fail-on-issues` (opt-in) makes CI
    fail while any remain open.
-6. **View field with no source** — a `view` field whose name matches no field on any instance
+9. **View field with no source** — a `view` field whose name matches no field on any instance
    of its source events. Only checked once BOTH the view and at least one source event declare
    `{ fields }`.
-7. **Event field not from a command** — an `event` field whose name matches no field on any
-   command in the same slice. Only checked once BOTH the event and at least one same-slice
-   command declare `{ fields }`. This is the payoff of the fields feature for slicing rigor:
-   once fields are written down, `em validate` checks that data flows forward consistently.
+10. **Event field not from a command** — an `event` field whose name matches no field on any
+    command in the same slice. Only checked once BOTH the event and at least one same-slice
+    command declare `{ fields }`. This is the payoff of the fields feature for slicing rigor:
+    once fields are written down, `em validate` checks that data flows forward consistently.
+
+`divergence "text"` is deliberately NOT in this list — it raises no warning at all, since it
+records a deviation already reasoned through and accepted, not something to fix. Use
+`em validate --list-divergences` to audit them on demand.
 
 **Design rules that keep models valid:**
 - One element per band per slice (multiple personas/contexts are fine — they're different rows).
 - Every `command` slice includes its `event`. Every `view` has a `from` source.
+- **Every `command` has a trigger.** A `ui` in its slice, or a reaction in the slice *before* it.
+  A command nothing points at is a write nobody can start.
+- **Every `event` has a reader.** A command slice isn't finished until the read slice that projects
+  its event exists. Reactions don't count — they read views, not events. Pair each write slice with
+  its read slice as you go rather than sweeping up dangling events at the end.
+- **Every `view` has a consumer.** A `ui` in its slice, a reaction watching it, or (headless) a read
+  translation. Every *instance* of a repeat, not just the last — a bare `view X again` slice is a
+  half-slice, not a State View.
+- **Only six connections are legal**, and only these are ever inferred:
+  `ui → command`, `command → event`, `event → view`, `view → ui`, `view → reaction`,
+  `reaction → command`. Anything else in an explicit `arrow` is an error — above all
+  `command → view` (the CQRS violation: an event has to sit between them) and `view → command`
+  (a reaction has to sit between them). If you reach for an arrow the patterns don't allow, the
+  model is missing an element, not an arrow.
 - Automations **and translations** are always two slices: the reaction (plus its read model, if
   internally triggered) in one slice, the triggered `command` + its `event` in the next. A
   translation/automation slice **never contains an `event`** — reactions trigger commands, not

package/.claude/skills/event-modeling/reference/extract.md

@@ -58,6 +58,15 @@ Mixed systems happen: pick the dominant mode, note the exception areas in the st
   implies several events. Apply the event filter hard here — procedural systems are where
   derived values and activity records masquerade as facts.
 
+Before minting a new candidate event/command/view name, check whether sibling `.em` models
+already exist in the repo. If they do, run `em glossary <this-model>.em <sibling>.em ...` (or
+`--json` it) as a fuzzy-name-matching aid: it surfaces the same normalized term used with a
+different kind or a different field type across models. A hit there usually means the
+extracted system already has an established name/kind elsewhere — prefer that over minting a
+near-duplicate synonym (e.g. "Order Confirmed" vs. an existing "Order Confirmation"). This is
+informational judgment, not a gate: `em glossary` only flags conflicts, it doesn't resolve
+them.
+
 ## The confirm-and-clarify loop (~7 rounds)
 
 One concern per round. After every round: mirror what you extracted back to the user, update
@@ -67,13 +76,20 @@ it is fine to finish a round with `# TBD`s still parked.
 - **R1 — Candidate events.** Extract (event-driven) or synthesize (procedural) the past-tense
   facts; apply the event test; user confirms/renames/rejects. Ambiguous candidates → `# TBD`.
 - **R2 — Timeline order.** Order the confirmed events into the as-is narrative. Identify the
-  *actual* actors/callers and the *real* UI or API surfaces (headless systems: no
-  `ui`/`persona` — use write/read translations per `em-dsl.md`). **First `em render` here.**
+  *actual* actors/callers and the *real* UI or API surfaces (headless systems: still `ui`/`persona`
+  — one persona per caller/role, its `ui` boxes are the API calls, per `em-dsl.md`). **First
+  `em render` here.**
 - **R3 — Commands / inputs.** For each event, the request that actually produces it today
-  (imperative name). Unclear trigger → `# TBD`, not a plausible guess.
+  (imperative name), *and what triggers it* — the real screen, or the scheduler/listener that
+  fires it (model that as a reaction in the preceding slice, per R5). Unclear trigger → `# TBD`,
+  not a plausible guess; expect a *command has nothing that triggers it* warning until R5 fills
+  it in, and don't invent a screen to silence it.
 - **R4 — Read models / outputs.** The projections/queries the system actually serves; wire
-  `from "Event"` (repeat read models span-1 per `em-dsl.md`). **Start running `em validate`**
-  each round from here.
+  `from "Event"` (repeat read models span-1 per `em-dsl.md`, using `view X again` after the
+  first). **Start running `em validate`** each round from here. Expect *event is not read by any
+  read model* warnings: real systems do record fire-and-forget events. In an as-is model that is
+  a **finding about the system**, not a modelling mistake — never invent a reader to silence it
+  (that would be desired state). Park it in the Decisions log and carry the warning.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
   listeners, outbound syncs, inbound webhooks. Model each as a reaction with the two-slice
   `reaction → command → event` split and the slice-ordering rules in `em-dsl.md` — even when
@@ -103,8 +119,9 @@ one for a sprawling one. Record any deviation in the Decisions log.
 ## Completion & handoff
 
 Extraction is complete when: the model renders; `em validate` is clean (or remaining warnings
-are consciously accepted in the Decisions log); every unknown is a parked `# TBD`; and the
-user has confirmed the model reflects today's behavior. Then:
+are consciously accepted in the Decisions log — unread events in an as-is model are the usual
+accepted case, and each one is worth naming explicitly as a finding); every unknown is a parked
+`# TBD`; and the user has confirmed the model reflects today's behavior. Then:
 
 1. State file: set phase progress (extraction rounds checked), log the completion decision.
    Seed `README.md`'s **slice index** (every slice, pattern, status `none`).