@milehimikey/em 1.4.0 → 1.6.0

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

@@ -16,6 +16,20 @@ three ways:
 3. There is **no other way** for information to flow. Every box on the diagram is one of:
    UI screen, command, event, read model, or automation/processor.
 
+Concretely, that leaves exactly six legal connections, and `em` infers only these:
+`ui → command`, `command → event`, `event → read model`, `read model → ui`,
+`read model → reaction`, `reaction → command`. Every other pair is a rule violation, and an
+explicit `arrow` writing one is a validation error. The two worth naming, because they are the
+tempting shortcuts:
+
+- **`command → read model`** — the CQRS violation. A write is only ever visible to a reader
+  through the event it recorded. Put the event between them.
+- **`read model → command`** — reads never drive a write directly. A processor or translation
+  watches the read model and issues the command, across two slices.
+
+If you find yourself wanting an arrow the patterns don't allow, the model is missing an
+**element**, not an arrow.
+
 **Automations and translations are not exceptions to rule 1.** They are *reactions* — a processor
 or an adapter that wakes up, decides something must change, and **issues a command** to do it. They
 never record an event themselves. A reaction box always points at a **command** (in the next
@@ -37,7 +51,24 @@ Every slice is exactly one of these. In `em`, each maps to a specific shape (see
 ### 1. State Change (Command pattern)
 **UI → Command → Event.** A user (or automation) submits a command; the system validates it
 against invariants and records one or more events.
-- `em` shape: `slice { ui X @Persona  command Y  event Z @Context }`
+- **A State Change never travels alone, and it's joined at both ends.** Something must *trigger*
+  the command — the `ui` it's issued from, or (patterns 3 and 4) the reaction in the slice before
+  it — and its event needs a read model that projects it. So the unit of work is a State Change
+  slice *plus* the State View slice that reads its event. Write them together; a command nothing
+  points at is a write nobody can start, an unread event is a write nobody can see, and
+  `em validate` warns on each.
+- `em` shape (one element per line — there is no one-line slice form):
+  ```em
+  slice "Do The Thing" {
+    ui X @Persona
+    command Y
+    event Z @Context
+  }
+  slice "See The Result" {   # the State View slice that reads Z — pattern 2, but required here
+    view V from "Z"
+    ui Screen @Persona
+  }
+  ```
 - This is where **invariants** live — the command is rejected if a rule is violated.
 - Socratic prompts: *"What does the user do here? What request are they making? What must be
   true for it to succeed? What fact gets recorded when it does? What gets rejected and why?"*
@@ -46,28 +77,38 @@ against invariants and records one or more events.
 **Event(s) → Read Model → UI.** Past events are projected into a read model that a screen
 displays. Read-only; changes no state.
 - `em` shape: `slice { view V from "Event A", "Event B"  ui Screen @Persona }`
-- **Headless / API systems (no UI):** when there is no UI, a read model is consumed by an
-  **external caller querying the API**, modeled as a **read translation** — the outbound analog of
-  `→ ui`. Shape: `slice { view V from "..."  translation <Caller> Read <V> }`. A read translation
-  **triggers no command** (it returns data); it is *not* a reaction, so the
-  `reaction → command → event` rule does **not** apply to it. (Contrast: a *reaction* translation in
-  pattern 4 triggers a command.)
+- **Headless / API systems:** still use `ui`/`persona` — declare a persona per external
+  caller/role (e.g. `IntegratorAPI`) and treat its `ui` boxes as API calls, not screens. Shape:
+  `slice { view V from "..."  ui Read V @IntegratorAPI }`, same as any State View slice.
+  `translation` stays reserved for genuine reactions/external-system boundaries (pattern 4), not
+  for a synchronous request/response API call.
 - **Repeat read models across the timeline.** A read model is drawn fresh in **every** slice where
   it is read — after the events that update it, before the actions that consume it — so the diagram
   shows state flowing left-to-right (the information-completeness staircase). The same read-model
-  name recurring is intentional and **renders cleanly**: `em validate` only warns about a duplicate
-  name that is *also referenced* by a `from`/`arrow` (it resolves to the first), so a repeated read
-  model that nothing references by name produces **no warning**. **Wire each event to a read model
+  name recurring is intentional and **renders cleanly**. Declare every instance after the first with
+  **`view V again from "..."`**: `again` instances are exempt from the duplicate-name warning even
+  when something references them, 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) — otherwise an 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 connected to one another.** There is no arrow between two appearances of one
+  read model, and an explicit one is a validation error. The repeat is an ergonomic device for
+  showing the same read model at successive points in time — continuity is implied by the shared
+  name, and the events arriving at each instance are what show it changing. An arrow between them
+  would say the read model feeds itself.
 - **Place each repeat immediately after its feeding event (span-1).** The cleanest staircase puts a
   read-model instance right after each event that updates it, sourcing **only that one adjacent
   event** — every `event → read model` arrow is then short and forward-flowing. A read model sitting
   far from its source events (e.g. a "list/queue" read placed early but fed by late events) draws
-  long arrows that cross the read-model row and *look* like read→read connections — which Event
-  Modeling forbids. The fix is never a `view → view` edge; it's to repeat the read model next to each
-  event that feeds it.
+  long arrows that sweep across the diagram. The renderer routes them *around* intervening boxes
+  rather than through them, so they no longer *look* like a forbidden read→read link — but the
+  distance itself is the 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. A reader has to trace
+  the line across the diagram to see otherwise. The fix is never a `view → view` edge; it's to
+  repeat the read model next to each event that feeds it, and to keep a sub-flow that detours into
+  another context together rather than parking it at the end of the model.
 - Socratic prompts: *"What does the consumer need to see to make their next decision? Which past
   events provide that information? Is this a screen or an API read? What's the freshness/consistency
   expectation?"*
@@ -76,10 +117,24 @@ displays. Read-only; changes no state.
 **Read Model → Processor → (next slice) Command → Event.** The system reacts on its own: a
 processor watches a read model (a "to-do list" of work) and **issues a command** — it never
 records an event directly.
-- `em` shape: **two slices.** First `slice { view "Todo" from "..."  processor P }`, then the
-  **next** `slice { command C  event E @Context }`. The processor band holds no event; the command
-  in the next slice produces it. Keeping the triggered command in the same slice as the processor
-  is a validation warning — always split it.
+- `em` shape: **two slices**, then the read slice that consumes the event — three in all:
+  ```em
+  slice "Todo" {
+    view Todo from "..."
+    processor P
+  }
+  slice "Do It" {           # the triggered command goes in the NEXT slice
+    command C
+    event E @Context
+  }
+  slice "Todo — done" {
+    view Todo again from "E"   # every event needs a reader; here it clears the to-do list
+    ui Work Board @Persona     # ...and every read model needs a consumer
+  }
+  ```
+  The processor band holds no event; the command in the next slice produces it. Keeping the
+  triggered command in the same slice as the processor is a validation warning — always split it.
+  Forgetting the third slice leaves `E` unread, which is also a warning.
 - Socratic prompts: *"What should happen without a human? What condition triggers it? What work
   list does the processor watch? What command does it fire? What if it fails or retries?"*
 
@@ -87,14 +142,42 @@ records an event directly.
 **Boundary crossing → command → event.** An adapter translates data across a boundary (an external
 system, or another bounded context) into the model's own language. Like an automation, a
 translation is a *reaction*: it **triggers a command**, never records an event directly. Two
-trigger forms:
-- **Externally triggered:** `external input → translation → command → event`. The trigger comes
-  from outside the model, so the translation has no internal `from`.
-- **Internally triggered** (reacting to the modeled system's own state, e.g. pushing data out):
-  `read model → translation → command → event`. The translation reads a **view** via `from`.
-- `em` shape: **two slices**, exactly like an automation. First
-  `slice { [view "Source" from "..."]  translation T [from "Source"] }`, then the **next**
-  `slice { command C  event E @Context }`. The translation band never carries an event.
+independent questions shape which form it takes — don't conflate them:
+- **Trigger source:** does the input come from outside the model, or from the model's own state
+  pushed back out?
+- **Durable artifact:** is there a queryable, persisted thing behind the trigger (a queue, topic,
+  or log), or is it an ephemeral call with nothing to query afterward?
+
+The `em` shape only tracks the second question — trigger source doesn't change it:
+- **No durable artifact:** `external input → translation → command → event`. No internal `from`.
+  Typically (not necessarily) externally triggered — a bare webhook call with nothing persisted
+  behind it.
+- **Durable artifact:** `read model → translation → command → event`. The translation reads a
+  **view** via `from`. This shape is the same whether the view was filled by the model's own event
+  (internally triggered, e.g. pushing data out) or by an external system's persisted queue
+  (externally triggered, e.g. a webhook whose inbound message is stored first for retries,
+  ordering, or audit) — an externally triggered translation backed by a real queue is
+  architecturally closer to this case than to the no-artifact one above.
+- **Event legitimacy:** a received external message counts as a legitimate domain `event` when
+  it's scoped to the context/lane whose fact it represents, not by who committed it — the same
+  move as an Anti-Corruption-Layer boundary event in DDD — and stays legitimate as long as it
+  doesn't leak into the model's own domain vocabulary.
+- `em` shape: **two slices**, exactly like an automation, plus the read slice for the event:
+  ```em
+  slice "Boundary" {
+    view Source from "..."     # durable-artifact form only; omit if there's nothing persisted
+    translation T from "Source"
+  }
+  slice "Record It" {
+    command C
+    event E @Context
+  }
+  slice "Source — recorded" {
+    view Source again from "E"   # every event needs a reader
+    ui Status Screen @Persona    # ...and every read model needs a consumer
+  }
+  ```
+  The translation band never carries an event.
 - Socratic prompts: *"What boundary are we crossing, and which way? What outside system or context
   feeds us (or do we feed)? In what format? How do we know its data is trustworthy/complete? What
   internal **command** does it trigger, and what event does that command record?"*
@@ -170,17 +253,31 @@ dedicated `slice` phase writes the full rich spec (see `templates/slice.md`).
 
 ### Step 7 — Evaluate Completeness  *(model)*
 Walk the whole model with stakeholders and check for loose ends:
+- Every **command** has something that **triggers** it — a `ui` in its slice, or a reaction in the
+  slice before it. A command nothing points at is a write nobody can start. `em validate` warns.
 - Every **command** produces at least one **event**.
-- Every **view** has at least one source event.
-- Every **event** is shown somewhere or consumed by something (no orphan facts).
+- Every **view** has at least one source event, **and a consumer** — a `ui` (headless: the `ui`
+  tagged to the API-caller persona), or a reaction watching it. Every *instance* of a repeated
+  view, not just the last one.
+  A read model nothing displays is information projected out and then dropped. `em validate` warns.
+- Every **event** is **read by a read model** — a `view` naming it in `from` (any `again` instance
+  counts), or a `view` with no `from` sitting in its slice. A reaction consuming it does **not**
+  count: reactions read views, not events. An event nothing projects is a write nobody can see, so
+  there was no point recording it. `em validate` warns on each one.
 - Every **UI** is reachable and leads somewhere.
+- Every connection is one of the six legal pairs (`ui → command`, `command → event`,
+  `event → read model`, `read model → ui`, `read model → reaction`, `reaction → command`). No
+  arrow between two instances of one read model.
 - Automations **and** translations are split correctly (reaction → command → event, never a
   reaction wired straight to an event); translations cover every external input.
-- Run `em validate` and resolve all errors and warnings. Note: `em validate` does **not** catch a
-  translation/automation that emits an event directly — verify the two-slice split by hand.
-- Prompts: *"Is there any event nobody sees? Any screen with no way in or out? Any command that
-  records nothing? Any external system we haven't translated? Any translation or automation that
-  records an event instead of triggering a command?"*
+- Run `em validate` and resolve all errors and warnings. It now catches illegal `arrow` kind pairs
+  (error) and unread events (warning), but it still does **not** catch a translation/automation that
+  emits an event directly — verify the two-slice split by hand.
+- Prompts: *"Is there any event nobody reads — and if the business genuinely never looks at it, why
+  are we recording it? Any command that just happens, with nobody and nothing asking for it? Any
+  screen with no way in or out? Any command that records nothing? Any
+  external system we haven't translated? Any translation or automation that records an event instead
+  of triggering a command?"*
 
 ---
 

package/.claude/skills/event-modeling/templates/conformance-report.md

@@ -16,11 +16,11 @@ Replace bracketed placeholders; delete guidance comments before finishing.
 
 ## Summary
 
-| Surface | Real drift | Model gap | Internal inconsistency | Uncertainty |
-|---|---|---|---|---|
-| Structural | {{n}} | {{n}} | — | {{n}} |
-| Spec | {{n}} | {{n}} | — | {{n}} |
-| Internal | — | — | {{n}} | {{n}} |
+| Surface | Real drift | Model gap | Internal inconsistency | Accepted divergence | Uncertainty |
+|---|---|---|---|---|---|
+| Structural | {{n}} | {{n}} | — | {{n}} | {{n}} |
+| Spec | {{n}} | {{n}} | — | {{n}} | {{n}} |
+| Internal | — | — | {{n}} | {{n}} | {{n}} |
 
 {{One or two sentences: overall read — clean, mostly clean with N items, or notably drifted.}}
 
@@ -32,12 +32,14 @@ Replace bracketed placeholders; delete guidance comments before finishing.
 ### {{n}}. {{Short finding title}}
 
 - **Surface:** {{structural | spec | internal}}
-- **Classification:** {{real drift | model gap | internal inconsistency}}
+- **Classification:** {{real drift | model gap | internal inconsistency | accepted divergence}}
 - **Slice:** {{slice name}}
-- **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name)}}
+- **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name) —
+  for accepted divergence, the `divergence "..."` annotation text itself}}
 - **Claim:** {{what the model/doc says vs. what the code/doc shows — the actual disagreement}}
 - **Proposed red note:** `issue "conformance: {{text}}"` on {{element}} (slice "{{slice}}")
   <!-- Omit this line entirely for internal-inconsistency findings with no clear side to flag,
+       for any accepted-divergence finding (already ratified — don't propose re-ratifying it),
        or when the finding doesn't warrant a red note (say why instead). -->
 
 ## Scenario / invariant coverage

package/.claude/skills/event-modeling/templates/model-readme.md

@@ -21,6 +21,15 @@ Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 - **Automation** — Read Model → Processor → (next slice) Command → Event
 - **Translation** — External input (or Read Model) → Translation → (next slice) Command → Event
 
+Between them these are the only legal connections: `ui → command`, `command → event`,
+`event → read model`, `read model → ui`, `read model → reaction`, `reaction → command`. A command
+never reaches a read model directly — the event goes between them. Every slice is joined up at
+both ends: something triggers each command (the screen it's issued from, or the reaction in the
+slice before it), and every event a command records is read by some read model — so each State
+Change slice is paired with the State View slice that projects its event. A read model repeated
+along the timeline (`view X again`) shows the same projection at a later point; the instances are
+never connected to one another.
+
 ## Slices
 <!-- The canonical slice index — the ONE place slices are enumerated (the state file
      points here rather than keeping its own copy). Keep it in sync as slice docs are

package/.claude/skills/event-modeling/templates/slice.md

@@ -3,10 +3,15 @@ Rich slice design document. One per slice, stored in <model>/slices/<slice-name>
 linked from the .em model with:  note "slices/<slice-name>.md"  on the slice's defining element.
 Fill every section through Socratic questioning. Leave "Open Questions" rather than guessing.
 Replace the bracketed placeholders; delete guidance comments before finishing.
+
+The diagram below is generated, not hand-drawn: `em render <model>.em --slice "{{Slice Name}}"
+-o slices/{{slice-name}}.svg` (kebab-case the slice name to match this doc's own filename).
 -->
 
 # Slice: {{Slice Name}}
 
+![Diagram](./{{slice-name}}.svg)
+
 - **Pattern:** {{State Change | State View | Automation | Translation}}
 - **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
 - **Status:** {{draft | reviewed | ready-to-implement | implemented}}
@@ -32,9 +37,20 @@ an event directly.}}
 |-------|------|----------|--------------------|
 | {{field}} | {{Type}} | {{yes/no}} | {{constraints, formats, ranges}} |
 
+## Trigger
+<!-- What issues this slice's command. Required: a command nothing points at is a write nobody
+     can start. Either the screen the user acts on (a `ui` in this slice), or the reaction that
+     issues it (an automation/processor/translation in the PREVIOUS slice). -->
+**Triggered by:** {{screen `X` @Persona | processor `Y` in slice "Z"}}
+
 ## Event(s) Emitted
 <!-- The immutable facts recorded. List each event and its payload. -->
 **Event:** `{{Event Name}}` → context `{{Context}}`
+**Read by:** {{which read model projects this event, and in which slice}}
+<!-- Required, not optional. Every event must be read by a read model — an event nothing
+     projects is a write nobody can see, and `em validate` warns on it. A reaction consuming
+     it does NOT count: reactions read views, not events. If the honest answer is "nothing
+     reads it", that's a question for the business, not a field to leave blank. -->
 
 | Field | Type | Immutable Fact? | Source / Notes |
 |-------|------|-----------------|----------------|
@@ -43,7 +59,10 @@ an event directly.}}
 ## Read Model / View
 <!-- For State View slices, and any read model this slice produces or feeds. -->
 - **View:** `{{View Name}}` built from events: {{"Event A", "Event B"}}
-- **Consumed by:** {{which UI screen or automation}}
+- **Consumed by:** {{which UI screen (or API-caller persona), or reaction}}
+<!-- "Consumed by" is required, not optional. A read model nothing displays or watches is
+     information projected out of the system and then dropped, and `em validate` warns. Every
+     instance of a repeated view needs its own consumer, not just the last one. -->
 - **Freshness / consistency expectation:** {{real-time | eventual | on-demand}}
 
 ## Invariants / Business Rules

package/.claude/skills/event-modeling/templates/state.md

@@ -11,6 +11,7 @@ Keep it current at the end of every working session.
 - **Current step:** {{1–7, see methodology; or extraction round R1–R7}}
 - **Last updated:** {{YYYY-MM-DD}}
 - **Last conformance:** {{YYYY-MM-DD @ <target-repo revision> — report: conformance/<date>-report.md | never}}
+- **Last stakeholder review:** {{YYYY-MM-DD — attendees: see Participants | never}}
 
 ## Session inputs
 - **Scope line:** {{one-line description of what's in/out of bounds for this model}}
@@ -47,6 +48,13 @@ Keep it current at the end of every working session.
      attribute each entry to the participant who made the call (see Participants above). -->
 - {{YYYY-MM-DD}}: {{decision}} — {{why}} — by {{participant, if a live workshop}}
 
+## Usage log
+<!-- The team's only usage signal today (see docs/usage-data.md) — cheap and coarse on purpose.
+     One line per session: phase(s) touched, and validate diagnostic *categories* hit (the rule
+     name from docs/validation.md's tables, e.g. "read model nothing consumes" — never the full
+     instance message or any domain content). Append, never edit past entries. -->
+- {{YYYY-MM-DD}}: phases: {{discover | extract | model | slice | conform | review | validate | watch, ...}} — validate: {{diagnostic category (docs/usage-data.md#categories), ... | none}}
+
 ## Open questions / parking lot
 <!-- Unresolved items to bring back to the user. Never guess these. Metadata is optional and
      flat — add only what's known: source (ticket/conversation that spawned it), blocked on

package/README.md

@@ -92,6 +92,7 @@ built this way.
 | [docs/timeline.md](docs/timeline.md) | The Two Laws of the Timeline |
 | [docs/ai-workflow.md](docs/ai-workflow.md) | The Claude Code skill: install, phases, artifacts |
 | [docs/dependencies.md](docs/dependencies.md) | What's bundled vs. what needs a system install |
+| [docs/usage-data.md](docs/usage-data.md) | What usage data em captures, and how to roll it up for a retro |
 | [docs/architecture.md](docs/architecture.md) | How rendering works; why Graphviz, not PlantUML |
 | [docs/roadmap.md](docs/roadmap.md) | What's planned |
 

package/dist/catalog/build.d.ts

@@ -0,0 +1,33 @@
+import { NormalizedModel } from "../model/model.js";
+import { Grid } from "../layout/grid.js";
+import { Diagnostic } from "../model/validate.js";
+export interface CatalogModelInput {
+    /** The .em file as given on the command line — used for the doc-discovery path and display. */
+    file: string;
+    model: NormalizedModel;
+    grid: Grid;
+    dot: string;
+}
+export interface CatalogOptions {
+    outDir: string;
+    format?: "svg" | "png";
+    title?: string;
+    /** Forwarded to buildSliceDiagram's fallback build so `--keep-empty-lanes`
+     *  behaves the same way for a built-on-the-fly slice diagram as it does for
+     *  the main one (which already gets it via the per-file compileFile call
+     *  that produced `model`/`grid` in the first place). */
+    keepEmptyLanes?: boolean;
+}
+export interface CatalogBuildResult {
+    models: number;
+    slices: number;
+    /** Ref-collision warnings raised while assigning slice/element keys (same diagnostics
+     *  `em export`/`em diff` surface via computeRefs), tagged by the input file they came from —
+     *  a duplicate slice/element name still gets a stable `~2` key here, but the caller should
+     *  print these the same way every other command does rather than build silently. */
+    diagnostics: {
+        file: string;
+        diagnostics: Diagnostic[];
+    }[];
+}
+export declare function buildCatalog(inputs: CatalogModelInput[], opts: CatalogOptions): Promise<CatalogBuildResult>;

package/dist/catalog/build.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+// Orchestrates `em catalog`'s static-site build — the only I/O in
+// src/catalog/*. One output directory per input model (so slice keys from
+// different files can never collide, even without a cross-file dedup pass):
+//
+//   <outDir>/
+//     index.html
+//     <model-key>/
+//       diagram.svg (or .png)
+//       slices/
+//         <slice-key>.html
+//         <slice-key>.svg   (this slice's own diagram — copied in if authored, else built)
+import { existsSync, readFileSync } from "node:fs";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { layoutDot, composeSvg, writeRendered } from "../render/render.js";
+import { buildSliceDiagram } from "../render/sliceDiagram.js";
+import { computeRefs } from "../emit/json.js";
+import { dedupe, kebabSlug } from "../util/slug.js";
+import { classifySlicePattern } from "./classify.js";
+import { parseSliceDoc } from "./sliceDoc.js";
+import { renderIndexPage, renderSlicePage } from "./pages.js";
+export async function buildCatalog(inputs, opts) {
+    const format = opts.format ?? "svg";
+    const title = opts.title ?? "Event Model Catalog";
+    const outDir = opts.outDir;
+    await mkdir(outDir, { recursive: true });
+    const usedModelKeys = new Set();
+    const modelSummaries = [];
+    const diagnostics = [];
+    let sliceCount = 0;
+    for (const { file, model, grid, dot } of inputs) {
+        const modelKey = dedupe(kebabSlug(basename(file, extname(file))), usedModelKeys, "~");
+        const modelDir = join(outDir, modelKey);
+        const slicesDir = join(modelDir, "slices");
+        await mkdir(slicesDir, { recursive: true });
+        const diagramFile = `diagram.${format}`;
+        // baseDir = dirname(file), same as `em render`/`em watch` — this is why note hrefs
+        // embedded in the diagram still resolve correctly from the catalog's output location.
+        const raw = await layoutDot(dot);
+        const mainSvg = composeSvg(raw, model, grid, dirname(file), modelDir);
+        await writeRendered(mainSvg, join(modelDir, diagramFile), format);
+        const refs = computeRefs(model);
+        if (refs.diagnostics.length > 0)
+            diagnostics.push({ file, diagnostics: refs.diagnostics });
+        const sliceSummaries = [];
+        for (let i = 0; i < model.slices.length; i++) {
+            const slice = model.slices[i];
+            const sliceKey = refs.sliceKeys[i];
+            const pattern = classifySlicePattern(slice);
+            // Look up the doc at the *deduped* key, not a fresh kebabSlug(slice.name): for the
+            // (overwhelmingly common) case of a unique slice name they're identical, but if two
+            // slices share a name (see the diagnostics above), only the first gets sliceKey ==
+            // kebabSlug(name) — the doc a human actually authored on disk. The second slice's key
+            // carries a "~2" suffix no doc file will ever match, so it honestly reports "no doc"
+            // instead of silently rendering the first slice's doc content on both pages.
+            const docRelPath = join("slices", `${sliceKey}.md`);
+            const docPath = join(dirname(file), docRelPath);
+            const doc = existsSync(docPath) ? parseSliceDoc(readFileSync(docPath, "utf8")) : null;
+            // Same sibling-file convention as the doc lookup above, one extension over: a
+            // slice diagram authored by `em render --slice` (per the event-modeling skill)
+            // is copied in as-is so the catalog stays self-contained; otherwise built
+            // fresh via buildSliceDiagram, written only into the catalog's own output
+            // tree — `em catalog` never writes back into the source tree.
+            const sliceSvgSrcPath = join(dirname(file), "slices", `${sliceKey}.svg`);
+            const sliceDiagramFile = `${sliceKey}.svg`;
+            if (existsSync(sliceSvgSrcPath)) {
+                await copyFile(sliceSvgSrcPath, join(slicesDir, sliceDiagramFile));
+            }
+            else {
+                // One Graphviz WASM layout pass per slice lacking an authored sibling — unlike
+                // the single shared pass the old crop-based approach paid for once per model.
+                // Each pass is on a tiny 1-3-column graph, so this is fast in absolute terms
+                // and the WASM module itself is loaded once and memoized (render.ts); a real,
+                // deliberate trade-off, not an oversight — worth revisiting only if catalog
+                // build time on a very-many-slice model actually becomes a complaint.
+                const { model: sliceModel, grid: sliceGrid, dot: sliceDot } = buildSliceDiagram(model, i, {
+                    keepEmptyLanes: opts.keepEmptyLanes,
+                });
+                const sliceRaw = await layoutDot(sliceDot);
+                const sliceSvg = composeSvg(sliceRaw, sliceModel, sliceGrid, dirname(file), slicesDir);
+                await writeFile(join(slicesDir, sliceDiagramFile), sliceSvg, "utf8");
+            }
+            const elementRefs = new Map();
+            for (const el of slice.elements) {
+                const ref = refs.refById.get(el.id);
+                if (ref)
+                    elementRefs.set(el.id, ref);
+            }
+            const page = renderSlicePage({
+                modelName: model.name,
+                diagramFile: `../${diagramFile}`,
+                sliceDiagramFile,
+                slice,
+                sliceKey,
+                pattern,
+                elementRefs,
+                doc,
+                docExpectedPath: docRelPath,
+            });
+            await writeFile(join(slicesDir, `${sliceKey}.html`), page, "utf8");
+            sliceSummaries.push({
+                key: sliceKey,
+                name: slice.name,
+                pattern,
+                hasDoc: doc !== null,
+                status: doc?.status ?? null,
+            });
+            sliceCount++;
+        }
+        modelSummaries.push({ key: modelKey, name: model.name, file, diagramFile, slices: sliceSummaries });
+    }
+    const indexHtml = renderIndexPage(modelSummaries, title, format);
+    await writeFile(join(outDir, "index.html"), indexHtml, "utf8");
+    return { models: modelSummaries.length, slices: sliceCount, diagnostics };
+}
+//# sourceMappingURL=build.js.map

package/dist/catalog/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/catalog/build.ts"],"names":[],"mappings":"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"}

package/dist/catalog/classify.d.ts

@@ -0,0 +1,14 @@
+import { Slice } from "../model/model.js";
+export type SlicePattern = "translation" | "automation" | "state-change" | "state-view" | "unclassified";
+/**
+ * Classify a single slice by its element kinds. Known simplification, not a
+ * bug: docs/patterns.md describes Automation and Translation as spanning
+ * *two* slices — the reaction slice, then a following `command`+`event`
+ * slice. That second slice has the exact same kind-signature as a State
+ * Change slice, so per-slice classification reads it as State Change. This
+ * matches "derived from which element kinds appear in the slice" and keeps
+ * the classifier a pure function of one slice at a time; don't "fix" this by
+ * trying to look at neighboring slices.
+ */
+export declare function classifySlicePattern(slice: Slice): SlicePattern;
+export declare function slicePatternLabel(pattern: SlicePattern): string;

package/dist/catalog/classify.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+// Derives a slice's Event Modeling pattern from which element `kind`s it
+// contains — the pattern itself is never stored in the AST/model (see
+// docs/patterns.md), so `em catalog` is the first consumer that needs it
+// computed. Rules follow docs/patterns.md's "DSL elements" table exactly,
+// checked in priority order (a slice can carry a translation and a view
+// together, for instance, so order matters).
+/**
+ * Classify a single slice by its element kinds. Known simplification, not a
+ * bug: docs/patterns.md describes Automation and Translation as spanning
+ * *two* slices — the reaction slice, then a following `command`+`event`
+ * slice. That second slice has the exact same kind-signature as a State
+ * Change slice, so per-slice classification reads it as State Change. This
+ * matches "derived from which element kinds appear in the slice" and keeps
+ * the classifier a pure function of one slice at a time; don't "fix" this by
+ * trying to look at neighboring slices.
+ */
+export function classifySlicePattern(slice) {
+    const kinds = new Set(slice.elements.map((el) => el.kind));
+    if (kinds.has("translation"))
+        return "translation";
+    if (kinds.has("processor") || kinds.has("automation") || kinds.has("saga"))
+        return "automation";
+    if (kinds.has("command") || kinds.has("event"))
+        return "state-change";
+    if (kinds.has("view"))
+        return "state-view";
+    return "unclassified";
+}
+export function slicePatternLabel(pattern) {
+    switch (pattern) {
+        case "translation":
+            return "Translation";
+        case "automation":
+            return "Automation";
+        case "state-change":
+            return "State Change";
+        case "state-view":
+            return "State View";
+        case "unclassified":
+            return "Unclassified";
+    }
+}
+//# sourceMappingURL=classify.js.map

package/dist/catalog/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/catalog/classify.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,yEAAyE;AACzE,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,6CAA6C;AAM7C;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IACnD,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAChG,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,cAAc,CAAC;IACtE,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,aAAa,CAAC;QACvB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/catalog/pages.d.ts

@@ -0,0 +1,45 @@
+import { Slice } from "../model/model.js";
+import { SlicePattern } from "./classify.js";
+import { SliceDoc } from "./sliceDoc.js";
+export declare function escapeHtml(s: string): string;
+/** A slice's row in the index page's per-model table. */
+export interface CatalogSliceSummary {
+    key: string;
+    name: string;
+    pattern: SlicePattern;
+    /** Whether a slices/<key>.md doc was found at all — distinct from `status` being null,
+     *  which can also mean "doc exists but has no recognizable Status line". */
+    hasDoc: boolean;
+    /** Lowercased Status value from the doc, or null (no doc, or doc has no Status line). */
+    status: string | null;
+}
+export interface CatalogModelSummary {
+    key: string;
+    name: string;
+    /** Input .em file path, as given on the command line. */
+    file: string;
+    /** Diagram filename, relative to <outDir>/<model-key>/. */
+    diagramFile: string;
+    slices: CatalogSliceSummary[];
+}
+export declare function renderIndexPage(models: CatalogModelSummary[], title: string, format: "svg" | "png"): string;
+export interface SlicePageArgs {
+    modelName: string;
+    /** Full model diagram path relative to this page (which lives in
+     *  <outDir>/<model-key>/slices/) — shown as a secondary "view full diagram" link
+     *  (a plain anchor, not an embed, so no MIME type is needed here). */
+    diagramFile: string;
+    /** This slice's own diagram, relative to this page (same directory) — always
+     *  svg (buildSliceDiagram writes svg regardless of the main diagram's chosen
+     *  format). Shown as the page's primary diagram. */
+    sliceDiagramFile: string;
+    slice: Slice;
+    sliceKey: string;
+    pattern: SlicePattern;
+    /** Internal Element.id -> em export ref, for stable per-row anchors. */
+    elementRefs: Map<string, string>;
+    doc: SliceDoc | null;
+    /** slices/<slug>.md, relative to the source .em file — shown when no doc was found. */
+    docExpectedPath: string;
+}
+export declare function renderSlicePage(args: SlicePageArgs): string;