@milehimikey/em 1.5.0 → 1.6.1

package/.claude/skills/event-modeling/SKILL.md

@@ -42,11 +42,14 @@ validation rules) before doing real work — they are the source of truth. Templ
   and show the user what changed. Encourage running the live view (`watch`) so a team can follow.
 - **Keep the `.em` structural; put depth in `note` docs.** The diagram holds flow; invariants,
   fields, and scenarios live in `slices/*.md` linked via `note "slices/<name>.md"`.
-- **No UI in headless/API models.** If the system is headless (clients call an API, not screens),
-  use no `ui`/`persona`: writes are `external translation → command → event` (name the inbound
-  adapter for the caller/role); reads are `read model → read translation` (an API query that
-  triggers **no** command — the analog of `view → ui`). **Repeat read models** across slices so the
-  timeline flows left-to-right — put each repeat **right after the event that feeds it**, sourcing
+- **Headless/API models still use `ui`.** If the system is headless (clients call an API, not
+  screens), declare a persona per external caller/role (e.g. `IntegratorAPI`) and treat its `ui`
+  boxes as API calls, not screens: writes are `ui → command → event` and reads are
+  `read model → ui`, exactly like any other State Change/State View slice — no separate trigger
+  slice. `translation` stays reserved for genuine reactions and real external-system boundaries,
+  not a synchronous request/response call. Internal-only commands/views with no public route carry
+  no `ui` at all — they follow the ordinary Automation pattern instead. **Repeat read models**
+  across slices so the timeline flows left-to-right — put each repeat **right after the event that feeds it**, sourcing
   only that one adjacent event, so every arrow is short (a read model far from its source events
   draws a long arrow whose head lands columns away, making the *write* slice read as dangling —
   keep a sub-flow that detours into another context together, not parked at the end of the model).
@@ -74,7 +77,11 @@ validation rules) before doing real work — they are the source of truth. Templ
   above all `command → read model` (the CQRS violation) or `read model → command` — means the model
   is missing an **element**, not an arrow.
 - **Validate continuously.** Run `em validate` and fix errors/warnings as you go (see DSL ref).
-- **Save state at the end of every session** so work resumes cleanly.
+- **Save state at the end of every session** so work resumes cleanly. Also append one line to
+  the Usage log: the phase(s) touched and the `em validate` diagnostic *categories* that fired
+  (rule name only, e.g. "read model nothing consumes" — never the full message or domain
+  content). This is the team's only usage signal today (`docs/usage-data.md`) — keep it cheap
+  and habitual, not a task to skip.
 
 ## Preconditions (run first)
 
@@ -133,9 +140,9 @@ phase applies to field tables, below.
    they aren't re-proposed later. Capture the survivors as a flat list.
 2. **Plot / storyboard (step 2).** Order the events into the narrative. Identify **personas**
    (actors) and the **UI** screens at each step. Add `persona` declarations and `ui` elements.
-   In a **headless/API** model there are no personas or screens — identify the external
-   **callers** at each step instead; they become the inbound write translations and read
-   translations (see `reference/methodology.md`).
+   In a **headless/API** model there are no human personas or screens — identify the external
+   **callers** at each step instead; declare one persona per caller/role, and its `ui` boxes are
+   the API calls (see `reference/methodology.md`).
 3. **Inputs (step 3).** For each event, find the **command** that causes it (imperative name).
    Form `command → event` slices (State Change pattern). Every command needs a **trigger** in the
    same breath: the screen the user issues it from (a `ui` in the slice), or — for the Automation
@@ -143,10 +150,10 @@ phase applies to field tables, below.
    a write nobody can start. *"Who does this, and where are they when they do it?"*
 4. **Outputs (step 4).** Identify the **read models / views** consumers need and wire them with
    `from "Event"` (State View pattern), each with the screen (or reaction) that consumes it — a
-   read model nothing displays is information dropped on the floor. In a **headless/API** model there is no UI — a read model is
-   consumed by an **external read translation** (the API query, triggers no command), and read
-   models are **repeated** in each slice where they're read (use `view X again` after the first) so
-   the timeline flows (see `reference/methodology.md`).
+   read model nothing displays is information dropped on the floor. In a **headless/API** model
+   the consumer is the caller persona's `ui` (the API query) — same as any screen. Read models are
+   **repeated** in each slice where they're read (use `view X again` after the first, each instance
+   with its own consumer) so the timeline flows (see `reference/methodology.md`).
    **Close the loop before leaving this step:** every event from step 3 must be read by at least one
    read model. Walk the event list and ask, for each one, *"who looks at this, and what do they do
    with it?"* An event with no answer is either missing its read model or shouldn't be recorded —
@@ -230,12 +237,16 @@ For each slice:
    already defined elsewhere.
 2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name). Record the originating
    need (ticket/conversation link) in the Intent section when one exists.
-3. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
+3. Render the slice's own diagram: `em render <model>.em --slice "<slice name>" -o
+   slices/<slice-name>.svg` (kebab-case, matching the doc's filename) — redraws just this slice
+   in its own canonical pattern shape, and add `![Diagram](./<slice-name>.svg)` near the top of
+   the doc, right after the metadata bullet list.
+4. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
    (the command for State Change, the view for State View, the processor for Automation, the
    translation for Translation).
-4. Update `README.md`'s slice index — the one canonical slice table (`draft` →
+5. Update `README.md`'s slice index — the one canonical slice table (`draft` →
    `ready-to-implement`, later `implemented` once shipped, with `Implemented in:` filled in).
-5. Re-render and `em validate`.
+6. Re-render and `em validate`.
 
 ## Phase: `conform` — drift check against the codebase
 
@@ -273,6 +284,37 @@ appear the moment you save, with no idle churn between edits.
 `live.html?svg=<model-name>.svg` in a browser. It polls every ~2s and reloads without flicker. No
 editing of `live.html` is needed — the `?svg=` query picks the model.
 
+## Phase: `review` — stakeholder walkthrough
+
+Goal: step a real stakeholder review session through the model slice by slice, one slice
+spotlighted at a time, with any open questions the room raises captured live as `issue "..."`
+red notes.
+
+**Trigger: a real stakeholder review session is on the calendar — a scheduled use, not
+speculation.** Don't propose this phase proactively; it exists for facilitated reviews with
+non-engineer stakeholders in the room, not routine model editing.
+
+Start the same live server as `watch`: `em watch <model-name>.em -o <model-name>.svg --serve`
+(run_in_background). Open the printed URL, click **Review mode** in the header, and share the
+screen. Use Prev/Next (or the left/right arrow keys) to step through slices in declaration
+order — each one pans/zooms into view with everything else dimmed, so the room's attention
+tracks one slice at a time.
+
+**Live capture:** when a stakeholder raises something unresolved, add `issue "..."` to the
+relevant element in the `.em` file and save — exactly the same mechanism as any other issue
+(see `validate` below). The browser updates over the existing SSE push within moments, without
+losing the current slice or resetting review mode.
+
+Wrap-up: run `em validate --list-issues` to sweep everything captured during the session and
+walk each one with the user, same as any open issue. Update the state file's Participants
+section with who attended, and set a `Last stakeholder review:` marker (mirrors `Last
+conformance:`).
+
+End of phase: state file's `Last stakeholder review:` marker updated, every issue captured
+live triaged (resolved on the spot, moved to Open questions / parking lot, or left open on
+purpose). Review doesn't chain to another phase — it's a recurring, scheduled activity like
+`conform`, not a step in the discover → model → slice sequence.
+
 ## Phase: `validate`
 
 Run `em validate <model-name>.em` and walk through each diagnostic with the user, explaining the
@@ -310,9 +352,12 @@ em init <name>.em                          # optional starter scaffold
 em validate <name>.em                      # check rules; exit 0 if clean/warnings only
 em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
 em render <name>.em --emit-dot             # inspect generated Graphviz DOT
+em render <name>.em --slice "<slice-name>" -o slices/<slug>.svg   # this slice's own diagram
 em watch <name>.em -o <name>.svg           # re-render on save (run in background)
 em watch <name>.em -o <name>.svg --serve   # + live viewer with instant push-reload (--port N)
+                                            #   click "Review mode" for a slice-by-slice storyboard walkthrough
 ```
 
 Always finish a working session by: re-rendering, running `em validate`, and updating
-`.event-modeling.md` with the current phase/step, decisions, and open questions.
+`.event-modeling.md` with the current phase/step, decisions, open questions, and a Usage log
+entry (phases touched + validate diagnostic categories hit).

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

@@ -102,7 +102,16 @@ For each slice in scope:
      materialized projection in code — a direct event handler with criteria-sourced state is
      the same pattern expressed in the code idiom (extract.md's R5 reaction rules). That is
      NOT structural drift; note the idiom in the evidence log instead of reporting the view
-     as missing.
+     as missing. This is the *general*, idiom-level version of the next bullet — prefer citing
+     an actual `divergence` annotation when the element carries one; fall back to this idiom
+     note only when it doesn't.
+   - **Accepted divergences:** before treating any finding as drift, check whether the
+     relevant canonical element already carries a `divergence "..."` annotation (visible in
+     the `.em`, in `em export --json`'s `divergence` field, or — for a structural finding — as
+     the `acceptedDivergence` field already attached to that `em diff --json` entry, see step
+     3). If it does, this is not a fresh finding to litigate: classify it as **Accepted
+     divergence** (step 4) and cite the annotation text as the evidence. This is the specific,
+     per-element, ratified counterpart to the idiom-level bullet above.
 3. Write what you found into the scratch model (`<model-name>-asis.em`, see below). **Seed the
    scratch model as a copy of the canonical `.em` and replace only the in-scope slices** with
    the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
@@ -112,9 +121,13 @@ For each slice in scope:
    this phase exists to avoid. It also keeps the scratch model compilable (see step 3). Within
    the slices you do rewrite, **reuse the canonical model's slice and element names wherever
    the code genuinely matches them** — the canonical model is the vocabulary anchor. Give a
-   new name only to code behavior the model doesn't cover at all. Record the mapping decision
-   for every element you name this way (e.g. `CartItemAdded` code class ↔ `"Cart Item Added"`
-   model event) so it's auditable, not a silent judgment call. **Match the canonical model's field granularity:** declare `{ fields }`
+   new name only to code behavior the model doesn't cover at all. When you do need a new name,
+   check `em glossary` across sibling `.em` models first (same aid the `extract` phase uses) —
+   if the term already exists elsewhere under a different kind or spelling, that's a signal to
+   reuse the established name rather than mint another synonym for the same concept. Record the
+   mapping decision for every element you name this way (e.g. `CartItemAdded` code class ↔
+   `"Cart Item Added"` model event) so it's auditable, not a silent judgment call. **Match the
+   canonical model's field granularity:** declare `{ fields }`
    in the scratch model only where the canonical model declares them (if the canonical model
    puts fields on commands but not events, so does the scratch model — writing code-derived
    event fields there would flood the diff with `field-added` noise). Schema claims at finer
@@ -147,7 +160,10 @@ Then run `em diff <model-name>.em <model-name>-asis.em --json`. `em`, not you, d
 structurally differs — don't re-derive by eye what the tool already computed. Parse the JSON
 (`docs/cli.md`'s diff section documents the envelope: `diffSchemaVersion`, `counts`, `changes`,
 `removals`, every optional `ChangeEntry` field explicit-`null` when unused) and use it as the
-structural-surface findings directly.
+structural-surface findings directly. Check each entry's `acceptedDivergence` field first: a
+non-null value means `em` itself already found a `divergence` annotation on the canonical
+element behind this entry — that finding is Accepted divergence (step 4), not something to
+re-litigate.
 
 ### 4. Classify
 
@@ -157,6 +173,11 @@ step 2 — sorts into exactly one class:
 - **Real drift** — code evidence contradicts the model or doc.
 - **Model gap** — code evidence shows behavior neither the model nor the doc covers.
 - **Internal inconsistency** — the doc and the `.em` disagree with each other (surface 3 only).
+- **Accepted divergence** — the relevant canonical element carries a `divergence "..."`
+  annotation (cited directly from a structural entry's `acceptedDivergence` field, or from the
+  `.em`/`em export` for a spec/internal finding). This is what the annotation is *for*: a
+  reasoned, ratified deviation stops being re-reported as drift on every run. Cite the
+  annotation text, not fresh judgment — that judgment already happened when it was written.
 - **Extraction uncertainty** — no evidence either way. Never reported as drift or a gap.
 
 Every classification must cite the evidence recorded in step 2 (or the `em diff` entry, for
@@ -169,7 +190,9 @@ Write `conformance/<YYYY-MM-DD>-report.md` in the model directory, from
 ready-to-apply red note — `issue "conformance: <text>"` on the right element, written out in
 the report exactly as it should be pasted into the `.em` — when a model-side marker is the
 right fix; when the fix is purely doc wording (or the finding is an internal inconsistency
-with no clear side to flag), omit the red note and say why instead. **You never edit the
+with no clear side to flag), omit the red note and say why instead. **Never propose a red note
+for a finding already classified Accepted divergence** — report it (so the annotation itself
+stays auditable) but don't ask the user to ratify what's already ratified. **You never edit the
 canonical model or a slice doc unprompted** — walk the report with the user, apply only the
 proposals they approve, then re-render and `em validate`.
 
@@ -228,3 +251,7 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **Re-deriving what `em diff` already decided** — once you have the JSON, use it; don't
   eyeball the two `.em` files yourself looking for structural differences the tool already
   computed for you.
+- **Re-litigating an accepted divergence** — a non-null `acceptedDivergence` on a diff entry
+  (or a `divergence` annotation on the element behind a spec/internal finding) means this exact
+  question was already reasoned through and ratified. Classify it as Accepted divergence and
+  cite the annotation; don't propose a new red note or re-open the judgment call from scratch.

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,22 +48,30 @@ 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.
 - **`from "X"`** on views/automations declares the source(s); names are quoted, comma-separated.
   Matching is case-insensitive and whitespace-normalized. A `from` may never point at an event or
   view that first appears in a LATER slice (forward-only timeline — validation error).
+  Kinds never cross: a view's `from` resolves ONLY to events; a reaction's `from` resolves ONLY
+  to read models — naming an event on a reaction is a validation error even though the event
+  exists. Feed an event to a reaction by projecting it into a view first (the automation's
+  "to-do list") and pointing the reaction at that view. Name that view after the pending work
+  (`Payments To Process`), never after the triggering event — a view reusing the event's name
+  collides in the shared namespace and draws a duplicate-name warning.
 - **`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
@@ -77,10 +88,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**
@@ -121,7 +171,7 @@ slice "Open Orders — shipped" {
   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`
 }
@@ -134,7 +184,26 @@ slice "Open Orders — delivered" {
   ui Order List @Customer
 }
 
-# 4b. Translation (internal trigger): read model -> translation -> command -> event
+# 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
+}
+
+# 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
@@ -154,6 +223,15 @@ slice "Accepted Quotes — synced" {
 }
 ```
 
+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.
 
@@ -161,38 +239,42 @@ Note the read slice closing each pattern: **every event must be read by some rea
 (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 (no UI) & repeated read models
-
-When the system is headless (no UI — clients call an API), drop `ui`/`persona` entirely:
+### Headless / API systems & repeated read models
 
-A slice body is always multi-line — there is **no one-line `slice "X" { … }` form**, and writing
-one is a parse error (`'slice' is not valid inside a slice`).
+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
-}
+persona IntegratorAPI   # API-flagged lane: its `ui` boxes are API calls, not shipped screens
+
 slice "Create Quote" {
+  ui Create Quote @IntegratorAPI
   command Create Quote
   event QuoteCreated @Quote
 }
 
-# Read: event(s) -> read model -> READ translation (the external caller's API query, replaces UI).
-# This slice is also what makes QuoteCreated a *read* event — without it the model warns.
 slice "Read Quote — created" {
   view Quote from "QuoteCreated"
-  translation SalesRep BU Read Quote
+  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.
+- **`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). `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
+  **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
@@ -215,12 +297,17 @@ slice "Read Quote — created" {
 - 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.
 
 ---
 
@@ -243,30 +330,44 @@ slice "Read Quote — created" {
    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 with no trigger** — nothing issues it. A command needs a `ui` in its slice, or a
+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 (4): a command nothing points at is a write nobody can start.
-3. **Command without event** — every command should record at least one event.
-4. **Event nobody reads** — the mirror of (3): recording an event no read model projects is a
+   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.
-5. **Read model without source** — add `from "Event"` or place the view in a slice with an event.
-6. **Duplicate name** — the same name defined N times; references resolve to the first. Rename.
-7. **Open issue** — an element carries `issue "text"`; resolve the question, then remove the
+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.
-8. **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 }`.
-9. **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).

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,8 +76,9 @@ 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), *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`,