@milehimikey/em 1.20.0 → 1.22.0

package/.claude/agents/em-implementer.md

@@ -18,6 +18,16 @@ You are the em implementer. You build one slice, in one worktree, on one branch,
 - Write code and tests inside that slice's package, as the constitution's layout rule describes it.
 - Every invariant and scenario in the slice doc gets a test that cites its `INV-*` id.
 
+## Bindings file
+
+Part of this slice's definition of done, in the same PR: write or update `conformance/bindings/<slice-key>.yaml`, beside the model, per `docs/bindings.md`'s schema — you just wrote the code, you know which file and identifier anchors each element and each `INV-*` invariant's enforcement and test sites. It's a plain file you author like any other in your PR; no `em` command writes it. Before you report the slice done, verify it:
+
+```
+em conform bindings check <model>.em --repo <path> --slice <slice-key> --exit-code
+```
+
+Exit 0 is required. If it fails, fix the bindings file — a wrong `ref`, a stale `file`/`identifier` pair — never report the slice done with a failing binding.
+
 ## Tracking key
 
 If your prompt carries a tracking key (an issue-tracker key such as `PROJ-123`, or a URL), the lead has already resolved it for this slice: the slice doc's own `tracking:` wins over the engagement's. Use it as given:

package/.claude/agents/em-validator.md

@@ -22,6 +22,7 @@ Run each one and record pass or fail:
 5. No diff under `slices/**`, `*.em`, `constitution.md`, or `engagements/`. Use `git diff --name-only <base>...HEAD`.
 6. The pull request body cites the slice doc.
 7. The pull request title equals the title you were given, exactly (`gh pr view <pr> --json title`). A mismatch fails the check and quotes both. If no title was given, skip this check and say so.
+8. `conformance/bindings/<key>.yaml` exists beside the model, and `em conform bindings check <model.em> --repo <worktree path> --slice <key> --exit-code` exits 0 (GH #450).
 
 ## Output
 

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when the user runs `/event-modeling` (with or without a phase name), or wants to resume an
   event-modeling session without specifying which part of the process applies. Reads the model's

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-conform
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when checking a ratified event model (and its slice docs) for drift against the codebase
   that implements it — advisory only, never a gate, never an unprompted edit — or when walking
@@ -28,9 +28,12 @@ duplicating them.
 In short: run `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis` to
 compute the in-scope slice set (diff-scoped by default, via `Last conformance:` + the target
 repo's changed paths mapped through each slice doc's `implementedIn:`) and seed the scratch
-model in one step; for each in-scope slice, gather code evidence *before* comparing to the model
-or doc; write the as-is picture into that scratch model (`<model-name>-asis.em`, reusing the
-canonical model's names wherever the code matches them); run `em diff <model-name>.em
+model in one step; for each in-scope slice, check for a `conformance/bindings/<key>.yaml` first
+(GH #450) — verify it with `em conform bindings check` and scope the walk through it when it
+exists, backfill it from this walk's own evidence when it doesn't — then gather code evidence
+*before* comparing to the model or doc; write the as-is picture into that scratch model
+(`<model-name>-asis.em`, reusing the canonical model's names wherever the code matches them);
+run `em diff <model-name>.em
 <model-name>-asis.em --json` and let `em` decide the structural deltas; classify every finding
 (real drift / model gap / internal inconsistency / uncertainty) with cited evidence; write
 `conformance/<date>-report.md` **and its structured twin `conformance/<date>-findings.json`**

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

@@ -94,7 +94,7 @@ e.g. a PR link, deterministically matches nothing). It prints one JSON document
 ```json
 { "lastConformance": { "date": "...", "revision": "..." } | null,
   "changedPaths": ["..."],
-  "candidateSlices": [ { "key": "checkout", "matchedBy": "implementedIn", "paths": ["..."] } ],
+  "candidateSlices": [ { "key": "checkout", "matchedBy": "implementedIn", "paths": ["..."], "file": null } ],
   "unmappedPaths": ["..."] }
 ```
 
@@ -104,6 +104,20 @@ your in-scope set for step 2. If `lastConformance` is `null` (first run) or you
 `changedPaths`/`unmappedPaths` both empty) — the tool makes this call for you, no need to
 special-case it yourself.
 
+**Storyline models (GH #451).** A model may split its storylines into their own files — a root
+declares `storyline "Name" [after "Other"]` with no body, and the storyline's slices live in
+`<slug>/<slug>.em` (`docs/dsl.md`'s "Storyline models" section). `em conform-scope` already
+compiles the root plus every storyline file it declares as ONE model
+(the same way every other `em` command does — a storyline file never compiles on its own), so
+scoping via `implementedIn` needs no special handling. What DOES change: each `candidateSlice`'s
+`file` names the storyline file that slice's body lives in — posix, relative to the model's
+directory — or `null` for a slice in the root file. This is which physical file you anchor on in
+step 2 and which scratch file you write the as-is picture into in step 3 (`--seed-asis` seeds one
+scratch file per physical file, not just the root — see there). Don't confuse a slice's `file`
+with its doc's path: slice docs for a storyline model live under that storyline's own
+`slices/` folder, but `em` finds them by key across every folder regardless, so doc resolution
+itself needs no extra care.
+
 **`unmappedPaths` is your judgment queue, not a dead end.** A changed path the tool couldn't
 place mechanically (`implementedIn` stale, a URL-only link, code that moved) still might belong
 to an in-scope slice — a quick Grep for the path's obvious symbols against the slice docs/model
@@ -119,6 +133,31 @@ keeps a recurring conform run cheap; don't invent a smarter trigger.
 
 For each slice in scope:
 
+**Check for an existing bindings file first (GH #450).** `conformance/bindings/<slice-key>.yaml`,
+beside the model, records this slice's own prior evidence — file and identifier per model
+element, and per `INV-*` invariant's enforcement/test sites (`docs/bindings.md`'s schema). Two
+cases, mutually exclusive:
+
+- **It exists:** verify it before walking anything by hand —
+  `em conform bindings check <model-name>.em --repo <target-repo-path> --slice <slice-key>`.
+  A binding that still checks out is evidence you don't need to re-derive; **scope the rest of
+  this slice's walk through it** — re-read only what the check reports failing (`file not
+  found`/`identifier not found`, an unknown `ref`) plus whatever `em conform-scope`'s
+  `changedPaths` (step 1) says moved since `implementedIn`. This is what turns a recurring
+  conform walk incremental instead of a full re-derivation every time — don't throw that away by
+  re-walking evidence the file already gives you clean.
+- **It doesn't exist:** the common shape for a slice an external or ticket-driven implementer
+  shipped without ever running `em` (`docs/bindings.md` is written so that implementer can still
+  author one by hand from its own ticket spec; this backfill is the safety net for the ones that
+  didn't, or for any slice that shipped before GH #450). Walk the slice normally (the numbered
+  steps below) and, once you've gathered that evidence, **write
+  `conformance/bindings/<slice-key>.yaml` from it** — the same file an implementer would have
+  written, now backfilled from your conform evidence instead of from the implementer's own
+  knowledge of the code. This is advisory tooling catching up a gap, not a model or doc edit: it
+  needs no ratification and doesn't change this phase's advisory-only stance (see "Stance"
+  above) — you're recording where code already lives, not deciding what it should do. From the
+  next conform run on, this slice follows the "it exists" branch above.
+
 1. Read the slice's **doc** (`slices/<slice-name>.md`) alongside its elements in the `.em`.
    This tells you the vocabulary to anchor on and the claims to check — not the answer.
 2. Walk the code and **record evidence before comparing**:
@@ -139,6 +178,20 @@ For each slice in scope:
      as missing. This is the *general*, idiom-level version of the next bullet — prefer citing
      an actual `divergence` annotation when the element carries one; fall back to this idiom
      note only when it doesn't.
+   - **`updates from` sources (GH #451) — housekeeping evidence, not trigger evidence.** A view
+     declared `view X from "A" updates from "B", "C"` (`docs/dsl.md`'s `updates from` section)
+     splits its sources into what put a row on the list (`from`) and what keeps an existing row
+     current or removes it (`updates from`). The two need different evidence: a `from` source is
+     what an automation/processor reacting to this view should fire on, or what a reader expects
+     to see a NEW row appear for — missing evidence there is the usual structural/spec drift. A
+     `updates from` source is expected to have an update/delete handler for the SAME row, never a
+     "new item created" or "automation triggered" site — don't report the absence of trigger-type
+     evidence for an `updates from` source as drift; that is literally what the clause says it
+     isn't. `em export`'s `from` list is the union of both (so `em diff`'s structural comparison
+     sees every source regardless of which list it's in — folding `from`/`updates from` into each
+     other is NOT itself a structural change `em diff` would catch), but the *diagram* draws no
+     arrow for an `updates from` source and the *evidence walk* above should read the same way:
+     check it as "does this row get kept current/removed", not "does this cause a new row".
    - **Accepted divergences:** before treating any finding as drift, check whether the
      relevant canonical element already carries a `divergence "..."` annotation (visible in
      the `.em`, in `em export --json`'s `divergence` field, or — for a structural finding — as
@@ -161,8 +214,15 @@ For each slice in scope:
 3. Write what you found into the scratch model (`<model-name>-asis.em`, see below) — start it
    with `em conform-scope <model-name>.em --repo <target-repo-path> --seed-asis`, which
    byte-copies the canonical `.em` to `<model-name>-asis.em` and ensures `*-asis.em` is
-   gitignored (idempotent — safe to pass on every run). **Then replace only the in-scope
-   slices** with the as-is picture, leaving out-of-scope slices byte-identical. This is not an optimization:
+   gitignored (idempotent — safe to pass on every run). **Storyline models (GH #451):** when the
+   slice you're rewriting has a non-null `file` in step 1's `candidateSlices` (its body lives in
+   a storyline file, not the root), `--seed-asis` also wrote a scratch copy of THAT file — the
+   `seeded.storylineFiles` entry naming it — and the copied root's declaration already points at
+   it. Edit that storyline file's own `-asis` sibling, never `<model-name>-asis.em` (it has no
+   body for that slice to rewrite) and never the canonical storyline file (that corrupts the
+   real model, not a scratch copy). **Then replace only the in-scope slices** with the as-is
+   picture, leaving out-of-scope slices byte-identical, in whichever scratch file(s) hold them.
+   This is not an optimization:
    `em diff` matches slices by name, so a scratch model containing *only* the in-scope slices
    reports every other canonical slice as `slice-removed` plus one `element-removed` per
    element — a phantom-removal flood on every diff-scoped run, which is the exact false drift
@@ -405,7 +465,12 @@ each call adds its own stamp rather than overwriting the last.
   directory as `.event-modeling.md`). Always seeded as a copy of the canonical model with only
   the in-scope slices rewritten (step 2) — `em conform-scope --seed-asis` does the seeding and
   the gitignoring (`*-asis.em`, idempotent) mechanically, never built up from nothing and never
-  hand-maintained. It's regenerated every conform run.
+  hand-maintained. It's regenerated every conform run. **Storyline models (GH #451):** a split
+  model gets ONE scratch file per physical file — `<model-name>-asis.em` for the root, plus a
+  `-asis` sibling for every storyline file the root declares (`seeded.storylineFiles` names
+  them) — never just the root; the copied root's `in` clause already points at each sibling, so
+  `em diff <model-name>.em <model-name>-asis.em` reads the whole scratch set as one model, same
+  as the canonical root reads the whole canonical set.
 - **Report location:** `conformance/<YYYY-MM-DD>-report.md` in the model directory. One file
   per run; don't overwrite a prior date's report. Its findings go in the same-stem `-findings.json`; gates read every same-revision findings file, so per-slice runs may write `<date>-<name>-findings.json`, and a ruling is written to the file the report names. The same-revision lookup uses the report's OWN revision (its `Target repo: … @ <rev>` header line; the caller's `<rev>` / `--as-of` only when the report has none).
 - **Red note wording:** `issue "conformance: <what's wrong, plainly>"` — plain enough that
@@ -447,6 +512,13 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **A scratch model holding only the in-scope slices** — `em diff` reads every omitted
   canonical slice as removed, so a diff-scoped run drowns in phantom removals. Seed from the
   canonical model and rewrite only the slices you walked.
+- **Editing a storyline file's canonical copy as if it were the scratch model (GH #451)** — for
+  a slice whose `file` isn't the root, the scratch copy is that storyline file's OWN `-asis`
+  sibling (`seeded.storylineFiles`), never `<model-name>-asis.em` (no body there to rewrite) and
+  never the canonical storyline file itself (that's the model, not a scratch copy of it).
+- **Treating an `updates from` source like a `from` source during the evidence walk** — a
+  missing "new row appears" or "automation fires" site is not drift for a source the view only
+  lists under `updates from`; check it for row-update/removal evidence instead (step 2).
 - **Reporting uncertainty as drift** — "I couldn't find the enforcement site" is an
   uncertainty, never a finding against the model.
 - **Editing the model or a slice doc without ratification** — conform proposes; the user
@@ -457,6 +529,12 @@ whatever cadence the user wants (see `docs/ci.md` for a scheduled-run recipe).
 - **Re-deriving what `em diff` already decided** — once you have the JSON, use it; don't
   eyeball the two `.em` files yourself looking for structural differences the tool already
   computed for you.
+- **Re-deriving evidence a verified bindings file already gives you (GH #450)** — when
+  `em conform bindings check` passes for a slice's `conformance/bindings/<key>.yaml`, walking
+  every element and invariant by hand anyway defeats the point of the file; scope through it
+  (step 2) instead.
+- **Skipping the backfill because a slice has no bindings file** — the absence is the signal to
+  write one from this walk's own evidence, not a reason to leave the gap for next time.
 - **Re-litigating an accepted divergence** — a non-null `acceptedDivergence` on a diff entry
   (or a `divergence` annotation on the element behind a spec/internal finding) means this exact
   question was already reasoned through and ratified. Classify it as Accepted divergence and

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing
@@ -71,7 +71,13 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    optional `after "<storyline>"` timeline clause: `em-dsl.md`) so the diagram gets a band per
    story and `em render --storyline "Name"` can show one alone; slices keep their file order, and
    a model can adopt storylines incrementally (`slice-outside-storyline` is only an advisory
-   warning) — but name them before you slice, not after. Then group events into **contexts** (bounded contexts /
+   warning) — but name them before you slice, not after. **Once the storylines are named, give
+   each its own file** (GH #421): run `em storyline split <root>.em` so the root keeps the
+   vocabulary and the storyline list with its flow (`storyline "Name" [after "Other"]`) and each
+   story's slices live in `<slug>/<slug>.em` with its docs in `<slug>/slices/` — do this before any
+   doc is wired, so nothing moves twice. **A storyline that reads another story's events declares
+   `after` it** (`storyline-reads-without-after` flags the ones you miss); two stories that run in
+   parallel read nothing from each other. Then group events into **contexts** (bounded contexts /
    aggregates) — ask which events share a consistency boundary and who owns them. Classify each
    slice as one of the 4 patterns. **Share the slice between every automation or translation and
    the command it triggers** (the reaction — processor/translation — together with the command
@@ -91,17 +97,26 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    read model; a child view only when its query needs what the parent view lacks), the
    **views-as-lookups check** per `from "E"` on a view (does E add, change or remove a row here? if
    it only fills a column, put the column on the event that creates the row and drop E — see
-   `../event-modeling-shared/reference/methodology.md`, "Views as lookups"), and the
+   `../event-modeling-shared/reference/methodology.md`, "Views as lookups"), then the
+   **trigger / housekeeping split** on what is left (*which event is the reason this row appears?*
+   that one stays in `from`; every event that only keeps a row current or removes it moves to
+   `updates from` — the view still reads it, the diagram no longer draws it; a to-do list with more
+   than one or two inbound arrows is missing this split), the **continuation check** per `view X
+   again` (it names only the events that changed the view since the previous instance, never the
+   first instance's list again), and the
    **conditional-invariant signal** (invariants or fields that apply only "if `<field>` is set"
-   mean two intents in one command: split it). The `timeline-entity-clustered`,
-   `command-second-intent`, `automation-split-by-outcome` and `view-lookup-source` lints are the
-   mechanical half (the last one only catches the cross-context cases — do the check by eye too); the
-   1.18.0 design exit gate is `em validate --shape`. Shape the model first, scaffold docs after: a rename,
+   mean two intents in one command: split it). Read each story on its own render and on the canvas
+   (`em render <root>.em --map`), not on the full timeline. The `timeline-entity-clustered`,
+   `command-second-intent`, `automation-split-by-outcome`, `view-lookup-source`,
+   `again-restates-sources` and `storyline-reads-without-after` lints are the
+   mechanical half (the lookup one only catches the cross-context cases — do the check by eye too); the
+   design exit gate is `em validate --shape`. Shape the model first, scaffold docs after: a rename,
    split or merge from the reshape would orphan docs already wired with `--wire`. The `slice` phase is unchanged (timeline order).
 3. **Elaborate scenarios — first pass (step 6).** Scaffold every slice's doc now, one per
    slice, none skipped: `em slice new "<slice name>" --pattern <state-change|state-view|
    automation|translation> --swimlane "<Persona> → <Context>" --wire <model>.em` writes
-   `slices/<slice-name>.md` at `status: draft` (the same command, flags, and `--wire`
+   `slices/<slice-name>.md` at `status: draft` (into the slice's own storyline folder when the model
+   is split — pass the ROOT model to `--wire`) (the same command, flags, and `--wire`
    note-binding the `slice` phase's step 2 below documents in full). A slice whose only element
    is a `view X again` instance is a **continuation** (MIL-208), not a slice to scaffold —
    `--wire` refuses it and names the originating slice holding `X`'s first declaration; its

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
   past-tense events, storyboarding the happy path, finding the commands and read models — or when
@@ -68,7 +68,7 @@ Goal: a draft model of events, storyboard, commands, and views. Loose is OK; str
    **Close the loop before leaving this step:** every event from step 3 must be read by at least one
    read model. Walk the event list and ask, for each one, *"who looks at this, and what do they do
    with it?"* An event with no answer is either missing its read model or shouldn't be recorded —
-   both are worth raising with the user rather than leaving dangling.
+   both are worth raising with the user rather than leaving dangling. Keep the draft in one file with inline `storyline` blocks; the design phase splits it into one file per story (`em storyline split`) once the names are settled.
 
 End of phase: write/refresh the `.em`, render it, update `.event-modeling.md` (steps done,
 decisions, open questions — run `em state set-phase model` rather than hand-editing `Current

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

@@ -103,7 +103,11 @@ it is fine to finish a round with `# TBD`s still parked.
   here, that would be inventing desired state. Note it as a finding in the Decisions log the same
   way as an unread event, and leave it for `model`/`slice` to apply the views-as-lookups rule
   (`../../event-modeling-shared/reference/methodology.md`, "Views as lookups") once the as-is
-  model is agreed.
+  model is agreed. **Housekeeping handlers are `updates from`, as-is:** when the projection code
+  handles an event only to update or delete a row it already holds (a status flip, a due date
+  moved, an address changed, a row removed), write that event in `updates from "…"`, not `from` —
+  that is what the code does today, it keeps the field tracing complete, and the as-is render then
+  shows the one line that puts work on the list instead of every handler.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
   listeners, outbound syncs, inbound webhooks. Model each as a reaction sharing its slice with
   the `command` + `event` it triggers (`reaction → command → event`, per `em-dsl.md`) — the

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-engagement
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the

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

@@ -47,6 +47,7 @@ Validator (em-validator, <model>):
 | diff footprint inside the slice package | PASS |
 | no diff under `slices/**`, `*.em`, `constitution.md`, `engagements/` | PASS |
 | PR body cites the slice doc | PASS |
+| `conformance/bindings/<key>.yaml` exists + `em conform bindings check --slice <key> --exit-code` | PASS |
 
 Reviewer (em-reviewer, <model>): <findings list verbatim, or NO FINDINGS>
 Critic (em-critic, <model>): <findings list verbatim, or NO FINDINGS>

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-implement
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on
@@ -28,8 +28,10 @@ ships in the originating doc's PR); ship the endpoint a
 model doesn't show; surface every gap to the user instead of deciding it silently; cover every
 `INV-<MNEMONIC>-n` and every scenario with tests, proving the citations before merge with
 `em coverage <model>.em --slice <key> --tests <dir> --strict` (the default form skips a
-`ready-to-implement` slice); in spec-kit projects, allocate via
-em-sdd-bridge (redirect mode) and never run `/speckit.specify`.
+`ready-to-implement` slice); write or update the slice's `conformance/bindings/<key>.yaml`
+(GH #450, `docs/bindings.md`'s schema) and verify it with `em conform bindings check <model>.em
+--repo <path> --slice <key> --exit-code` before calling the slice done; in spec-kit projects,
+allocate via em-sdd-bridge (redirect mode) and never run `/speckit.specify`.
 
 **Gate: no constitution, no first slice.** The constitution is the project's ratified house rules
 — stack and architectural shape (including which implementation skill each slice pattern routes

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

@@ -300,6 +300,20 @@ or seem small — see §10.
   you didn't touch the `.em`, so this only fails if something else broke).
 - Nothing between the slice doc and the code was committed as a source of truth (see §9 —
   work containers are ephemeral; generated or symlinked specs are renderings).
+- **The slice's bindings file is written or updated** (GH #450): `conformance/bindings/<slice-
+  key>.yaml`, beside the model, per [`docs/bindings.md`](https://github.com/milehimikey/em/blob/main/docs/bindings.md)'s
+  schema. You just wrote the code — you know which file and identifier anchors each element
+  this slice's doc declares (`ref: <kind>.<slug>`, bare, no `<slice-key>/` prefix) and each
+  `INV-<MNEMONIC>-n` invariant's enforcement and test sites. This is a file contract, not an
+  `em`-run write: author or hand-edit the YAML directly, the same way you'd write any other file
+  in your PR. Verify it before calling the slice done:
+  ```bash
+  em conform bindings check <model>.em --repo <path> --slice <slice-key> --exit-code
+  ```
+  Exit 0 is required — fix the file (a wrong `ref`, a stale `file`/`identifier` pair) rather than
+  shipping a binding that doesn't check out. A continuation key (§5, an `again` view instance)
+  has no bindings file of its own; its elements and invariants are bound inside the originating
+  slice's file alongside the rest of that doc's bindings.
 
 ## 6. At merge: the lifecycle flip
 

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-review
-em-version: 1.20.0
+em-version: 1.22.0
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through
@@ -15,8 +15,16 @@ description: >-
 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 polling and no idle churn between edits.
+URL it prints and share their screen — updates appear the moment you save, with no polling and no
+idle churn between edits.
+
+What that URL opens depends on the model. A model that declares storylines opens on the
+**storyline canvas** (`http://localhost:5173/map`): every storyline's own diagram in a draggable
+frame, the flow between storylines drawn between frames, reloaded live on every save with the
+layout kept. A frame's **open ›** drills into that storyline — the viewer on its own slices and
+nothing from outside it — and **‹ Storylines** in the header returns to the canvas. A model
+without storylines opens on the timeline (`http://localhost:5173/?svg=<model-name>.svg`). Never
+send a room to the full timeline of a storyline model; the storyline is the unit people read.
 
 The viewer navigates like a map — drag to pan, scroll/pinch to zoom, **Fit** to reset — and its
 **Review mode** steps through slices one at a time (see the `review` phase below). A save that
@@ -34,10 +42,14 @@ speculation.** Don't propose this phase proactively; it exists for facilitated r
 non-engineer stakeholders in the room, not routine model editing.
 
 Start the same live server as `watch`: `em watch <model-name>.em -o <model-name>.svg --serve`
-(run_in_background). Open the printed URL, click **Review mode** in the header, and share the
-screen. Use Prev/Next (or the left/right arrow keys) to step through slices in declaration
-order — each one pans/zooms into view with everything else dimmed, so the room's attention
-tracks one slice at a time.
+(run_in_background). Open the printed URL and share the screen. With storylines, review one
+storyline at a time: open it from the canvas (or start inside it with `--storyline "<name>"`),
+then click **Review mode** in the header — Prev/Next walk that storyline's slices only. Between
+storylines, **‹ Storylines** returns to the canvas, where the arrows between frames are the
+order to take them in. Without storylines, click **Review mode** on the timeline. Use Prev/Next
+(or the left/right arrow keys) to step through slices in declaration order — each one
+pans/zooms into view with everything else dimmed, so the room's attention tracks one slice at
+a time.
 
 **When a State View slice is on screen, ask who reads it (MIL-215):** a person or client in the
 room → the `ui` should draw it; another system → `public`; only an automation → nothing, it's