@milehimikey/em 1.16.1 → 1.18.0

package/plugin/shared/reference/em-dsl.md

@@ -23,6 +23,7 @@ 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> --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
@@ -69,29 +70,34 @@ em slice index <file>                                               # rewrite th
 em slice index <file> --check                                       # verify the table is current; exit non-zero on drift without writing (CI)
 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)
 em slice review <file> <slice-key>                                  # flip a slice doc's frontmatter to `status: reviewed` and record `reviewedBy:`/`reviewedOn:` — the FIRST of the two human gates (MIL-201, docs/process.md#the-slice-lifecycle-gates): the room walked this slice and every open question it raised is resolved. Ratification is a separate, later gate (`em slice ratify`). Legal from `status: draft`; idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded; refuses a doc already `ready-to-implement`/`implemented`; never touches `version:` or the doc body
 em slice review <file> <slice-key> --by <name>                      # the reviewer's (or facilitator's) name
 em slice review <file> <slice-key> --on <date>                      # review date, YYYY-MM-DD (default: today, local date)
-em slice ratify <file> <slice-key>                                  # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) that makes who ratified, and when, a first-class recorded fact. The review gate is a check on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: a doc at `reviewed` passes; a `ready-to-implement` doc only when the same signer is completing their own record (since 1.15.0, MIL-283 — a new sign-off is a new version: `em slice revise`); any other status — a `draft` that never went through `em slice review` — is refused unless --skip-review is passed. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded, and (MIL-284) a same-pair re-run on a doc whose body moved after sign-off; never touches `version:` or the doc body
+em slice review <file> <slice-key> --roster <path>                  # ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)
+em slice ratify <file> <slice-key>                                  # flip a slice doc's frontmatter to `status: ready-to-implement` and record `ratifiedBy:`/`ratifiedOn:` — the handoff sign-off (MIL-165, docs/process.md#the-slice-lifecycle-gates) that makes who ratified, and when, a first-class recorded fact. The review gate is a check on the doc's current `status:`, not on whether `reviewedBy:`/`reviewedOn:` are populated: a doc at `reviewed` passes; a `ready-to-implement` doc only when the same signer is completing their own record (since 1.15.0, MIL-283 — a new sign-off is a new version: `em slice revise`); any other status — a `draft` that never went through `em slice review` — is refused unless --skip-review is passed. Idempotent on the same --by/--on pair; refuses to overwrite a different one already recorded, and (MIL-284) a same-pair re-run on a doc whose body moved after sign-off; never touches `version:` or the doc body. Inside a git work tree also records `ratifiedRef:` (HEAD, refusing a doc with uncommitted changes) and always `ratifiedHash:`; with --no-ref (GH #255) only the hash — for a repo whose squash/rebase merges would leave the ref unreachable — and git is not consulted
 em slice ratify <file> <slice-key> --by <name>                      # the ratifier's name
+em slice ratify <file> <slice-key> --no-ref                         # record ratifiedHash: only, no ratifiedRef: (GH #255) — the signed content keeps its identity, nothing points at a commit a squash or rebase merge would orphan; the uncommitted-changes check does not apply
 em slice ratify <file> <slice-key> --on <date>                      # ratification date, YYYY-MM-DD (default: today, local date)
-em slice ratify <file> <slice-key> --skip-review                    # ratify without a recorded review — prints a loud notice on stderr
+em slice ratify <file> <slice-key> --roster <path>                  # ratifier roster to check --by against (GH #259; default: the nearest ratifiers.yaml above the model, none = unrestricted)
+em slice ratify <file> <slice-key> --skip-review                    # ratify without a recorded review — prints a loud notice on stderr and records `reviewSkipped: <status>` on the doc (GH #260) so the bypass is visible to later readers, `em export` and `--slice-ready --json`; cleared by `em slice revise`
 em slice ratify <file> <slice-key> --meaning-unchanged              # API-first sign-off (MIL-238): this version does not change what the public contract means — records `meaningConfirmed: true`; required (or --contract-change) on a slice touching a `public` element
 em slice ratify <file> <slice-key> --contract-change <why>          # API-first sign-off (MIL-238): a consumer must read this change differently, and why — records `contractChange: "<why>"`
-em slice revise <file> <slice-key>                                  # open the next version of a slice doc as a `draft` (MIL-283): bumps `version:`, flips `status:` to `draft`, clears the prior version's review and sign-off (`reviewedBy/On`, `ratifiedBy/On/Ref/Hash`, `meaningConfirmed`/`contractChange`) and re-opens the questions deferred to the new version. The shipped version stays shipped: `implementedIn:` and the `shipped*` keys are untouched (written first on a doc shipped before 1.15). Applies to `status: implemented` (the shipped case) and to a ratified `ready-to-implement` doc (ratification withdrawn, never shipped); a `ready-to-implement` doc with no `ratifiedBy:` reopens as draft at the same version; `draft`/`reviewed` refuse — the next version is already open. The new version then takes the normal road: `em slice review --by`, `em slice ratify --by`. Questions queued by `em slice defer` for the new version (GH #236) are injected into its Open Questions. A ratified, never-shipped doc REFUSES without --withdraw (revising withdraws the only implementable version; queue a question with `em slice defer` instead)
+em slice revise <file> <slice-key>                                  # open the next version of a slice doc as a `draft` (MIL-283): bumps `version:`, flips `status:` to `draft`, clears the prior version's review and sign-off (`reviewedBy/On`, `ratifiedBy/On/Ref/Hash`, `meaningConfirmed`/`contractChange`) and re-opens the questions deferred to the new version. The shipped version stays shipped: `implementedIn:` and the `shipped*` keys are untouched (written first on a doc shipped before 1.15). Applies to `status: implemented` (the shipped case) and to a ratified `ready-to-implement` doc (ratification withdrawn, never shipped); a `ready-to-implement` doc with no `ratifiedBy:` reopens as draft at the same version; `draft`/`reviewed` refuse — the next version is already open. The new version then takes the normal road: `em slice review --by`, `em slice ratify --by`. A ratified, never-shipped doc REFUSES without --withdraw (revising withdraws the only implementable version; record a question with `em slice defer` instead — it sits outside the hash, GH #253). With --keep-version (GH #262) a ratified, never-shipped doc reopens as a draft at the SAME `version:` — same status flip and sign-off clearing, no bump — for a project that holds every slice at its initial version until a first release; refused on a shipped doc
 em slice revise <file> <slice-key> --withdraw                       # GH #236: required on a ratified, never-shipped doc — confirms withdrawing the ratification of the only implementable version
+em slice revise <file> <slice-key> --keep-version                   # GH #262: reopen a ratified, never-shipped doc as a draft at the same `version:` (no bump) — a correction before a first release, not a delta; refused on a shipped doc, whose version must stay distinct from the next one
 em slice reratify <file> <slice-key>                                # DEPRECATED alias of `em slice revise` (MIL-283, since 1.15.0; removed in a later minor). Until 1.14 this left the doc at an unsigned `ready-to-implement`; it now opens a `draft` of the next version like `revise`. The --meaning-unchanged/--contract-change flags are accepted and ignored with a notice — the API-first confirmation is taken by `em slice ratify` on the new version
 em slice reratify <file> <slice-key> --meaning-unchanged            # ignored since 1.15.0 (see above)
 em slice reratify <file> <slice-key> --contract-change <why>        # ignored since 1.15.0 (see above)
 em slice reratify <file> <slice-key> --withdraw                     # see `em slice revise --withdraw`
-em slice defer <file> <slice-key> [question]                        # record a question this version will not answer as deferred to a later version (MIL-275): rewrites the single unchecked `## Open Questions` item containing <question> as `- [x] <item> — v<current>: <decision>; deferred to v<n> (<date>[, <by>])` so `--slice-ready` passes without a guess, and mirrors it into `.event-modeling.md` (the parking lot and a dated Decisions-log bullet; the file must exist, it is never created). Idempotent; `em slice reratify` re-opens the item when it bumps to v<n>. With --from-issue <text> instead of <question> (MIL-281): promotes the single open `issue "..."` on the slice's own elements containing <text> into the doc's Open Questions as that same deferred item, mirrors it, and removes the `issue` clause from the .em — the one-command path for a question raised in a review session. On a RATIFIED (`ready-to-implement` + `ratifiedBy:`) or shipped (`implemented`) doc (GH #236) the doc is NOT edited — its body is the signed spec — and the question is queued in `.event-modeling.md` for v<N+1>; `em slice revise` / `mark-implemented` inject it into the next draft
+em slice defer <file> <slice-key> [question]                        # record a question this version will not answer as deferred to a later version (MIL-275): rewrites the single unchecked `## Open Questions` item containing <question> as `- [x] <item> — v<current>: <decision>; deferred to v<n> (<date>[, <by>])` so `--slice-ready` passes without a guess, and mirrors it into `.event-modeling.md` (the parking lot and a dated Decisions-log bullet; the file must exist, it is never created). Idempotent; `em slice reratify` re-opens the item when it bumps to v<n>. With --from-issue <text> instead of <question> (MIL-281): promotes the single open `issue "..."` on the slice's own elements containing <text> into the doc's Open Questions as that same deferred item, mirrors it, and removes the `issue` clause from the .em — the one-command path for a question raised in a review session. On a RATIFIED (`ready-to-implement` + `ratifiedBy:`) or shipped (`implemented`) doc (GH #253) the already-deferred `[x]` item is APPENDED to the doc's Open Questions — `ratifiedHash` excludes the section heading and its `deferred to v<n>` items, so the signature, `--slice-ready` and ratify's re-run stay valid, and the question is visible in the ratified doc; a pre-1.17 whole-body hash is re-stamped in the same edit. Refuses a doc whose body already fails its hash
 em slice defer <file> <slice-key> [question] --until <version>      # the version that must answer it, v<n> (greater than the doc's version)
 em slice defer <file> <slice-key> [question] --decision <text>      # what this version does instead
 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 newest conformance/*-findings.json 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> --at <rev>                      # the target-repo revision this certification sweep diffed against
+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 changelog <file>                                                 # render a model's git history as a business-readable ledger (see docs/cli.md)
@@ -127,6 +133,10 @@ em conform-supersede <file> <report-path> --locus <locus>           # who/what t
 em conform-supersede <file> <report-path> --by <name>               # who ruled on the named finding(s) (requires --locus)
 em conform-findings check <path>                                    # shape-validate a conformance/<date>-findings.json file (findingsSchemaVersion, required fields, enum values, ids sorted+unique, a ruled finding carries resolvedBy+resolvedOn) — exit 1 on shape errors. The conform skill writes this file directly alongside its report; this is how a headless run verifies what it just wrote.
 em conform-findings check <path> --json                             # print a JSON document instead of the text report
+em discover triage-check <file>                                     # validate a discovery/prd-triage.json (prdTriageSchemaVersion 1.0): shape, the shipped rubric version, every statement/storyline quote appearing verbatim in the input document, and every statement carrying a category, an outcome and (modeled/rewritten) a group + storyline — exit 1 on errors. The discover skill writes this file directly; this is how a headless run verifies it.
+em discover triage-check <file> --source <path>                     # the input PRD/spec to check quotes against (default: the file's own `source`, relative to it)
+em discover triage-check <file> --markdown                          # after a passing check, print the Markdown view of the record instead of the summary
+em discover triage-check <file> --json                              # print a JSON document instead of the text report
 em watch <file>                                                     # re-render on every save
 em watch <file> -o, --out <path>                                    # output path (extension picks the format)
 em watch <file> -T, --format <fmt>                                  # output format (svg, png, pdf, ...)
@@ -139,9 +149,20 @@ em validate <file> --list-divergences                               # print only
 em validate <file> --list-public                                    # print only commands, events and views marked `public` (slice, kind, name, line) — an integration-surface audit, never fails the build
 em validate <file> --fail-on-issues                                 # exit non-zero if the model has any open `issue`s (opt-in — issues are warnings and don't block by default)
 em validate <file> --slice-ready <key>                              # readiness gate for one slice (export key): status ready-to-implement, doc resolvable via note binding, zero unchecked Open Questions, a recorded ratifiedBy, and — for a slice touching a `public` element — a current contracts/<model key>.tsp; exits non-zero if not ready (MIL-87, MIL-259, MIL-238)
+em validate <file> --require-ratified-hash                          # with --slice-ready (GH #256): strict mode — a ready-to-implement doc with no `ratifiedHash:` is NOT ready (`slice-ready-missing-ratified-hash`, error; `ready: false` in --json). Off by default so docs ratified before em 1.15 keep passing; turn it on once legacy docs are re-ratified
+em validate <file> --strict                                         # promote advisory lints (GH #293: scenario-quality warnings) to errors: they fail the run and, with --slice-ready, block readiness
+em validate <file> --roster <path>                                  # with --slice-ready (GH #259): the ratifier roster to check `ratifiedBy` against (default: the nearest ratifiers.yaml above the model; none = unrestricted). A name the roster does not permit for the slice's context is `ratified-by-not-in-roster` (error)
+em validate <file> --check-signed-bodies                            # opt-in (GH #257): compare every slice doc that records a `ratifiedHash:` — ready, implemented, any status — to its body; a mismatch is `slice-body-changed-since-ratification` (error). A pre-1.17 whole-body hash with an intact body passes; a deferral written by `em slice defer` is outside the hash. The one check that still watches a shipped doc's signed content
+em validate <file> --shape                                          # GH #282: run only the advisory shape-family lints (storyline shape) and print rule / count / first ref / docs anchor; exit 0 always. With --json: `shapeSchemaVersion` 1.0 with per-rule finding arrays
+em validate <file> --waive-file <path>                              # with --shape: a baseline file (`<rule-code> <slice-key>` per line, or a bare slice key for every shape rule; `#` comments) whose shape findings are listed as waived and not counted; missing file = no waivers
 em validate <file> --json                                           # print a JSON document instead of text — works on a model WITH errors, unlike `em export` (MIL-128, see docs/cli.md); exit codes are unchanged
 em migrate <file>                                                   # rewrite the old two-slice Automation/Translation shape into the merged single-slice shape MIL-120 made canonical (see docs/cli.md)
 em migrate <file> --write                                           # apply the rewrite to the file (default: dry run — report only, write nothing)
+em refs <file>                                                      # check that every commit a slice doc records — `ratifiedRef:`, `shippedRef:`, a bare `conformedAt:` — still resolves and is reachable from a branch (GH #258): per doc, per field, `ancestor` / `not-ancestor` / `unresolved` / `undecidable` (a shallow clone never passes). Squash and rebase merges orphan the PR-branch HEAD ratify recorded; nothing else in em resolves a ref. Opt-in CI check, like `em ledger` — never part of `em validate`. Local object store only, no network. Kinded `conformedAt` values (build:…) are skipped; docs with no ref fields are not reported
+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> --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
 em ledger <file> --to <rev>                                         # compare revision (default: current working tree)
@@ -187,6 +208,7 @@ em query slices <files> --status <s>                                # the slice'
 em query slices <files> --context <c>                               # match a slice with an event in this @Context
 em query slices <files> --persona <p>                               # match a slice with a ui in this @Persona
 em query slices <files> --tag <t>                                   # match a slice with an event carrying this tag key
+em query slices <files> --storyline <name>                          # match a slice declared in this `storyline` block
 em query slices <files> --json                                      # print a JSON document instead of the text report
 em query invariant <files>                                          # declaring slice + doc facts for one INV-* id, and (with --tests) its test citations
 em query invariant <files> --id <inv-id>                            # the INV-* id to look up
@@ -210,6 +232,9 @@ em engagement new <file> <slug> --tracking <key>                    # an issue-t
 em engagement new <file> <slug> --force                             # overwrite an existing engagement file with this slug
 em engagement plan <file> <slug>                                    # the engagement's build plan: dependency levels over model.edges (loops-to excluded), and per slice its readiness, branch impl/<key>, base (always main — MIL-280), and any hold
 em engagement plan <file> <slug> --json                             # print a JSON document instead of text (same document as the MCP engagement_plan tool)
+em engagement foundation <file> <slug>                              # GH #240: is the foundation PR (implement.md §8) actually in the code for the events this engagement's slices emit and consume? A text scan of --code: an event is present when a file carries an identifier derived from its name (OrderPlaced / order_placed / ORDER_PLACED / order-placed), its model fields and tag fields are then looked for in those files. Per event: present | incomplete (missing-field / missing-tag, named) | missing-event — so "foundation absent" and "foundation incomplete" are different reports. Exits 1 unless every event is present. Proves the contract was written down, not that it type-checks
+em engagement foundation <file> <slug> --code <dir>                 # the target repository (or the directory the constitution's "where a slice's code lives" rule points at)
+em engagement foundation <file> <slug> --json                       # print a JSON document instead of text (same document as the MCP engagement_foundation tool)
 em engagement set <file> <slug> <key>                               # the only write path to the Ledger: set one slice's state (and optionally branch/base/pr); idempotent; merged is terminal; --state held records a human hold
 em engagement set <file> <slug> <key> --state <state>               # one of: planned | building | validating | review | awaiting-merge | merged | held | gap
 em engagement set <file> <slug> <key> --branch <name>               # the slice's branch
@@ -218,6 +243,12 @@ em engagement set <file> <slug> <key> --pr <url>                    # the slice'
 em engagement status <file> <slug>                                  # the Ledger joined with each slice doc's current status, plus whether the engagement is closable
 em engagement status <file> <slug> --json                           # print a JSON document instead of text (same document as the MCP engagement_status tool)
 em engagement close <file> <slug>                                   # set status: closed — refuses unless every slice is merged (recorded or inferred) or gap
+em roster init <file>                                               # write ratifiers.yaml beside the model, seeded from the names already recorded in the slice docs' `ratifiedBy:`/`reviewedBy:` (whole-model entries; narrow them with `contexts:` by hand). Refuses to overwrite an existing file unless --force; `em upgrade`'s grandfathered placeholder is not a name
+em roster init <file> --roster <path>                               # write the roster here instead of <model dir>/ratifiers.yaml
+em roster init <file> --force                                       # overwrite an existing roster file
+em roster check <file>                                              # check EVERY slice doc's recorded signers against the ratifier roster (GH #259) - `ratifiedBy` on ready-to-implement and implemented docs, `reviewedBy` on any doc - the whole-model CI gate that `--slice-ready <key>` (one ready slice) is not. Exit 1 on any violation or an invalid roster; no roster file = nothing to check, exit 0. The `grandfathered ...` placeholder is exempt (counted)
+em roster check <file> --roster <path>                              # roster to check against (default: the nearest ratifiers.yaml above the model)
+em roster check <file> --json                                       # print a JSON document (per-doc results, diagnostics with refs); exit codes unchanged
 em system [target]                                                  # verify a system — every model's `consumes` refs resolved against the other models' `public` events/views, the cross-model half of "both ends of a flow" (MIL-194/MIL-235, see docs/cli.md). Reads system.yaml when given (or found in the directory), else discovers every *.em in the repo
 em system [target] --json                                           # print a JSON document instead of the text report (see docs/cli.md)
 em system codeowners [target]                                       # generate (or --check) the managed CODEOWNERS block that routes review: each model's team on its design directory, and every team that `consumes` a model's public surface on that model's contract file (MIL-234, see docs/ci.md and docs/cli.md)
@@ -242,10 +273,13 @@ em ci init <model>                                                  # install .g
 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 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
 em upgrade <file> --check                                           # exit non-zero only on a hard incompatibility (an existing but unparseable state file, an un-migratable .em shape) — writes nothing; what CI runs; the final line says why
 em upgrade <file> --json                                            # print a JSON document instead of text (dry-run/--check only, never with --apply)
+em upgrade <file> --fold-continuations                              # also run the opt-in fold-continuations step (stack consecutive continuations of one view into the first; continuationOf, doc join and index rows unchanged)
+em upgrade <file> --to-sugar                                        # (implies --fold-continuations; without --apply it is a dry run listing exactly what would fold): fold continuations into their host command slice as `view X again … shown on` lines — CHANGES continuationOf and the doc join to `<host>--again` and removes the folded slices' index rows
 ```
 <!-- GENERATED:cli:end -->
 
@@ -262,6 +296,10 @@ model "Name" [owner "Team"]      # diagram title; optional owning team(s), quote
 persona Name                     # a UI swimlane row (actor)
 context Name                     # an event swimlane row (bounded context / aggregate)
 
+storyline "Name" [source "url"] [after "Other"] {   # optional chapter grouping slices (see Storylines)
+  slice "Name" { ... }
+}
+
 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)
@@ -284,7 +322,7 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 | `ui` | persona | screen / interface | `@Persona` | `note`, `issue`, `divergence`, `{ fields }` |
 | `command` | API | state-changing request | — | `note`, `issue`, `divergence`, `renamed from`, `{ fields }`, standalone `invariant` line |
 | `view` | API | read model / projection | — | `from "Event"…`, `note`, `issue`, `divergence`, `public`, `{ fields }` |
-| `event` | context | recorded fact (past tense) | `@Context` | `note`, `issue`, `divergence`, `public`, `tag`, `renamed from`, `loops-to`, field-level `assigned`, `{ fields }`, standalone `invariant` line |
+| `event` | context | recorded fact (past tense); `event A \| B @Context` = alternative outcomes of ONE command, one slice, one shared cell | `@Context` | `note`, `issue`, `divergence`, `public`, `tag`, `renamed from`, `loops-to`, field-level `assigned`, `{ fields }`, standalone `invariant` line |
 | `processor` / `automation` / `saga` / `translation` | automation | system reaction / adapter | — | `from "…"`, `note`, `issue`, `divergence`, `{ fields }`; `translation` only: `consumes` |
 
 ### Clauses
@@ -300,6 +338,15 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   "to-do list") and pointing the reaction at that view. Name that view after the pending work
   (`Payments To Process`), never after the triggering event — a view reusing the event's name
   collides in the shared namespace and draws a duplicate-name warning.
+- **One event recorded by several commands** (two intents, one fact — `Create Product` and
+  `Create Product Variant` both ending in `Product Created`): repeat the event BARE in the later
+  slice with the same name and context. A bare repeat of an event with the same name and context is
+  ONE logical event — no `duplicate-name`, no marker (`again` stays view-only). The repeat inherits
+  the first declaration's fields, element-level `tag` clauses and `public`; declaring different ones
+  is the error `shared-event-field-mismatch`. A view's `from "E"` draws an arrow from every recording
+  site at or before it, 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.
 - **`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
@@ -431,7 +478,11 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   into doc-only prose** — the marker keeps `em export`/the model aware the field exists (the
   `doc-model-field-mismatch` doc↔model check does not compare view field tables at all today —
   see the slice template's field-table guidance — so this is an export-side win specifically,
-  not yet a doc-drift check).
+  not yet a doc-drift check). **Collection fields (GH #288):** a view field typed `T[]` for a
+  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). No add/remove/key clauses — `em slice sync` writes a `Collection of` note plus
+  one Given/Then scenario stub per named event in the view region (copy into `## Scenarios`), and `em export` sets `collection: true`.
 - **Fields:** `command Place Order { orderId: UUID, items: LineItem[], customerId }` — inline or
   one-per-line. Types are free text (no semantic checking) UNLESS the type string names a
   declared `type` (see Named types below), in which case it resolves to a structured
@@ -460,6 +511,22 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
   of relying on prose. Purely metadata — no visual marker, not validated. Don't confuse it with
   an element's `note "path.md"` (a markdown file link, not a URL).
 
+- **`storyline "Name" [source "url"] [after "Other"] { slice … }`** (GH #277) groups slices into a
+  named chapter — the main journey, and secondary stories (retire a product, extend an attribute).
+  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
+  `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
+  slice: `from`/`again`/reaction `from` resolve against the composed timeline (referenced → this), the
+  forward-only checks use it, a backward feed into the referenced storyline, an `after` cycle
+  (`storyline-after-cycle`), an unknown target (`storyline-after-unknown`) or a storyline declared above
+  the one it comes after when a flow would draw right-to-left (`storyline-after-out-of-order`) is an
+  error. Without `after`, file order is the only timeline.
+
 ### Named types
 
 `type Name { field: Type, ... }` declares a reusable structured shape at the top level (any
@@ -622,8 +689,9 @@ slice "Read Quote — created" {
   **prefer `view X again`** for every instance after the first (see Clauses) — **each instance
   carries its own consumer** (the `ui` that reads it, or a reaction), not just the last one. `again`
   instances are exempt from the duplicate-name warning even when referenced, and each reference
-  resolves to the right instance — a plain repeat only stays warning-free while nothing references it by name, and
-  resolves to the *first* declaration when something does. **Wire each event to a read model exactly
+  resolves to the right instance — a plain repeat of a view only stays warning-free while nothing references it by name, and
+  resolves to the *first* declaration when something does (the exception is a same-context event
+  repeat, which is one logical event — see above). **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.)
@@ -644,6 +712,13 @@ consumer is an obligation to ship an endpoint, no `ui` means internal-only, and
 the published integration surface — see `reference/implement.md`'s "Interface obligations"
 paragraph in the `event-modeling-implement` skill (§2).
 
+- **Continuations without ceremony (GH #287).** Several `view X again` lines may share one
+  continuation slice (they stack in the `api` cell); `view X again from "E"` written inside a
+  command's own slice is sugar for a synthesized continuation column right after it (one column per host slice, lines stacked; key
+  `<slice-key>--again`, no doc, not in `em slice index`; consumer = the slice's first `ui`,
+  or `shown on "Screen"` — required in a reaction slice with no `ui`); and a continuation slice may omit its name — it is auto-named
+  `"<View> View: <Event>"`. Instances still never connect.
+
 ### Reaction wiring — no positional gotcha
 
 A reaction's command is inferred from **same-slice presence**, exactly like `ui -> command`: put
@@ -664,7 +739,13 @@ it to the slice that displays the read model, or drop it.
 
 **Errors (must fix):**
 1. **Band collision** — two elements of the same band in one slice (e.g. two `command`s, or two
-   `ui`s in the *same* persona row). Split them into separate slices/personas.
+   `ui`s in the *same* persona row). Split them into separate slices/personas. Two events on one
+   context that are alternative outcomes of one command are NOT a split: write
+   `event A | B @Context` (identical payloads) or `oneof { event A @Context { … }  event B @Context { … } }`
+   (own fields/clauses per alternative) — one slice, one shared cell, one command, one shared context; each
+   alternative is a full event, and a standalone `invariant` after them binds to all.
+   Alternatives with no command in the slice are an error (`alternative-events-no-command`), and the same
+   command repeated across slices warns (`command-repeated-across-slices`).
 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.
@@ -762,9 +843,11 @@ 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 |
 |---|---|---|---|
+| `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. |
 | `arrow-unresolved-target` | error | Arrow target unresolved | Fix the arrow's target name. |
+| `automation-split-by-outcome` | warning | Reaction split into one slice per outcome | Model one Automation slice recording the outcomes as alternative events — `event A | B @Context` (docs/patterns.md#automation). |
 | `binding-missing-file` | warning | Doc binding points at a missing file | Create the slice doc, or fix the `note` path. |
 | `both-ends-of-a-flow/command-no-event` | warning | Command without event | Add the event this command records. |
 | `both-ends-of-a-flow/command-untriggered` | warning | Command with no trigger | Add a `ui` or the reaction that issues it, both in this slice. |
@@ -774,6 +857,8 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `both-ends-of-a-flow/ui-unbacked` | warning | `ui` with no read model or command | Add a `view` it displays, or the command it triggers. |
 | `both-ends-of-a-flow/view-unconsumed` | warning | Read model with no consumer | Add a `ui` or reaction that consumes it, or drop this instance. |
 | `code-spans-seam` | warning | Code change spans a seam | Keep one code module per model and change the two sides of a seam in separate change sets. |
+| `command-repeated-across-slices` | warning | Command repeated across slices | Merge the slices: one command with several outcomes is one slice — `event A | B @Context`. |
+| `command-second-intent` | warning | Command carries a second intent | Split the conditional rule set into its own command; both commands may record the same event (a bare repeat of the event is legal). |
 | `connection-legality/illegal-pair` | error | Illegal connection | Only ui→command→event→view→ui and view→reaction→command are legal — the message names the missing step. |
 | `consumer-not-adapted` | error | Consuming translation no longer matches the producer's public element | Update the translation's field block to the producer's current fields (a renamed field names its new name in the message). Additive producer changes never raise this — consumers tolerate unknown fields. |
 | `consumes-unknown-element` | error | `consumes` names no public element of that model | Point the ref at an element the producer marks `public` (`em export` lists them), or ask the producer to publish it. |
@@ -786,6 +871,8 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `doc-model-element-not-in-model` | warning | Doc names an element the model doesn't have | Add the element to the model, or fix/remove it in the doc. |
 | `doc-model-field-mismatch` | warning | Doc/model field mismatch | Reconcile the field table with the model's fields — names and types. |
 | `doc-model-pattern-mismatch` | warning | Doc/model pattern mismatch | Fix the doc's `pattern:` frontmatter to match the model, or restructure the slice to match the doc. |
+| `doc-names-unfed-event` | warning | Doc names an event its view does not read | Add the event to the view's `from` in the model (if the edge is real), or fix the doc's Source column / scenario. |
+| `doc-omits-fed-event` | warning | Doc omits an event its view reads | Mention the event in the view's Source column (run `em slice sync`), or drop it from the view's `from`. |
 | `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
 | `duplicate-model-key` | warning | Duplicate model key | Give each model a unique `model "Name"` so its key (and every cross-model ref) is stable. |
 | `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
@@ -797,6 +884,7 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `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. |
 | `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. |
 | `invariants/doc-cites-undeclared` | warning | Slice doc cites an undeclared invariant | Declare the ID in the model (or in a slice doc's Invariants section), or fix the citation. |
 | `invariants/duplicate-id` | error | Duplicate invariant ID | Give each model-declared invariant its own ID — a rule is declared once, on the element it guards. |
@@ -821,18 +909,27 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `public-name-not-unique` | error | Two public elements of one kind share a name | Rename one of them (or drop `public` from one): a consumer's `consumes <model>:<kind>.<slug>` must name exactly one element. |
 | `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
 | `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
+| `retry-slice-of` | warning | Slice only retries another command | Re-fire the same reaction via `view … again from` the retry-scheduled event; a different actor's override is its own slice with its own command (docs/patterns.md#automation). |
+| `scenario-then-not-outcome` | warning | Scenario's Then names no event or rejection | Make the Then bullets name the event(s) the command records, or the rejection/error it returns. |
+| `scenario-when-not-command` | warning | Scenario's When does not name the slice's command | Make the When bullet name the slice's command (for a reaction slice: the command, the reaction element, or a view of the slice) — each scenario exercises exactly one command. For a Translation, naming the translation element satisfies it. |
 | `seam-consumer-not-reaction` | error | Seam consumer is not a reaction | Point `to` at a translation/automation element (or a slice containing exactly one). |
 | `seam-crossing` | error | Change set alters a contract and its consumer together | Split the change set: land the producer's public-surface change first, then adapt the consuming model in a later change. Review on the contract file is the only override. |
 | `seam-crossing-greenfield` | warning | New public surface lands with its first consumer | Nothing to fix: a public element no consumer was bound to at the base revision is new surface, not a crossing. Later changes to it are crossings. |
 | `seam-duplicate` | warning | Duplicate seam | Remove the repeated `from`/`to` pair. |
 | `seam-endpoint-unresolved` | error | Seam endpoint does not resolve | Fix the ref to an element the named model actually exports (`em export` lists every ref), or re-declare the seam after a rename. |
 | `seam-source-not-public` | error | Seam source is not `public` | Mark the event/view `public` in its model, or point the seam at the element that is. |
+| `shared-event-field-mismatch` | error | Shared event declared with different fields, tags or public | Repeat the event bare to inherit the first declaration's fields, tags and public, or make them identical. |
 | `slice-doc/structured-section-malformed` | warning | Malformed structured section | Balance the `<!-- GENERATED:em-slice-…:start -->`/`:end -->` markers (re-create the doc with `em slice new --force` if they are lost), restore the template's table header and run `em slice sync`, and give every `### Scenario:` block a Given, When and Then bullet. |
+| `slice-outside-storyline` | warning | Slice outside every storyline | Move the slice inside one of the model's `storyline` blocks (advisory: storylines can be adopted incrementally). |
+| `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. |
 | `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. |
 | `tag-composite-unknown-field` | error | Composite tag names an unknown field | Fix the field name, or add it to the event's fields. |
 | `tag-duplicate-key` | error | Duplicate tag key | Rename one of the tags so every key on the event is unique. |
+| `timeline-entity-clustered` | warning | Lifecycle-per-entity shape (storyline order) | If these are create/update/archive steps on one entity, order the slices by the business journey, interleaving contexts as the story does; if they are steps of one journey, show a screen (a view) after each step. See docs/storyline.md. |
 | `translation-name-collision` | warning | Translation name reused for different producers | Use a distinct name per producer to avoid confusion. |
 | `type-cycle` | error | Cyclic type reference | Break the cycle, or route the self/mutual reference through an array. |
 | `ui-shares-slice-with-automation` | warning | `ui` shares slice with a reaction | Move the `ui` to the slice that displays the read model, or drop it. |