@milehimikey/em 1.19.7 → 1.21.0

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.19.7
+em-version: 1.21.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.19.7
+em-version: 1.21.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

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

@@ -39,7 +39,9 @@ difference is what you do with what you find: extract *builds* a model from the
    (or the status the user says corresponds to shipped code) for whichever slices are in scope.
    Checking a `draft` or `ready-to-implement` slice against code is a wasted walk — ratified or
    not, nobody has built to it yet; tell the user and skip it rather than reporting "drift"
-   against it.
+   against it. (GH #400: the ONE exception is a deliberate pre-ship advisory run — see
+   `--preview` under step 5 below — not a reason to treat this precondition as optional for an
+   ordinary post-ship sweep.)
 3. The codebase to check: the state file's **Existing system refs** (populated during
    `extract`, if this model came from one) or ask the user for the repo path if not set. Record
    it if missing. In a headless/scheduled run with no user to ask, default to the repository
@@ -335,6 +337,32 @@ been through this) instead of just trusting `implementedIn`. Legal only for `sta
 with a link, and itself refuses if an unruled finding for that slice still exists at this
 revision — the mechanical proof this step comes only after rulings, not before.
 
+**Pre-ship advisory mode: `--preview` (GH #400).** The certify step above is legal only for a
+**shipped** slice (`status: implemented`/`shippedVersion:` + `implementedIn:`) — precondition 2
+reflects that this phase ordinarily walks shipped code. `--preview` is the deliberate exception:
+the SAME doc-resolution and findings-check read, legal for a slice that hasn't shipped yet
+(the shipped/`implementedIn:` preconditions are waived), and it **never writes anything** —
+no `conformedVersion`/`conformedAt`/`conformedOn`, ever, regardless of outcome:
+
+```
+em slice conform <model-name>.em <slice-key> --at <target-repo revision> --preview
+```
+
+Use this to run a conform sweep against your OWN implementing branch before it merges — catching
+spec/code drift while you can still fix it on the same branch, rather than after shipping. The
+walk itself (steps 1-4 above) is unchanged; only the certify step's preconditions differ. Output
+is ephemeral by default (nothing is written, not even to `conformance/`); pass
+`--write-findings` to persist the run's own unruled findings as a normal
+`conformance/<date>-<slice-key>-preview-findings.json` (this is deliberate — `docs/cli.md`'s
+`em slice conform --preview` section documents the exact shape and naming). Know before opting
+in: the written file has no sibling report (`report` is synthetic), so `em conform-supersede`
+refuses to rule on it — unruled entries in it gate certify/`set-conformance` at that revision
+until you rule them in the file by hand, delete the snapshot, or author the sibling report.
+`em state set-conformance` and the unruled-findings gates are unaffected by
+this mode either way: a default preview run writes nothing for them to read, so it can never
+block a later certify or `set-conformance` call. There is no `--slice-ready` integration for this
+mode yet.
+
 End of run: update the state file's `Last conformance:` marker with
 
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.19.7
+em-version: 1.21.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
@@ -88,16 +94,29 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    shape — reshape it with the "Reshaping an existing model" checklist. Then the **intent test**
    per command (would a business person say this name at this step in the story? an endpoint-shaped
    name fails), the **question test** per view (write the question it answers; no question, no
-   read model; a child view only when its query needs what the parent view lacks), and the
+   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"), 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` and `automation-split-by-outcome` lints are the mechanical half; 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
@@ -130,6 +149,13 @@ Goal: a structurally complete, **validated** model with correct patterns and swi
    that reads it; another model/system reads it → mark it `public`; only an automation reads
    it → nothing, it's internal by design. No new keyword — reachability is already what `ui` and
    `public` mean.
+   **Per `view`, also ask whether each of its sources earns its place (GH #398):** for every
+   `from "E"` on the view, does E add, change or remove a row here — or only fill a column on a
+   row some other event already created? The latter is the views-as-lookups smell (methodology
+   reference, "Views as lookups"): drop E as a source and have the event that creates the row
+   carry the field instead. `view-lookup-source` flags the cross-context instances of this
+   mechanically; a lookup from the view's own context (no `@Context` mismatch to key on) only
+   this by-eye check catches.
    **Per translation fed from another model, declare what it consumes (MIL-235):** write
    `translation Order Intake consumes checkout:event.order-submitted`. The ref is
    `<modelKey>:<kind>.<slug>`, where kind is `event` or `view` and the target is marked `public`

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.19.7
+em-version: 1.21.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

@@ -96,6 +96,18 @@ it is fine to finish a round with `# TBD`s still parked.
   read model* warnings: real systems do record fire-and-forget events. In an as-is model that is
   a **finding about the system**, not a modelling mistake — never invent a reader to silence it
   (that would be desired state). Park it in the Decisions log and carry the warning.
+  **Expect lookup-style sources too.** A lifted model will faithfully reproduce the projection's
+  lookup joins — a view wired to `from "Order Created"` only because the current query joins the
+  orders table to get `customerName`, not because this view owns any row that event changes. Wire
+  it as-is (current-state-only stance: that join is how the system behaves today); don't fix it
+  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. **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.19.7
+em-version: 1.21.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-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-implement
-em-version: 1.19.7
+em-version: 1.21.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
@@ -52,7 +52,12 @@ routing table (§7) is what names the skill set for each pattern.
 Preconditions (tool check, model location) are the same as every other phase — see
 `../event-modeling-shared/reference/operating-principles.md` — but this phase additionally
 requires the target slice to already be ratified; if it isn't, stop and say so rather than
-starting on unratified work.
+starting on unratified work. The one documented exception is **inline ratification** (GH #399,
+`reference/implement.md` §1a): for an internal (non-public-touching, non-engagement) slice whose
+doc is already `reviewed`, drafting code on the same branch ahead of the human's `em slice
+ratify` is sanctioned — provided you never flip the gate yourself and re-confirm
+`--slice-ready` reads `true` before treating the slice as done. `event-modeling-engagement` is
+unchanged by this: it still requires every dispatched slice ratified before its branch is cut.
 
 End of phase: PR merged, slice doc flipped to `status: implemented` with `implementedIn`
 filled, `em slice index <model-name>.em` run to refresh `README.md`'s Slices table. Implement

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

@@ -46,15 +46,82 @@ A warning whose code is in this list blocks; any other warning never does — `c
 
 Because of that list, `ready` can be `false` with every `gates` entry `true` (a `both-ends-of-a-flow/*` warning on one of the slice's own elements, say). Don't work it out from `gates`: read **`blockedBy`** (schema `1.5`, GH #377), the codes that flipped `ready`, `[]` exactly when it is `true`, and report those codes with the `false` gates when you hand the slice back.
 
-**`ready: false` means stop** — with one named exception: a slice already `status: implemented`
-with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false` (its
-`statusReady` gate fails because nothing is newly ratified), and that specific case is
-re-implementation/repair, not a blocker — see §3's third mode before treating it as one. For
+**`ready: false` means stop** — with two named exceptions. First: a slice already `status:
+implemented` with `driftSignal: in-sync` or `uncertified` (MIL-214) also reads `ready: false`
+(its `statusReady` gate fails because nothing is newly ratified), and that specific case is
+re-implementation/repair, not a blocker — see §3's third mode before treating it as one. Second:
+under **inline ratification** (§1a) a slice doc that's only `status: reviewed` — not yet
+`ready-to-implement` — is a sanctioned starting point for drafting code on the SAME branch, with
+the explicit, non-negotiable condition that you treat nothing as actually ratified, and open
+nothing for merge, until a human has run `em slice ratify` and `--slice-ready` reads `true` for
+real; §1a names exactly which slices qualify and what that condition requires in practice. For
 every other `false`, report which `gates`
 entries are `false` and what `blockedBy` names (and any `diagnostics` entries concerning this
 slice) and hand the slice back to the humans. Never make the gate pass yourself — checking an open-question box, flipping
-`status`, or editing frontmatter are ratification decisions, and ratification happens in a
-facilitated session, not in an implementation branch.
+`status`, or editing frontmatter are ratification decisions, made by a human in a ratification
+session, never by you running `em slice ratify` on their behalf. That session is usually a
+separate doc-only PR, merged before an implementation branch is even cut — but it doesn't have
+to be: **inline ratification** (GH #399, §1a below) lets the session be the PR review of the
+very branch you're implementing on, for internal slices. Either shape, the rule here is the
+same: you never flip the gate yourself, whatever branch you're on.
+
+### 1a. The inline variant: ratifying on the implementation branch
+
+Most of this document assumes the ordinary shape — a slice is already `ready-to-implement` when
+you start, ratified in its own prior PR, and §1's gate reads `true` before you write a line of
+code. **Inline ratification** is the documented alternative
+(`docs/process.md`'s
+["Inline ratification" section](https://github.com/milehimikey/em/blob/main/docs/process.md#inline-ratification-approval-as-the-ratification-session)):
+draft the slice doc *and* build it on the same branch, spec commits first, and let the human's
+review of that one PR be the ratification session — which means you are, deliberately and
+sanctioned, building for most of that branch's life against a doc that reads `ready: false`.
+What doesn't change: you still never flip `status` yourself, never run `em slice ratify` on the
+human's behalf, and never write a word of the ratification record — see §1's second named
+exception for the precise condition this depends on. What's different is sequencing and tiering:
+
+- **Draft the doc first, then build on the same branch.** Commit the slice doc (through the
+  normal `slice` phase), get it reviewed (`em slice review --by`, flipping it to `status:
+  reviewed` — a human has to do this part too, same as always) before any implementation code,
+  even though doc and code will both live on one branch and merge in one PR. Writing code before
+  the doc exists, or before a human has looked at it, is retrofit — the exact failure mode inline
+  mode is named after avoiding — whether or not anyone ever checks for it.
+- **You may keep building past a `reviewed`-but-not-yet-`ready-to-implement` doc, but nothing is
+  ratified until `em slice ratify` actually runs.** `--slice-ready` keeps reading `false` the
+  whole time you're building — that's expected, not a signal to stop, as long as the doc's
+  `status` is `reviewed` (not `draft`: an un-reviewed doc is never a valid base, inline or not).
+  On an inline branch the human typically runs `em slice ratify --no-ref` as part of approving
+  the PR (`--no-ref` because the branch is headed for a squash/rebase merge) — not something you
+  do for them, and not something you should expect to have happened before the PR is up for
+  review. Before you report the slice done, or treat §6's merge-time flip as legitimate,
+  re-check `--slice-ready` yourself and confirm it now reads `true` with `ratifiedBy:` set — if
+  it still doesn't, the slice isn't ratified yet and you say so instead of proceeding.
+- **A post-signature doc edit still trips the hash check.** `ratifiedHash` doesn't know or care
+  which branch it was computed on — if something changes the doc's body after the human has
+  signed it (a gap surfaces, §4), `--slice-ready` and `em slice ratify` both refuse the stale
+  signature exactly as they would across two PRs. Route it through `em slice revise --withdraw`,
+  review, re-ratify (§4) — inline doesn't shortcut that loop, it just means the re-sign happens
+  on the branch you're already on instead of a fresh one.
+- **Not every slice is a candidate.** A slice owning a `public` command, event or view
+  (`isPublicTouchingSlice`) keeps the separate doc PR — the contract is a promise to consumers
+  who never see your implementation diff, and `em slice ratify` already refuses a public-touching
+  slice without `--meaning-unchanged`/`--contract-change` regardless of which branch it runs on.
+  An engagement-dispatched slice is never inline either — engagements structurally need every
+  contract frozen before any implementer branch is cut, so the engagement skill never offers you
+  this shape (it is explicitly unchanged by GH #399 — this is a note for your own judgment
+  outside an engagement, not something to apply inside one).
+- **Pre-ship advisory conform is the loop's natural checkpoint.** Before the PR merges, a human
+  (or you, if asked) can run `em slice conform <model>.em <key> --at <rev> --preview` — the
+  pre-ship, non-certifying mode (GH #400): same doc-resolution and findings-check read as a real
+  certification, legal before the slice has shipped, never writes `conformedVersion:`/
+  `conformedAt:`/`conformedOn:`. It's advisory and ephemeral by default (nothing written unless
+  `--write-findings` is passed) — a cheap "did I just drift from the doc I signed" look before
+  asking for the PR review that will also be the ratification.
+- **The ordering advisory is informational, not yours to act on.** `em refs --check-order`
+  (GH #399) can report whether a commit on this branch touched code before the doc's
+  `ratifiedRef` — a retrofit smoke signal for the human reviewing the PR. It's advisory, never a
+  gate, and nothing in this skill asks you to run it or react to its output; if a human shows you
+  a `code-before-ratification` result, treat it the same as any other gap raised against your
+  work (§4), not as something to silence.
 
 ## 2. Read the spec
 

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-review
-em-version: 1.19.7
+em-version: 1.21.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

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

@@ -22,12 +22,15 @@ em render <file>                                                    # transpile
 em render <file> -o, --out <path>                                   # output path (extension picks the format)
 em render <file> -T, --format <fmt>                                 # output format (svg, png, pdf, ...)
 em render <file> --slice <name>                                     # render only this slice, redrawn in its own canonical pattern shape (default out: slices/<kebab-slug>.svg)
-em render <file> --storyline <name>                                 # render only this storyline: its slices in order, preceded by dimmed stub columns for what they read from outside it (and the end state of a storyline it comes `after`) (default out: storylines/<kebab-slug>.svg)
+em render <file> --storyline <name>                                 # render only this storyline: its own slices in order, nothing from outside it (default out: storylines/<kebab-slug>.svg)
+em render <file> --map                                              # render every storyline to storylines/<kebab-slug>.svg plus a draggable canvas of them all, with the flow between storylines, at storylines/map.html (-o picks the html path)
 em render <file> --emit-dot                                         # print the generated DOT instead of rendering
 em render <file> --keep-empty-lanes                                 # keep the API lane even when empty
 em export <file>                                                    # export a versioned JSON snapshot of the normalized model
 em export <file> -o, --out <path>                                   # write to a file instead of stdout
 em export <file> --slice <key>                                      # export only this slice's object (pattern/fields/doc) instead of the whole model (export key, MIL-128) — refuses only if THIS slice has an error; an unrelated slice's breakage elsewhere in the model doesn't block it (see docs/cli.md)
+em export <file> --doc-json                                         # emit the structured slice-doc export (GH #401) instead of the model snapshot: per slice the frontmatter join plus the parsed sections as data (fields, invariants, scenarios, error flows, open questions) and a model-level invariant catalog. Own schema version; whole model only (does not combine with --slice)
+em export <file> --include-html                                     # with --doc-json, include each slice doc's rendered HTML body (excluded by default; the authored body never appears in a plain export)
 em api generate <file>                                              # write the TypeSpec contract for the model's public commands, events and views to <model dir>/contracts/<model key>.tsp
 em api generate <file> -o, --out <path>                             # write to this path instead of <model dir>/contracts/<model key>.tsp
 em api generate <file> --stdout                                     # print the contract instead of writing it
@@ -68,6 +71,7 @@ em slice stub-all <file> --implemented-in <url>                     # PR/commit
 em slice stub-all <file> --dry-run                                  # list what would be stubbed/wired without writing anything
 em slice index <file>                                               # rewrite the model's sibling README.md's GENERATED Slices table from `em export`'s slice facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated
 em slice index <file> --check                                       # verify the table is current; exit non-zero on drift without writing (CI)
+em slice index <file> --full                                        # every lifecycle column (reviewed/ratified/owner/tracking/implemented/conformed) instead of the reader's five
 em slice mark-implemented <file> <slice-key> <pr-url>               # flip a slice doc's frontmatter to `status: implemented` / `implementedIn: <pr-url>` — the one edit an implementing agent makes to a ratified doc at merge (MIL-103, replaces the em-sdd-bridge `em-sdd-mark-implemented` script; see reference/implement.md §6). Applies only to a `ready-to-implement` doc (MIL-277: a `draft`/`reviewed` doc refuses — ratify first). Also records the shipped version beside the link (MIL-284): `shippedVersion:`, `shippedRef:` (the doc's `ratifiedRef:`, when it has one) and `shippedOn:`, and opens the next version as a `draft` when an Open Question was deferred to it (MIL-283). Idempotent on the same URL — also after that draft opened; refuses to overwrite a different one; never touches the doc body except to re-open those deferred questions
 em slice mark-implemented <file> <slice-key> <pr-url> --on <date>   # merge date recorded as `shippedOn:`, YYYY-MM-DD (default: today, local date; MIL-284)
 em slice mark-implemented <file> <slice-key> <pr-url> --json        # print a JSON document instead of text: { path, changed, implementedIn, nextDraft: { version, reopened[] } | null } (GH #285)
@@ -98,10 +102,13 @@ em slice defer <file> <slice-key> [question] --decision <text>      # what this
 em slice defer <file> <slice-key> [question] --from-issue <text>    # defer a captured `issue "..."` on this slice instead of a doc Open Question (case-sensitive substring of its text)
 em slice defer <file> <slice-key> [question] --by <name>            # who deferred it
 em slice defer <file> <slice-key> [question] --on <date>            # deferral date, YYYY-MM-DD (default: today, local date)
-em slice conform <file> <slice-key>                                 # record per-slice-per-version conformance certification: sets `conformedVersion:`/`conformedAt:`/`conformedOn:` on a slice doc (MIL-214) — the fact `driftSignal: in-sync` now depends on. Legal only for a shipped slice (`status: implemented`, or any status with a `shippedVersion:` — MIL-283) with an `implementedIn:` link; `conformedVersion:` is the shipped version. Idempotent on the same (version, --at) pair; a different --at simply overwrites (a later re-certification is normal — there's no way for em to tell 'later' from 'earlier' for an arbitrary revision string, so there's no --force to reach for). Refuses when the conformance/<date>[-<name>]-findings.json file matching --at still has an unruled finding in scope for this slice; --skip-findings-check overrides with a loud notice.
+em slice conform <file> <slice-key>                                 # record per-slice-per-version conformance certification: sets `conformedVersion:`/`conformedAt:`/`conformedOn:` on a slice doc (MIL-214) — the fact `driftSignal: in-sync` now depends on. Legal only for a shipped slice (`status: implemented`, or any status with a `shippedVersion:` — MIL-283) with an `implementedIn:` link; `conformedVersion:` is the shipped version. Idempotent on the same (version, --at) pair; a different --at simply overwrites (a later re-certification is normal — there's no way for em to tell 'later' from 'earlier' for an arbitrary revision string, so there's no --force to reach for). Refuses when the conformance/<date>[-<name>]-findings.json file matching --at still has an unruled finding in scope for this slice; --skip-findings-check overrides with a loud notice. GH #400: --preview runs the same doc-resolution and findings-check read for a slice that hasn't shipped yet — the shipped/implementedIn gates are waived and NOTHING is ever written to the doc; output is ephemeral (text or --json) unless --write-findings opts into persisting a normal findings file.
 em slice conform <file> <slice-key> --at <rev>                      # the target-repo revision this certification sweep diffed against — or, when what was exercised is not a commit that stays reachable (a per-PR environment under squash/rebase merges, a build or image), an opaque `<kind>:<id>` such as build:1234 or deploy:eu-1-2026-10-15 (GH #261); recorded verbatim, skipped by git-reachability checks
 em slice conform <file> <slice-key> --on <date>                     # certification date, YYYY-MM-DD (default: today, local date)
 em slice conform <file> <slice-key> --skip-findings-check           # certify even with unruled findings in scope — prints a loud notice on stderr
+em slice conform <file> <slice-key> --preview                       # GH #400: pre-ship advisory mode — waives the shipped-status/`implementedIn:` gates, writes NOTHING to the doc (no conformedVersion/conformedAt/conformedOn, ever); ephemeral by default, --write-findings opts into persisting a normal findings file. --skip-findings-check has no effect in this mode (preview never refuses on findings)
+em slice conform <file> <slice-key> --write-findings                # with --preview: persist the preview's own unruled findings as conformance/<on>-<slice-key>-preview-findings.json
+em slice conform <file> <slice-key> --json                          # with --preview: print a JSON document instead of the text report
 em changelog <file>                                                 # render a model's git history as a business-readable ledger (see docs/cli.md)
 em changelog <file> --from <rev>                                    # start the walk at this revision (inclusive)
 em changelog <file> --to <rev>                                      # end the walk at this revision (inclusive; default HEAD)
@@ -145,6 +152,7 @@ em watch <file> -T, --format <fmt>                                  # output for
 em watch <file> --keep-empty-lanes                                  # keep the API lane even when empty
 em watch <file> --serve                                             # serve a live viewer with instant push-reload (no polling)
 em watch <file> --port <n>                                          # port for --serve (default 5173)
+em watch <file> --storyline <name>                                  # GH #309 (deferred from #277): filter the live view to one storyline's subset — the same subset `em render --storyline` draws (its own slices in order, plus dimmed stub columns for what they read from outside it and the `after` end state). Whenever the model declares any storylines the viewer also offers a picker to switch to the full model or another declared storyline, live, without restarting. An unknown name errors, listing the declared storylines; requires --serve
 em validate <file>                                                  # check a model against event-modeling rules
 em validate <file> --list-issues                                    # print only open `issue` diagnostics (slice, element, line, text)
 em validate <file> --list-divergences                               # print only accepted-divergence annotations (slice, element, line, text) — never fails the build
@@ -164,6 +172,7 @@ em refs <file>                                                      # check that
 em refs <file> --reachable-from <rev>                               # the branch or commit every ref must be an ancestor of (e.g. origin/main)
 em refs <file> --waive <slice-key>                                  # excuse this slice's non-ancestor/unresolved/undecidable results from the exit code (repeatable); still reported
 em refs <file> --waive-file <path>                                  # a baseline file of slice keys to waive, one per line (`#` comments allowed); missing file = no waivers
+em refs <file> --check-order                                        # advisory-only (GH #399): for every slice doc with a ratifiedRef, report whether a commit between the branch's fork point and ratifiedRef already touched code other than the doc itself — a retrofit signal for inline ratification (spec written to describe code that already exists). History is rewritable, so this NEVER affects the exit code or `ok`, and is never a validate gate — see docs/process.md's inline-ratification section
 em refs <file> --json                                               # print a JSON document instead of the text report (see docs/cli.md)
 em ledger <file>                                                    # check slice docs' version: field agrees with their content across two git revisions (opt-in CI check, MIL-89 — never part of `em validate`, see docs/ci.md)
 em ledger <file> --from <rev>                                       # baseline revision
@@ -268,15 +277,25 @@ em mcp                                                              # start an M
 em skill install                                                    # copy the event-modeling skill bundle into .claude/skills/ (event-modeling, event-modeling-discover/-design/-implement/-conform/-review, event-modeling-shared); across a structural bundle change (e.g. the MIL-157 split of the old single event-modeling/ directory into this six-directory bundle), `em skill sync` is the migration path — --force now performs the same reconcile (MIL-180)
 em skill install -f, --force                                        # overwrite an existing installation, reconciling added/updated/removed files within the bundle's own managed directories the same way `em skill sync` does — never touching an unrelated sibling skill (MIL-180)
 em skill install --no-agents-md                                     # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill install --skills-dir <dir>                                 # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill install --agents-dir <dir>                                 # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 em skill sync [path]                                                # update the vendored .claude/skills/ event-modeling skill bundle in [path] to match the installed em package (overwrites unconditionally; local edits are never merged, MIL-93)
 em skill sync [path] --no-agents-md                                 # skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)
+em skill sync [path] --skills-dir <dir>                             # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill sync [path] --agents-dir <dir>                             # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 em skill check [path]                                               # check [path]'s em skills for drift against the installed em package: the em Claude Code plugin's pin (settings + this machine's marketplace registry) when the repo declares it, and the vendored .claude/skills/ bundle when present; exits non-zero on any mismatch (CI-ready, MIL-93, MIL-231)
 em skill check [path] --json                                        # print a JSON document instead of the text report (see docs/cli.md)
 em skill check [path] --ci                                          # also fail (exit 1) when the declared plugin is not registered on this machine (implied by CI=true in the environment); without it that finding prints the install commands on stderr and exits 0
+em skill check [path] --skills-dir <dir>                            # where the vendored skill bundle lives, relative to the repo root (default .claude/skills; .agents/skills when that exists and .claude/skills does not — GH #412)
+em skill check [path] --agents-dir <dir>                            # where the four em sub-agent definitions live, relative to the repo root (default .claude/agents, or .agents/agents beside an .agents/skills bundle — GH #412)
 em ci init <model>                                                  # install .github/workflows/em-ci.yml (PR gates: em validate, em slice index --check, em coverage --strict, em ledger, em skill check, em glossary --fail-on-conflicts, plus a push-triggered status-badge rebuild) and em-conform.yml (scheduled, advisory-only conformance cadence) — same install discipline as `em skill install`: marker-delimited, idempotent, --check for CI self-verification (MIL-166, see docs/ci.md). Give it a system.yaml (or its directory) instead of a model to cover every model in the system: one workflow, per-model jobs, a conform matrix (MIL-233)
 em ci init <model> --tests <dir>                                    # test directory the coverage/status steps scan for INV-* citations
 em ci init <model> -f, --force                                      # replace an existing workflow file that has no GENERATED markers, or a managed block generated for a different set of models
 em ci init <model> --check                                          # verify both files match the current preset; exit non-zero on drift without writing (CI)
+em storyline split <file>                                           # move each inline `storyline "X" { … }` block into its own storyline model file <slug>/<slug>.em (a `storyline "X" [source]` header, then the block's slices) and leave the one-line declaration `storyline "X" [after "Y"]` in the root (GH #421). Slice docs stay under the root's slices/. A storyline declared in several blocks is left alone (merge them first)
+em storyline split <file> --storyline <name>                        # split only this storyline
+em storyline split <file> --dry-run                                 # print what would be written without touching anything
+em storyline split <file> -f, --force                               # overwrite a storyline model file that already exists
 em storyline suggest <file>                                         # advisory (GH #290): propose `storyline` blocks for a model that has none — one per distinct slice `source "url"`, the remaining slices grouped by the view-instance chains (`again`) they feed — printed as a unified diff on stdout (apply with `patch -p1` or `git apply`); never writes the model
 em upgrade <file>                                                   # bring a model repo authored under an older em (1.6 forward) up to the installed version: an ordered list of mechanical steps (skill bundle, reaction shape, state-file bullets, generated CI blocks, constitution scaffold) plus a human list of things no command can safely decide by itself (MIL-219, see docs/upgrading.md). Dry-run by default; --apply makes one git commit per applicable step, refusing on a dirty working tree
 em upgrade <file> --apply                                           # apply every applicable mechanical step, one git commit each, then a final `Em version:` commit
@@ -303,12 +322,14 @@ context Name                     # an event swimlane row (bounded context / aggr
 storyline "Name" [source "url"] [after "Other"] {   # optional chapter grouping slices (see Storylines)
   slice "Name" { ... }
 }
+storyline "Name" [after "Other"] [in "path.em"]      # a storyline MODEL: its slices live in <slug>/<slug>.em (see Storylines)
 
 slice "Name" [source "url"] {    # one vertical time step (a column); source is optional
   ui   Free Text @Persona        # screen; @Persona picks its row (defaults to first/"User")
   command Free Text              # state-changing request (API band)
   invariant INV-ORD-1 "Rule"     # rule guarding the command/event just above (see Clauses)
   view Free Text from "Event A", "Event B"   # read model fed by event(s)
+  view Free Text from "Event A" updates from "Event B", "Event C"   # B, C keep rows current: read, never drawn (see Clauses)
   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
@@ -352,6 +373,14 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   previous instance of V that also reads E), and EVERY site needs a reader at or after it (add `view V again from "E"`
   after the last site, or `event-unread` warns for that site). The same name in a different context
   is still a `duplicate-name` warning.
+- **`updates from "Event", …`** (views only, GH #414): the subset of a view's sources that only keep a
+  row current or remove it (a due date moved, an address changed, a loan returned). They are folded
+  into the view's `from` for every check — `derived from`, completeness, the generated built-from
+  list — but never drawn as arrows: the diagram shows the line from the event that puts work on the
+  list, and lists the rest under "Kept current by". The author chooses the triggers: `view Holds To
+  Fulfill from "Hold Placed", "Tool Returned" updates from "Hold Collected", "Hold Cancelled"`.
+  Valid on an `again` instance too. A to-do view with more than one or two inbound arrows is missing
+  this split.
 - **`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
@@ -489,7 +518,19 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   declared `type T`, with `derived from "Child Created", "Child Deleted"`, embeds a child entity:
   each field of `T` must trace to a named event (`fields-completeness/view-field-no-source`
   otherwise); a field also traces one level through the declared element type of an array field
-  on the event (`optionValues: VariantOptionValue[]`), no deeper and with no path syntax. An
+  on the event (`optionValues: VariantOptionValue[]`), no deeper by same name. When the event
+  renamed or flattened the field, declare the element field's source by **path** into the named
+  event, as the unquoted form of the same clause (GH #383): `attributeValueIds: string[] derived
+  from values[].attributeValueId` — a `.`-joined chain of identifiers, each `[]`-suffixed exactly
+  when it steps through an array field (the marker is enforced against the event field's actual
+  arrayness). The path must resolve on a named event — every named event is tried; non-leaf
+  segments must be `type`-valued fields — and the leaf field's type must match the element
+  field's (array markers stripped); an unresolved path or leaf-type mismatch is
+  `fields-completeness/view-field-no-source` (implicit same-name nested tracing matches names
+  only; the explicit path form earns the stronger leaf-type check). The quoted event-list form
+  and the unquoted path form are mutually exclusive on one field — both at once is a parse error.
+  A plain (non-collection) view field may carry the same path form, checked the same way against
+  the view's source events — never silently exempt like a bare `derived` field. An
   element field the projection computes rather than copies (an audit stamp from event metadata,
   say) is marked `derived` on the `type` field itself — bare or `derived from "<events>"`, same
   syntax as a view field (GH #382): it is then skipped by `view-field-no-source`, and a traced
@@ -530,8 +571,15 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   Slices keep their file-order timeline position; a slice outside any storyline is allowed;
   storylines don't nest and a repeated name continues that storyline (its slices join it; a continuation may not add or change
   `source`/`after` — parse error). The full render draws a
-  labelled band above the slice headers; `em render --storyline "Name"` draws one story alone, with the
-  elements it reads from outside as dimmed stub columns. `em export` carries `slice.storyline` and
+  labelled band above the slice headers; `em render --storyline "Name"` draws one story alone — its own
+  slices only, nothing from outside it — and `em render <root>.em --map` puts every story's real
+  diagram on one draggable canvas with the flow between stories (`after` thick, reads dashed and
+  labelled). **Storyline models (GH #421):** `storyline "Name" [after "Other"] [in "path.em"]` with no
+  body declares a storyline whose slices live in `<slug>/<slug>.em` — a file that starts with
+  `storyline "Name" [source "url"]` and holds slice blocks only — with its docs in `<slug>/slices/`;
+  the root is the compile unit (always give em the root), and `em storyline split <root>.em` turns
+  inline blocks into files, moving each story's docs. A storyline that reads another declares `after`
+  it (`storyline-reads-without-after`). `em export` carries `slice.storyline` and
   `model.storylines[]`; `em query slices --storyline`; `em slice index` adds a Storyline column. Once
   any storyline exists a slice outside every one is the advisory warning `slice-outside-storyline`.
   `after "<other>"` reads the storyline as if its slices followed the referenced storyline's last
@@ -857,6 +905,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 <!-- GENERATED:validate-rules:start -- run `npm run docs:generate` to refresh, do not hand-edit -->
 | Code | Severity | Title | Fix |
 |---|---|---|---|
+| `again-restates-sources` | warning | Continuation restates sources an earlier instance already read | Name only the events that changed the view since the previous instance on the `again` line; the view's field sources are the union across instances, so nothing is lost (docs/dsl.md#view--again). |
 | `alternative-events-no-command` | error | Alternative events without a command | Add the command whose decision records one of the alternatives, in the same slice. |
 | `arrow-backward` | error | Backward arrow | Restructure so the target comes later. |
 | `arrow-unresolved-source` | error | Arrow source unresolved | Fix the arrow's source name. |
@@ -897,6 +946,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `fields-completeness/view-field-no-source` | warning | View field with no source | Add the field to a source event, or remove it from the view. |
 | `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
 | `frontmatter-invalid` | warning | Invalid or missing frontmatter | Add the required frontmatter keys, or add a frontmatter block. |
+| `frontmatter-status-unrecognized` | warning | Unrecognized slice status | Set `status:` to one of draft, reviewed, ready-to-implement, implemented. |
 | `grid-collision` | error | Band collision | Split the colliding elements into separate slices. |
 | `invariant-without-scenario` | warning | Invariant cited by no scenario | Cite the INV id in the Given/When/Then (or title) of the scenario that exercises it, or add one. |
 | `invariants/declared-in-both` | warning | Invariant declared in the model and in a slice doc | Keep the model's `invariant` line; in the doc, cite the ID and elaborate instead of restating it as a `**INV-…:**` rule. |
@@ -940,6 +990,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `storyline-after-cycle` | error | Storyline `after` cycle | Remove an `after` clause so no storyline comes after itself. |
 | `storyline-after-out-of-order` | error | Backward timeline (storyline declared above the one it comes after) | Move the storyline block below the storyline it comes `after`, or restructure the feed. |
 | `storyline-after-unknown` | error | `after` names an unknown storyline | Name a storyline declared in this model, or drop the `after` clause. |
+| `storyline-reads-without-after` | warning | Storyline reads another without declaring `after` it | Add `after "<the storyline it reads>"` to the reading storyline (or to one between them); if the two stories are parallel on purpose, accept it on the shape exit gate (docs/storyline.md). |
 | `system-manifest-invalid` | error | Seam manifest invalid | Fix the manifest: `systemSchemaVersion: "2.0"`, `models:` with a readable `source` per model, and nothing else (`seams:`/`owner:` moved into the models — run `em upgrade`). |
 | `system-manifest-outdated` | warning | Seam manifest is schema 1.0 | Run `em upgrade <model>.em --apply` once: it moves `seams:` into `consumes` clauses and `owner:` onto each model header, and rewrites the manifest to 2.0. |
 | `system-model-key-mismatch` | error | Manifest model key differs from the export's `model.key` | Rename the manifest's `models:` key to the computed key the message prints. |
@@ -954,6 +1005,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `view-again-without-earlier` | error | `again` without an earlier declaration | Declare the view plainly the first time it appears. |
 | `view-from-future-event` | error | Backward timeline (view reads a future event) | Move the source to a later `view X again` instance. |
 | `view-from-unresolved` | error | Unknown event source | Fix the `from` reference to name an existing event. |
+| `view-lookup-source` | warning | View reads an event only as a lookup | Carry the field on the event that creates this view's own row instead; if this is a genuine cross-context row change, accept it on the shape exit gate (docs/validation.md#the-shape-exit-gate) rather than fixing it (docs/patterns.md#state-view). |
 | `view-no-source` | warning | Read model without source | Add `from "Event"`, or place the view in a slice with an event. |
 <!-- GENERATED:validate-rules:end -->