@milehimikey/em 1.1.0 → 1.2.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,10 +18,9 @@ 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), `reference/em-dsl.md` (DSL syntax +
-validation rules), and — before the `slice` phase specifically — `reference/frontmatter.md` (the
-slice-doc frontmatter schema, lifecycle, and `em slice` CLI) before doing real work; they are the
-source of truth. Templates live in `templates/`.
+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)
 
@@ -59,14 +60,9 @@ source of truth. Templates live in `templates/`.
 2. Locate the model. Look for an existing `<dir>/.event-modeling.md` and `*.em` in the working
    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. **Pre-1.0 model check.** If a `slices/*.md` doc exists with no YAML frontmatter block (run
-   `em validate <model>.em` — a missing-frontmatter doc errors with a message pointing at this),
-   tell the user this model predates the frontmatter standard and offer to run
-   `em migrate <model-dir>` before continuing (it refuses a dirty git tree by default — commit
-   first, or pass `--force`). Don't hand-edit old-format docs around this; migrate once, then
-   proceed normally.
-4. 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`.
+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`
+   (greenfield) or `extract` (modeling an existing system).
 
 ## Project layout this skill creates
 
@@ -74,32 +70,24 @@ source of truth. Templates live in `templates/`.
 <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, with frontmatter)
-  em.config.json           # optional: { "sliceTemplate": "..." } for a team's own slice template
-  slices/<slice-id>.md     # one rich slice doc per slice, scaffolded via `em slice new`
+  .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 `model-readme.md`/`state.md`
-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. **Slice docs are the one exception**: don't hand-copy `templates/slice.md` —
-use `em slice new` (see the `slice` phase below), which injects the required frontmatter and
-respects a project's `em.config.json` custom template if one is configured.
-
-Ask the **Regulatory scope** session input (state.md) up front, alongside Scope line / PRD
-reference / Headless-API-model: does this domain have compliance requirements (PCI-DSS, SOX,
-HIPAA, GDPR, ...) or none? This decides whether the `slice` phase asks about the `compliance:`
-frontmatter block per slice (see `reference/frontmatter.md`) — don't ask about compliance at all
-for a model with no regulatory scope.
+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.
 
 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?"
@@ -124,6 +112,27 @@ End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (s
 decisions, open questions, slice inventory). 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, slice
+inventory); then chain to `/event-modeling model` (steps 5-7).
+
 ## Phase: `model` — steps 5-7
 
 Goal: a structurally complete, **validated** model with correct patterns and swimlanes.
@@ -159,54 +168,36 @@ the corresponding event/slice to the `.em` and re-render. The happy-path spine f
 phases is the starting point, not the finished event set.
 
 For each slice:
-1. Scaffold the doc: `em slice new "<Slice Name>" --pattern <state-change|state-view|automation|translation>`.
-   This writes `slices/<id>.md` with the required frontmatter already filled in (`id`, `pattern`,
-   `status: draft`, `version: 1`, …) and the body template (custom, if `em.config.json` configures
-   one; the shipped default otherwise) ready to fill in.
-2. Hold a Socratic deep-dive to fill every body section: 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),
+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. Pattern and status are frontmatter
-   now, not prose — see `reference/frontmatter.md`. If the model's **Regulatory scope** (state
-   file) isn't "none," additionally ask whether *this* slice touches regulated data or processes;
-   if so, hand-add a `compliance:` block to the doc's frontmatter (see `reference/frontmatter.md`
-   for the suggested shape — `em` never validates it, so use whatever sub-fields fit). Skip this
-   question entirely for non-regulated models, and skip the block for slices with no compliance
-   relevance even in a regulated model — don't ask by rote.
-3. Wire it into the `.em`: add `note "slices/<id>.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. Run `em slice sync <id>` — it discovers the linked element from that `note` and fills in the
-   generated frontmatter fields (`commands`/`events`/`readModels`/`contexts`/`personas`, and
-   `triggers`/`triggeredBy` for automation/translation). **Re-run `em slice sync <id>` (or
-   `--all`) after any later `.em` edit that touches this slice's elements** — generated fields
-   drift otherwise, and `em validate` will flag it.
-5. When the doc is solid, move it forward: `em slice update <id> --status reviewed` (and later
-   `--status ready-to-implement`). Update `README.md`'s slice index.
-6. Re-render and `em validate` (validates the `.em` **and** every slice doc's frontmatter by
-   default).
+   questions. Park anything unresolved rather than guessing.
+2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name).
+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-to-implement`).
+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`
 
 Run `em validate <model-name>.em` and walk through each diagnostic with the user, explaining the
-rule (see `reference/em-dsl.md` for `.em` rules, `reference/frontmatter.md` for slice-doc
-frontmatter rules) and proposing the fix. Apply fixes on agreement:
-- `.em`-level fixes: split an automation's command into the next slice, add a missing `from`, give
-  a command its event.
-- Slice-doc-level fixes: no frontmatter block → run `em migrate` (pre-1.0 model); "out of sync
-  with .em" → run `em slice sync <id>`; orphan doc → wire a `note "slices/<id>.md"` onto the
-  right element, then sync.
+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.
 
 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
@@ -220,20 +211,12 @@ two slices and route it through a command.
 ```bash
 em --version
 em init <name>.em                          # optional starter scaffold
-em validate <name>.em                      # check .em rules + slice-doc frontmatter
+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 watch <name>.em -o <name>.svg           # re-render on save (run in background)
-
-em slice new "<Slice Name>" --pattern <pattern>   # scaffold slices/<id>.md with frontmatter
-em slice sync <id>                                # after wiring note "slices/<id>.md" into the .em
-em slice update <id> --status <status>            # move a slice's lifecycle status forward
-em slice list / show <id> / search "<query>"      # query slice docs by frontmatter (--format json)
-em slice search "<q>" --format json --full        # ...with every field, not just the summary row
-em migrate <model-dir>                            # one-time upgrade from a pre-1.0 model
+em watch <name>.em -o <name>.svg --serve   # + live viewer with instant push-reload (--port N)
 ```
 
-See `reference/frontmatter.md` for the full slice-doc frontmatter schema and CLI reference.
-
 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.

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,28 +15,14 @@ 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
 ```
 
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
 `rsvg-convert`.
 
-**Slice docs** (frontmatter, lifecycle, search — see `reference/frontmatter.md` for the schema):
-
-```bash
-em slice new "Slice Name" [--pattern state-change] [--id <id>]   # scaffold slices/<id>.md
-em slice sync <id>            # after wiring note "slices/<id>.md" into the .em
-em slice sync --all           # re-sync every doc in the model directory
-em slice list [--status <s>] [--pattern <p>] [--context <c>] [--tag <t>] [--format json] [--full]
-em slice show <id> [--body] [--format json]
-em slice search "<query>" [--pattern <p>] [--status <s>] [--context <c>] [--tag <t>] [--format json] [--full]
-em slice update <id> [--status <s>] [--bump-version]
-em migrate <model-dir> [--dry-run] [--report <path>]   # one-time upgrade from a pre-1.0 model
-```
-
-`em validate <file>` also validates every doc in `slices/` by default (`--skip-slices` to opt out).
-
 ---
 
 ## Grammar
@@ -49,6 +37,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
 }
@@ -68,7 +57,16 @@ arrow From Element -> To Element    # explicit cross-slice edge (overrides infer
 ### 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.**
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
@@ -156,7 +154,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
@@ -185,6 +185,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

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

@@ -0,0 +1,123 @@
+# 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**,
+  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 the **Slice inventory** (every slice, pattern, doc 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)*
@@ -178,6 +181,26 @@ 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 (`# TBD` in the `.em`, mirrored in the state
+file's Open Questions), never guessed. 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.

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,10 @@ 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 (or regenerate from `em slice list`). -->
-| # | Slice | Pattern | Status | Design doc |
-|---|-------|---------|--------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | {{status}} | [slices/{{slice-id}}.md](slices/{{slice-id}}.md) |
+<!-- 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) |
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

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

@@ -3,15 +3,13 @@ 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.
-
-This is the body template only — `em slice new` injects the required frontmatter block above
-this content (id, pattern, status, version, sliceElement, and the generated search fields).
-Pattern and status live there now, not as prose here — see reference/frontmatter.md.
 -->
 
 # Slice: {{Slice Name}}
 
+- **Pattern:** {{State Change | State View | Automation | Translation}}
 - **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
+- **Status:** {{draft | reviewed | ready-to-implement}}
 
 ## Intent
 {{Why this slice exists — the user or business goal it serves, in one or two sentences.}}