@milehimikey/em 1.1.1 → 1.3.0

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

@@ -5,8 +5,10 @@ description: >-
   the 7 steps of Event Modeling and the 4 patterns (State Change, State View, Automation,
   Translation), and produce implementation-ready slice design documents. Use when the user wants
   to event-model a business process or system, do event modeling / event storming, design slices,
-  build or edit an `.em` model, or run the em tool. Works in resumable phases via an argument:
-  `discover` (steps 1-4), `model` (steps 5-7), `slice` (deep slice specs), plus `watch` and
+  build or edit an `.em` model, run the em tool, or extract / reverse-engineer a current-state
+  event model from an existing system or codebase (event-driven or legacy/procedural). Works in
+  resumable phases via an argument: `discover` (steps 1-4, greenfield), `extract` (current-state
+  model of an existing system), `model` (steps 5-7), `slice` (deep slice specs), plus `watch` and
   `validate`. With no argument it resumes from the saved state file.
 ---
 
@@ -16,8 +18,8 @@ You are facilitating an Event Modeling session. Your job is to **extract an accu
 the user through Socratic questioning** — never to invent the domain. You drive the `em` CLI to
 render the model live, and you produce implementation-ready slice design docs.
 
-Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl.md` (DSL syntax
-+ validation rules) before doing real work — they are the source of truth. Templates live in
+Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl.md` (DSL syntax and
+validation rules) before doing real work — they are the source of truth. Templates live in
 `templates/`.
 
 ## Operating principles (every phase)
@@ -26,7 +28,8 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
   multiple-choice decisions. Never assume a domain fact — extract it. Prefer "who/why/what-if/
   what-must-always-be-true/how-do-you-know" over yes-no.
 - **Don't guess — park it.** Unresolved items go into the Open Questions list in
-  `.event-modeling.md`, not into invented model content.
+  `.event-modeling.md`, not into invented model content. Note the source, blocker, and revisit
+  date when known — cheap now, useful when you come back to it.
 - **Happy path first; branches belong to slicing.** Steps 1-7 build the **happy-path spine**.
   Alternate, unhappy, and exception-path events (rejections, removals, cancellations,
   expirations, declines) are **not** enumerated as a separate discover/model task — they
@@ -59,7 +62,11 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
    directory (or a `models/` subfolder). If found, read the state file. If not, and the phase
    needs one, ask the user for the model name and where to create it.
 3. Parse the argument (`$ARGUMENTS`) to pick the phase below. With **no argument**, read the
-   state file and resume the recorded phase/step; if no model exists, propose starting `discover`.
+   state file and resume the recorded phase/step; if no model exists, propose starting `discover`
+   (greenfield) or `extract` (modeling an existing system).
+4. Populate the state file's Participants section at session start. For a live workshop, ask for
+   a single human proxy to relay questions to the room, and attribute every answer/decision in
+   the Decisions log to a named participant.
 
 ## Project layout this skill creates
 
@@ -67,22 +74,28 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
 <model-name>/
   <model-name>.em          # the model (slice docs linked via note "...")
   <model-name>.svg         # render target for em watch
-  live.html                # auto-refresh viewer (copy of templates/live.html, SVG_FILE set)
+  live.html                # file:// auto-refresh viewer (copy of templates/live.html, verbatim)
   README.md                # overview + slice index (from templates/model-readme.md)
   .event-modeling.md       # resumable state (from templates/state.md)
   slices/<slice-name>.md   # one rich slice doc per slice (from templates/slice.md)
 ```
 
-When creating a new model, scaffold the directory, copy the templates in (filling the
-placeholders), and set `SVG_FILE` in the copied `live.html` to `<model-name>.svg`. You may use
-`em init` for a starter `.em`, but usually you'll build it up from the discovery conversation
-instead. Fill template placeholders — never leave `{{...}}` in delivered files.
+When creating a new model, scaffold the directory and copy the templates in (filling the
+placeholders). Copy `live.html` **verbatim** — it takes the SVG name from its URL query
+(`live.html?svg=<model-name>.svg`), so there's nothing to edit. You may use `em init` for a
+starter `.em`, but usually you'll build it up from the discovery conversation instead. Fill
+template placeholders — never leave `{{...}}` in delivered files.
 
 ---
 
 ## Phase: `discover` — steps 1-4
 
 Goal: a draft model of events, storyboard, commands, and views. Loose is OK; structure comes next.
+**Existing system?** Use `extract` instead (next section) — discover is for greenfield modeling.
+**New feature inside an existing codebase?** Stay in `discover`, but before locking in
+command/event names, Grep/Read adjacent real sources (OpenAPI specs, DB migrations, existing
+DTOs/event classes in sibling contexts) rather than guessing conventions — same check `slice`
+phase applies to field tables, below.
 
 1. **Brainstorm events (step 1).** Ask the user to name everything that happens, as past-tense
    facts. Probe for missed state changes. For each candidate, apply the **"is it an event?"
@@ -104,8 +117,29 @@ Goal: a draft model of events, storyboard, commands, and views. Loose is OK; str
    `reference/methodology.md`).
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
-decisions, open questions, slice inventory). Tell the user they can stop here and resume with
-`/event-modeling model`.
+decisions, open questions) and `README.md`'s slice index. Tell the user they can stop here and
+resume with `/event-modeling model`.
+
+## Phase: `extract` — current-state model of an existing system
+
+Goal: a faithful **current-state** model extracted from an existing system — the as-is sibling
+of `discover` (it replaces discover; the model then proceeds to `model` as usual).
+
+**Read `reference/extract.md` before doing any extract work** — it carries a stance override
+that inverts methodology step 1 (capture how the system behaves *today*; never model desired
+state).
+
+- Two source modes, detected from the system itself and confirmed with the user:
+  **event-driven** (an event vocabulary already exists — schemas, topics, handlers) and
+  **procedural/monolith** (no event vocabulary — synthesize candidate events from behavior
+  and docs).
+- Converge via a ~7-round confirm-and-clarify loop (one concern per round; render from round 2,
+  validate from round 4 — see the playbook).
+- **Current-state-only:** park unknowns as `# TBD` comments in the `.em`, mirrored in the state
+  file's Open Questions — never guess intended design.
+
+End of phase: validated as-is model; state file updated (source mode, rounds, decisions) and
+`README.md`'s slice index seeded; then chain to `/event-modeling model` (steps 5-7).
 
 ## Phase: `model` — steps 5-7
 
@@ -134,7 +168,7 @@ End of phase: render, update state, suggest `/event-modeling slice` to write imp
 ## Phase: `slice` — deep slice documents
 
 Goal: implementation-ready specs. Go slice by slice (let the user pick order, or follow the
-timeline). Check the state file's slice inventory for what's already done.
+timeline). Check `README.md`'s slice index for what's already done.
 
 This is also where **branch / unhappy-path events** are discovered and added to the model — as a
 slice's alternate/error flows surface (a rejection, removal, cancellation, decline, expiry), add
@@ -145,24 +179,33 @@ For each slice:
 1. Hold a Socratic deep-dive to fill every section of `templates/slice.md`: intent, trigger/actor,
    command + field table (types & rules), event(s) + payload (mark immutable facts), invariants
    (give each a stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
-   alternate/error flows (retries, idempotency, compensations), read models affected, open
-   questions. Park anything unresolved rather than guessing.
-2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name).
+   alternate/error flows (retries, idempotency, compensations), non-functional requirements
+   (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park
+   anything unresolved rather than guessing. If the slice lives in an existing codebase, Grep/Read
+   adjacent real sources (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling
+   contexts) before finalizing field names/types or invariants — don't guess a shape that's
+   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
    (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 and the state file's slice inventory (`draft` → `ready`).
+4. 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`.
 
 ## Phase: `watch` — live team view
 
-1. Ensure `live.html` exists in the model dir (copy from `templates/live.html`) with `SVG_FILE`
-   set to `<model-name>.svg`.
-2. Start the watcher in the background: `em watch <model-name>.em -o <model-name>.svg`
-   (run_in_background). It re-renders the SVG on every save.
-3. Tell the user to open `live.html` in a browser and share their screen — it auto-refreshes ~1s,
-   so the team sees the model evolve as you edit during the session. (`em` has no built-in server;
-   the HTML viewer provides the auto-reload.)
+**Recommended (instant push, no polling):** start the watcher with `--serve` in the background:
+`em watch <model-name>.em -o <model-name>.svg --serve` (run_in_background). It re-renders on every
+save and pushes an instant reload to the browser over Server-Sent Events. Tell the user to open the
+URL it prints (e.g. `http://localhost:5173/?svg=<model-name>.svg`) and share their screen — updates
+appear the moment you save, with no idle churn between edits.
+
+**No-server fallback (`file://`):** if the user prefers not to run a server, start the plain watcher
+`em watch <model-name>.em -o <model-name>.svg` (run_in_background) and have them open the copied
+`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: `validate`
 
@@ -170,6 +213,11 @@ Run `em validate <model-name>.em` and walk through each diagnostic with the user
 rule (see `reference/em-dsl.md`) and proposing the fix (e.g. split an automation's command into
 the next slice, add a missing `from`, give a command its event). Apply fixes on agreement.
 
+For anything genuinely unresolved rather than a rule violation, prefer `issue "text"` on the
+relevant element over a `# TBD` comment — it shows up as a red marker on the rendered diagram and
+`em validate` tracks it as an open-issue warning, so it isn't lost once rendered. `em validate
+--list-issues` gives a quick sweep of everything still open.
+
 Then do one check `em validate` can't: scan every `translation`/`processor`/`automation` slice and
 confirm none contains an `event` — each reaction must trigger a `command` in the next slice
 (`reaction → command → event`). If you find a reaction wired straight to an event, split it into
@@ -186,6 +234,7 @@ em validate <name>.em                      # check rules; exit 0 if clean/warnin
 em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
 em render <name>.em --emit-dot             # inspect generated Graphviz DOT
 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)
 ```
 
 Always finish a working session by: re-rendering, running `em validate`, and updating

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

@@ -1,3 +1,5 @@
+<!-- DSL behavior change? Update BOTH docs/dsl.md and .claude/skills/event-modeling/reference/em-dsl.md -->
+
 # `em` DSL Reference & Cheatsheet
 
 The `em` tool (`@milehimikey/em`) is a slice-first text DSL rendered to a strict Graphviz
@@ -13,8 +15,11 @@ 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 watch  <file> -o out.svg    # re-render on every save (file-based; no HTTP server)
+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> --fail-on-issues    # opt-in CI gate: exit non-zero while any issue remains open
 ```
 
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
@@ -34,6 +39,7 @@ slice "Name" {                   # one vertical time step (a column)
   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)
+  view Free Text again from "Event C"        # later instance of an evolving read model (see Clauses)
   event Free Text @Context       # recorded fact; @Context picks its row (defaults to "Domain")
   processor Free Text from "View"   # automation; aliases: automation | saga | translation
 }
@@ -44,18 +50,32 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
 ### Element kinds (8 keywords, nothing else)
 | Keyword | Band | Meaning | Tag | Extra clauses |
 |---|---|---|---|---|
-| `ui` | persona | screen / interface | `@Persona` | `note`, `{ fields }` |
-| `command` | API | state-changing request | — | `note`, `{ fields }` |
-| `view` | API | read model / projection | — | `from "Event"…`, `note`, `{ fields }` |
-| `event` | context | recorded fact (past tense) | `@Context` | `note`, `{ fields }` |
-| `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `{ fields }` |
+| `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 }` |
 
 ### 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.
+  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).
+- **`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.
+  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
   a clickable marker in SVG and a legend entry in PNG/PDF. **This is how slice docs attach.**
+- **`issue "text"`** on ANY element flags an open question inline — the diagram-visible red
+  sticky note. Renders as a red corner marker (opposite corner from `note`, so both can coexist
+  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.
 - **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.
@@ -141,7 +161,9 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
   *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.)
+  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.
 - **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
@@ -170,6 +192,11 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 2. **Unknown event source** — `view X from "Event"` where the event doesn't exist anywhere.
 3. **Unknown read-model source** — `processor X from "View"` where the view doesn't exist.
 4. **Arrow endpoint mismatch** — `arrow A -> B` where A or B matches no element name.
+5. **Backward timeline** ("time flows left to right") — an event feeding a view instance in an
+   EARLIER slice (fix: add a `view X again` instance where the event lands and move the source
+   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.
 
 **Warnings (should fix):**
 1. **Automation/translation shares slice with its command** — both `automation`/`processor` and
@@ -177,6 +204,16 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 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
+   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
+   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.
 
 **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

@@ -0,0 +1,124 @@
+# Extract Phase — Current-State Model of an Existing System
+
+Read this **before doing any extract work**. It governs the `extract` phase and **overrides
+`methodology.md` step 1's stance** for the duration of extraction: you are capturing how the
+system behaves **today**, not modeling what the business needs. Everything else in the
+methodology — the 4 patterns, the "is it an event?" test, the Socratic stance, the two-slice
+reaction split — still applies.
+
+## Stance override — current-state-only
+
+- Capture the system **as it is**, faithfully, warts included. Never invent future or desired
+  state. Improvement ideas that surface go to the state file's Open Questions or Decisions log
+  — never into the model.
+- Methodology step 1's caution ("model the process the business **needs**, not how the current
+  system happens to work — existing system behavior is a common source of fake events") is
+  **deliberately suspended**: here the existing system *is* the subject.
+- The **"is it an event?" filter still applies.** Derived values (totals, calculated fields)
+  and telemetry/activity (clicks, page views, logins) are still not events, even when the
+  current system stores or emits them as such. Park each rejection in the Decisions log with
+  why, so it isn't re-proposed.
+- **Never guess.** Unknown or ambiguous current behavior is parked (see TBD convention below),
+  not filled in with what the design "probably" intends.
+
+## Setup
+
+1. Run the SKILL.md preconditions (tool check, model location) and scaffold the standard
+   project layout if no model exists yet.
+2. **Agree the scope line first**: which system, which part, what's out of bounds. Write it to
+   the state file's Session inputs.
+3. Record in the state file: `Source mode` (after detection, below) and
+   `Existing system refs` — the repo paths, event-schema/topic locations, and docs you will
+   extract from.
+
+## Mode detection
+
+Inspect the system with your own tools (Grep/Read over the codebase and docs), then confirm
+the mode with the user:
+
+- **Event-driven** — the system already has an event vocabulary. Signals: event
+  schemas/classes, topics/streams/queues, message or CDC handlers, an event store, pub/sub
+  wiring. Extraction *lifts* the model from that vocabulary.
+- **Procedural / monolith** — no event vocabulary. Signals: transaction scripts, service
+  methods mutating rows, CRUD controllers, procedural runbooks/docs. Extraction *synthesizes*
+  candidate events from the state changes the behavior implies.
+
+Mixed systems happen: pick the dominant mode, note the exception areas in the state file.
+
+## Sourcing by mode
+
+- **Event-driven:** inventory the emitted/consumed event types; take past-tense business facts
+  directly; then filter — technical/infrastructure messages (retries, heartbeats, envelope
+  wrappers) and derived/telemetry types are dropped (log why). Keep the system's own names
+  where they are honest past-tense facts; propose a cleaner past-tense name only when the
+  original is technical (record the mapping in the Decisions log).
+- **Procedural:** for each significant operation, ask "what business fact has become true when
+  this completes?" — those are the candidate events. Screens and tables are *evidence* of
+  state changes, not events themselves; a table row's lifecycle (created/updated/closed) often
+  implies several events. Apply the event filter hard here — procedural systems are where
+  derived values and activity records masquerade as facts.
+
+## The confirm-and-clarify loop (~7 rounds)
+
+One concern per round. After every round: mirror what you extracted back to the user, update
+the `.em`, and (from R2) re-render so they see the model grow. Convergence beats coverage —
+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.**
+- **R3 — Commands / inputs.** For each event, the request that actually produces it today
+  (imperative name). Unclear trigger → `# TBD`, not a plausible guess.
+- **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.
+- **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
+  the current code wires it as one procedural step (note the as-built shape in the slice's
+  `# TBD`/Decisions if it differs).
+- **R6 — Gap & TBD reconciliation.** Walk every parked `# TBD` with the user. Resolve only
+  what they can confirm **as a current-state fact**; everything else stays parked. Explicitly
+  refuse to resolve a TBD by inventing desired behavior.
+- **R7 — Convergence.** Final `em render` + `em validate` (fix errors and warnings; remember
+  the validator's blind spot — check the reaction split by hand). User confirms the model is a
+  faithful picture of today. Mark extraction complete in the state file and hand off.
+
+Seven rounds is the default shape, not a quota — collapse rounds for a small system, repeat
+one for a sprawling one. Record any deviation in the Decisions log.
+
+## TBD parking convention
+
+- Inline `.em` comment on its own line directly above (or trailing) the element it concerns:
+  `# TBD: <specific question about current behavior>`. Comments are native DSL syntax — they
+  render and validate cleanly.
+- Mirror every `# TBD` 1:1 as a checkbox in the state file's **Open questions / parking lot** —
+  add `source`/`blocked on`/`revisit` metadata when known — and remove both together when
+  resolved.
+- A `# TBD` is only ever resolved by a confirmed current-state fact — never replaced by a
+  guessed element.
+
+## 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:
+
+1. State file: set phase progress (extraction rounds checked), log the completion decision.
+   Seed `README.md`'s **slice index** (every slice, pattern, status `none`).
+2. The extracted model **replaces `discover`** — suggest `/event-modeling model` next
+   (steps 5-7: swimlanes, patterns, completeness). Desired-state changes belong *after* the
+   as-is model is agreed — as normal `model`/`slice` evolution, clearly separated from
+   extraction.
+
+## Anti-patterns
+
+- **Inventing desired state** — the cardinal sin of extraction; park it instead.
+- **Importing screens/tables as events** — they are evidence of state changes, not facts.
+- **Guessing an unclear trigger or reaction** instead of parking a `# TBD`.
+- **Cleaning up the domain while extracting** — renames and restructures beyond honest
+  past-tense naming are `model`-phase work, done with the user after the as-is picture exists.
+- **Skipping render/validate until the end** — the loop depends on the user seeing the model
+  grow round by round.

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

@@ -121,6 +121,9 @@ state change anyone can think of. No commands, no UI yet — just facts.
     User Clicked Button, User Viewed Page, User Logged In.
 - Model the process the business **needs**, not how the current system happens to work. Existing
   system behavior is a common source of fake events — screens and tables leaking in as facts.
+  (**Extract mode inverts this**: in the skill's `extract` phase the existing system *is* the
+  subject and this caution is deliberately suspended — see the "Extract" section below and
+  `reference/extract.md`. The derived-value and telemetry filters still apply there.)
 - Output: a flat list of candidate `event` names.
 
 ### Step 2 — The Plot / Storyboard  *(discover)*
@@ -160,6 +163,9 @@ dedicated `slice` phase writes the full rich spec (see `templates/slice.md`).
 - Prompts: *"Given what starting state, when this command/trigger fires, then what event(s)
   result? What must always be true? What are the failure paths? Which fields are essential and
   what are their rules?"*
+- **Existing codebase:** before finalizing field names/types, check adjacent real sources
+  (OpenAPI specs, DB migrations, existing DTOs/event classes in sibling contexts) rather than
+  guessing — mirrors `extract.md`'s whole-system grounding, applied per-slice.
 - Output: rich slice docs linked into the `.em` via `note "slices/<name>.md"`.
 
 ### Step 7 — Evaluate Completeness  *(model)*
@@ -178,6 +184,28 @@ Walk the whole model with stakeholders and check for loose ends:
 
 ---
 
+## Extract: current-state models of existing systems
+
+The `extract` phase derives a model from an **existing** system instead of a greenfield
+conversation. It is discover's as-is sibling: its confirm-and-clarify rounds converge the same
+step 1–4 outputs (events, timeline, commands, read models) — *derived from the system*, then
+confirmed with the user — after which the model enters `model` (steps 5–7) as usual.
+
+The stance inversion, stated authoritatively: **extraction captures how the system behaves
+today — faithfully, warts included — and never invents future or desired state.** Step 1's
+anti-current-system caution is suspended for the duration; the "is it an event?" filter is
+not — derived values and telemetry are still rejected even when the current system emits them.
+Unknown or ambiguous current behavior is parked, never guessed — mirrored in the state file's
+Open Questions, and on the element itself with `issue "text"` when it should also show up on the
+rendered diagram (preferred over a bare `# TBD` comment, which is invisible once rendered).
+Desired-state improvements belong to the `model` and `slice` phases, after the as-is picture is
+agreed.
+
+Procedure, source modes (event-driven vs. procedural synthesis), and the round-by-round loop:
+`reference/extract.md`.
+
+---
+
 ## Socratic stance (applies throughout)
 
 - Ask **one focused question at a time**; never assume a domain fact — extract it.
@@ -185,3 +213,6 @@ Walk the whole model with stakeholders and check for loose ends:
 - Mirror the model back after each increment and **re-render** so the team sees it evolve.
 - Park unresolved questions in the state file instead of guessing.
 - Name things crisply: events past-tense, commands imperative, views as the thing-shown.
+- **Live workshop, one chat interface:** route through a single human proxy who relays questions
+  to the room and reports answers back; attribute every answer/decision in the Decisions log to
+  the named participant who gave it (see the state file's Participants section).

package/.claude/skills/event-modeling/templates/live.html

@@ -3,10 +3,22 @@
   Live viewer for an em event model. Auto-reloads the rendered SVG so a team on a shared
   screen sees updates from `em watch` without manual refresh.
 
-  Usage:
-    1) In one terminal:  em watch MODEL.em -o MODEL.svg
-    2) Set SVG_FILE below to the SVG filename (same folder as this file).
-    3) Open this file in a browser (open live.html) and share the screen.
+  Two ways to use it:
+
+    A) Push (recommended, instant, no polling):
+         em watch MODEL.em -o MODEL.svg --serve
+       then open the URL it prints (http://localhost:5173/?svg=MODEL.svg). You don't need
+       this file at all in that mode — the server serves its own push-based viewer.
+
+    B) This file, over file:// (no server):
+         1) In one terminal:  em watch MODEL.em -o MODEL.svg
+         2) Open this file with the SVG name in the query:
+              open "live.html?svg=MODEL.svg"      (macOS)
+            No editing required — the ?svg= param picks the model.
+
+  Under file:// the browser gives no reliable "did the file change?" signal (fetch/HEAD is
+  blocked), so this fallback polls and reloads on a gentle interval. It double-buffers the
+  swap so a shared screen never flashes. For zero idle work and instant updates, use --serve.
 
   The SVG is embedded via <object> so note "..." links inside it stay clickable.
 -->
@@ -37,17 +49,57 @@
     <object id="svg" type="image/svg+xml"></object>
   </div>
   <script>
-    // Change this to your model's SVG filename:
-    const SVG_FILE = "model.svg";
-    const obj = document.getElementById("svg");
+    // SVG filename from ?svg=<name>.svg (defaults to model.svg) — one file serves any model.
+    const SVG_FILE = new URLSearchParams(location.search).get("svg") || "model.svg";
+    // Poll cadence for the file:// fallback. Tune freely; --serve makes polling unnecessary.
+    const REFRESH_INTERVAL_MS = 2000;
+
+    const stage = document.getElementById("stage");
     const stamp = document.getElementById("stamp");
-    function reload() {
-      // cache-bust so the freshly written SVG is fetched each tick
-      obj.setAttribute("data", SVG_FILE + "?t=" + Date.now());
-      stamp.textContent = new Date().toLocaleTimeString();
+    let current = document.getElementById("svg");
+    let lastModified = null;
+
+    // Best-effort change check — only meaningful when served over http(s). Under file://
+    // fetch/HEAD is blocked, so this throws and we fall back to reloading every tick.
+    async function changed() {
+      if (!location.protocol.startsWith("http")) return true;
+      try {
+        const res = await fetch(SVG_FILE, { method: "HEAD", cache: "no-store" });
+        const tag = res.headers.get("last-modified") || res.headers.get("etag");
+        if (tag && tag === lastModified) return false;
+        lastModified = tag;
+        return true;
+      } catch {
+        return true; // can't tell — reload to be safe
+      }
     }
-    reload();
-    setInterval(reload, 1000);
+
+    // Double-buffer: load into a hidden <object>, swap on load, so the shared screen
+    // never flashes white during a reload.
+    function swap() {
+      const next = document.createElement("object");
+      next.type = "image/svg+xml";
+      next.style.cssText = current.style.cssText;
+      next.addEventListener("load", () => {
+        stage.replaceChild(next, current);
+        current = next;
+        stamp.textContent = new Date().toLocaleTimeString();
+      }, { once: true });
+      next.setAttribute("data", SVG_FILE + "?t=" + Date.now());
+    }
+
+    // Self-scheduling loop: schedule the next tick only after this one resolves, so a slow
+    // reload can never overlap the next tick.
+    async function tick() {
+      try {
+        if (await changed()) swap();
+      } finally {
+        setTimeout(tick, REFRESH_INTERVAL_MS);
+      }
+    }
+
+    swap();
+    setTimeout(tick, REFRESH_INTERVAL_MS);
   </script>
 </body>
 </html>

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

@@ -6,10 +6,13 @@
 While modeling, run the live view so the team can watch the diagram update:
 
 ```bash
-em watch {{model-name}}.em -o {{model-name}}.svg   # re-renders on every save
-# then open live.html in a browser (auto-refreshes ~1s; share the screen)
+em watch {{model-name}}.em -o {{model-name}}.svg --serve   # re-render + instant push-reload
+# then open the URL it prints (http://localhost:5173/?svg={{model-name}}.svg) and share the screen
 ```
 
+No server? Run `em watch {{model-name}}.em -o {{model-name}}.svg` and open
+`live.html?svg={{model-name}}.svg` in a browser (polls ~2s; share the screen).
+
 Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 
 ## Patterns legend
@@ -19,10 +22,12 @@ Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 - **Translation** — External input (or Read Model) → Translation → (next slice) Command → Event
 
 ## Slices
-<!-- Keep this index in sync as slice docs are written. -->
-| # | Slice | Pattern | Design doc |
-|---|-------|---------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
+<!-- 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
+     written and as statuses move. -->
+| # | Slice | Pattern | Status | Design doc |
+|---|-------|---------|--------|------------|
+| 1 | {{Slice Name}} | {{Pattern}} | {{none / draft / reviewed / ready-to-implement / implemented}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

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

@@ -9,10 +9,12 @@ Replace the bracketed placeholders; delete guidance comments before finishing.
 
 - **Pattern:** {{State Change | State View | Automation | Translation}}
 - **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
-- **Status:** {{draft | reviewed | ready-to-implement}}
+- **Status:** {{draft | reviewed | ready-to-implement | implemented}}
+- **Implemented in:** {{PR/commit link — fill in once status is `implemented`}}
 
 ## Intent
-{{Why this slice exists — the user or business goal it serves, in one or two sentences.}}
+{{Why this slice exists — the user or business goal it serves, in one or two sentences. Note the
+originating ticket/conversation link here if one exists.}}
 
 ## Trigger & Actor
 {{Who or what initiates this slice and under what circumstances. For automations, the watched
@@ -61,6 +63,13 @@ an event directly.}}
 - {{e.g. external call fails → retry policy / compensating event}}
 - {{idempotency: what happens if the command/event arrives twice?}}
 
+## Non-Functional Requirements
+<!-- Short checklist. Idempotency is covered above under Alternate & Error Flows — not repeated
+     here. -->
+- **Security / authz:** {{who may invoke this; role/permission checks — or "none"}}
+- **PII & compliance:** {{personal data touched, retention/consent constraints — or "none"}}
+- **Performance / SLA:** {{latency/throughput expectation — or "none"}}
+
 ## Dependencies & Read Models Affected
 - **Upstream events this slice relies on:** {{...}}
 - **Downstream read models / slices affected:** {{...}}