@milehimikey/em 0.2.0 → 1.0.0

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

@@ -16,9 +16,10 @@ You are facilitating an Event Modeling session. Your job is to **extract an accu
 the user through Socratic questioning** — never to invent the domain. You drive the `em` CLI to
 render the model live, and you produce implementation-ready slice design docs.
 
-Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl.md` (DSL syntax
-+ validation rules) before doing real work — they are the source of truth. Templates live in
-`templates/`.
+Read `reference/methodology.md` (the 7 steps + 4 patterns), `reference/em-dsl.md` (DSL syntax +
+validation rules), and — before the `slice` phase specifically — `reference/frontmatter.md` (the
+slice-doc frontmatter schema, lifecycle, and `em slice` CLI) before doing real work; they are the
+source of truth. Templates live in `templates/`.
 
 ## Operating principles (every phase)
 
@@ -45,7 +46,8 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
   only that one adjacent event, so every arrow is short (a read model far from its source events
   draws long arrows that look like a forbidden read→read link). Repeats render cleanly — em only
   warns on a duplicate name that's *referenced* by `from`/`arrow`. Slice order matters: a reaction
-  must be directly followed by its command slice, and a read slice must not be (see `em-dsl.md`).
+  must be directly followed by its command slice, and a read slice must not be immediately
+  followed by a command slice (see `em-dsl.md`).
   See `reference/methodology.md` (State View) and `reference/em-dsl.md`.
 - **Validate continuously.** Run `em validate` and fix errors/warnings as you go (see DSL ref).
 - **Save state at the end of every session** so work resumes cleanly.
@@ -57,7 +59,13 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
 2. Locate the model. Look for an existing `<dir>/.event-modeling.md` and `*.em` in the working
    directory (or a `models/` subfolder). If found, read the state file. If not, and the phase
    needs one, ask the user for the model name and where to create it.
-3. Parse the argument (`$ARGUMENTS`) to pick the phase below. With **no argument**, read the
+3. **Pre-1.0 model check.** If a `slices/*.md` doc exists with no YAML frontmatter block (run
+   `em validate <model>.em` — a missing-frontmatter doc errors with a message pointing at this),
+   tell the user this model predates the frontmatter standard and offer to run
+   `em migrate <model-dir>` before continuing (it refuses a dirty git tree by default — commit
+   first, or pass `--force`). Don't hand-edit old-format docs around this; migrate once, then
+   proceed normally.
+4. Parse the argument (`$ARGUMENTS`) to pick the phase below. With **no argument**, read the
    state file and resume the recorded phase/step; if no model exists, propose starting `discover`.
 
 ## Project layout this skill creates
@@ -68,14 +76,24 @@ Read `reference/methodology.md` (the 7 steps + 4 patterns) and `reference/em-dsl
   <model-name>.svg         # render target for em watch
   live.html                # auto-refresh viewer (copy of templates/live.html, SVG_FILE set)
   README.md                # overview + slice index (from templates/model-readme.md)
-  .event-modeling.md       # resumable state (from templates/state.md)
-  slices/<slice-name>.md   # one rich slice doc per slice (from templates/slice.md)
+  .event-modeling.md       # resumable state (from templates/state.md, with frontmatter)
+  em.config.json           # optional: { "sliceTemplate": "..." } for a team's own slice template
+  slices/<slice-id>.md     # one rich slice doc per slice, scaffolded via `em slice new`
 ```
 
-When creating a new model, scaffold the directory, copy the templates in (filling the
-placeholders), and set `SVG_FILE` in the copied `live.html` to `<model-name>.svg`. You may use
-`em init` for a starter `.em`, but usually you'll build it up from the discovery conversation
-instead. Fill template placeholders — never leave `{{...}}` in delivered files.
+When creating a new model, scaffold the directory, copy the `model-readme.md`/`state.md`
+templates in (filling the placeholders), and set `SVG_FILE` in the copied `live.html` to
+`<model-name>.svg`. You may use `em init` for a starter `.em`, but usually you'll build it up from
+the discovery conversation instead. Fill template placeholders — never leave `{{...}}` in
+delivered files. **Slice docs are the one exception**: don't hand-copy `templates/slice.md` —
+use `em slice new` (see the `slice` phase below), which injects the required frontmatter and
+respects a project's `em.config.json` custom template if one is configured.
+
+Ask the **Regulatory scope** session input (state.md) up front, alongside Scope line / PRD
+reference / Headless-API-model: does this domain have compliance requirements (PCI-DSS, SOX,
+HIPAA, GDPR, ...) or none? This decides whether the `slice` phase asks about the `compliance:`
+frontmatter block per slice (see `reference/frontmatter.md`) — don't ask about compliance at all
+for a model with no regulatory scope.
 
 ---
 
@@ -84,9 +102,16 @@ instead. Fill template placeholders — never leave `{{...}}` in delivered files
 Goal: a draft model of events, storyboard, commands, and views. Loose is OK; structure comes next.
 
 1. **Brainstorm events (step 1).** Ask the user to name everything that happens, as past-tense
-   facts. Capture a flat list. Probe for missed state changes.
+   facts. Probe for missed state changes. For each candidate, apply the **"is it an event?"
+   test** (`reference/methodology.md` step 1 — the "would this wake the CEO at 3am" heuristic):
+   reject derived values (belong in a read model) and telemetry/activity (not business state).
+   Don't silently drop rejections — park them in the state file's Decisions log with why, so
+   they aren't re-proposed later. Capture the survivors as a flat list.
 2. **Plot / storyboard (step 2).** Order the events into the narrative. Identify **personas**
    (actors) and the **UI** screens at each step. Add `persona` declarations and `ui` elements.
+   In a **headless/API** model there are no personas or screens — identify the external
+   **callers** at each step instead; they become the inbound write translations and read
+   translations (see `reference/methodology.md`).
 3. **Inputs (step 3).** For each event, find the **command** that causes it (imperative name).
    Form `command → event` slices (State Change pattern).
 4. **Outputs (step 4).** Identify the **read models / views** consumers need and wire them with
@@ -134,17 +159,33 @@ the corresponding event/slice to the `.em` and re-render. The happy-path spine f
 phases is the starting point, not the finished event set.
 
 For each slice:
-1. Hold a Socratic deep-dive to fill every section of `templates/slice.md`: intent, trigger/actor,
-   command + field table (types & rules), event(s) + payload (mark immutable facts), invariants
-   (give each a stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
+1. Scaffold the doc: `em slice new "<Slice Name>" --pattern <state-change|state-view|automation|translation>`.
+   This writes `slices/<id>.md` with the required frontmatter already filled in (`id`, `pattern`,
+   `status: draft`, `version: 1`, …) and the body template (custom, if `em.config.json` configures
+   one; the shipped default otherwise) ready to fill in.
+2. Hold a Socratic deep-dive to fill every body section: intent, trigger/actor, command + field
+   table (types & rules), event(s) + payload (mark immutable facts), invariants (give each a
+   stable ID), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
    alternate/error flows (retries, idempotency, compensations), read models affected, open
-   questions. Park anything unresolved rather than guessing.
-2. Write the doc to `slices/<slice-name>.md` (kebab-case the slice name).
-3. Wire it into the `.em`: add `note "slices/<slice-name>.md"` to the slice's primary element
-   (the command for State Change, the view for State View, the processor for Automation, the
-   translation for Translation).
-4. Update `README.md`'s slice index and the state file's slice inventory (`draft` → `ready`).
-5. Re-render and `em validate`.
+   questions. Park anything unresolved rather than guessing. Pattern and status are frontmatter
+   now, not prose — see `reference/frontmatter.md`. If the model's **Regulatory scope** (state
+   file) isn't "none," additionally ask whether *this* slice touches regulated data or processes;
+   if so, hand-add a `compliance:` block to the doc's frontmatter (see `reference/frontmatter.md`
+   for the suggested shape — `em` never validates it, so use whatever sub-fields fit). Skip this
+   question entirely for non-regulated models, and skip the block for slices with no compliance
+   relevance even in a regulated model — don't ask by rote.
+3. Wire it into the `.em`: add `note "slices/<id>.md"` to the slice's primary element (the command
+   for State Change, the view for State View, the processor for Automation, the translation for
+   Translation).
+4. Run `em slice sync <id>` — it discovers the linked element from that `note` and fills in the
+   generated frontmatter fields (`commands`/`events`/`readModels`/`contexts`/`personas`, and
+   `triggers`/`triggeredBy` for automation/translation). **Re-run `em slice sync <id>` (or
+   `--all`) after any later `.em` edit that touches this slice's elements** — generated fields
+   drift otherwise, and `em validate` will flag it.
+5. When the doc is solid, move it forward: `em slice update <id> --status reviewed` (and later
+   `--status ready-to-implement`). Update `README.md`'s slice index.
+6. Re-render and `em validate` (validates the `.em` **and** every slice doc's frontmatter by
+   default).
 
 ## Phase: `watch` — live team view
 
@@ -159,8 +200,13 @@ For each slice:
 ## Phase: `validate`
 
 Run `em validate <model-name>.em` and walk through each diagnostic with the user, explaining the
-rule (see `reference/em-dsl.md`) and proposing the fix (e.g. split an automation's command into
-the next slice, add a missing `from`, give a command its event). Apply fixes on agreement.
+rule (see `reference/em-dsl.md` for `.em` rules, `reference/frontmatter.md` for slice-doc
+frontmatter rules) and proposing the fix. Apply fixes on agreement:
+- `.em`-level fixes: split an automation's command into the next slice, add a missing `from`, give
+  a command its event.
+- Slice-doc-level fixes: no frontmatter block → run `em migrate` (pre-1.0 model); "out of sync
+  with .em" → run `em slice sync <id>`; orphan doc → wire a `note "slices/<id>.md"` onto the
+  right element, then sync.
 
 Then do one check `em validate` can't: scan every `translation`/`processor`/`automation` slice and
 confirm none contains an `event` — each reaction must trigger a `command` in the next slice
@@ -174,11 +220,20 @@ two slices and route it through a command.
 ```bash
 em --version
 em init <name>.em                          # optional starter scaffold
-em validate <name>.em                      # check rules; exit 0 if clean/warnings only
+em validate <name>.em                      # check .em rules + slice-doc frontmatter
 em render <name>.em -o <name>.svg          # render (svg/png/pdf by extension)
 em render <name>.em --emit-dot             # inspect generated Graphviz DOT
 em watch <name>.em -o <name>.svg           # re-render on save (run in background)
+
+em slice new "<Slice Name>" --pattern <pattern>   # scaffold slices/<id>.md with frontmatter
+em slice sync <id>                                # after wiring note "slices/<id>.md" into the .em
+em slice update <id> --status <status>            # move a slice's lifecycle status forward
+em slice list / show <id> / search "<query>"      # query slice docs by frontmatter (--format json)
+em slice search "<q>" --format json --full        # ...with every field, not just the summary row
+em migrate <model-dir>                            # one-time upgrade from a pre-1.0 model
 ```
 
+See `reference/frontmatter.md` for the full slice-doc frontmatter schema and CLI reference.
+
 Always finish a working session by: re-rendering, running `em validate`, and updating
 `.event-modeling.md` with the current phase/step, decisions, and open questions.

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

@@ -20,6 +20,21 @@ em validate <file>             # check event-modeling rules; exit 0 if only warn
 Install if missing: `npm i -g @milehimikey/em`. PNG works with no system deps; PDF needs
 `rsvg-convert`.
 
+**Slice docs** (frontmatter, lifecycle, search — see `reference/frontmatter.md` for the schema):
+
+```bash
+em slice new "Slice Name" [--pattern state-change] [--id <id>]   # scaffold slices/<id>.md
+em slice sync <id>            # after wiring note "slices/<id>.md" into the .em
+em slice sync --all           # re-sync every doc in the model directory
+em slice list [--status <s>] [--pattern <p>] [--context <c>] [--tag <t>] [--format json] [--full]
+em slice show <id> [--body] [--format json]
+em slice search "<query>" [--pattern <p>] [--status <s>] [--context <c>] [--tag <t>] [--format json] [--full]
+em slice update <id> [--status <s>] [--bump-version]
+em migrate <model-dir> [--dry-run] [--report <path>]   # one-time upgrade from a pre-1.0 model
+```
+
+`em validate <file>` also validates every doc in `slices/` by default (`--skip-slices` to opt out).
+
 ---
 
 ## Grammar
@@ -156,6 +171,9 @@ slice "Read Quote — created"   { view Quote from "QuoteCreated"  translation S
 - A **read** slice (read model → read translation, no command) must **not** be immediately followed
   by a `command` slice, or the read translation will be mis-wired to that command. Put reads after a
   command+event slice, or before another read / a reaction / an inbound `(request)` slice.
+- A read model fed by an early event (e.g. a queue or to-do view) can't always sit directly after
+  its source event when a reaction must immediately precede its command slice — placing the read
+  later, in narrative order with a longer arrow, is the correct trade-off, not something to force-fix.
 
 ---
 

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

@@ -0,0 +1,129 @@
+# Slice Frontmatter Reference
+
+Every slice doc (`slices/<id>.md`) starts with a required YAML frontmatter block, injected by
+`em slice new` and kept fresh by `em slice sync`. This is what makes slices searchable and
+versionable by AI agents across a model with hundreds of slices, without reading every doc's body.
+Full rationale: `docs/1.0.0-spec.md` in the `em` repo. This file is the quick reference for
+day-to-day use.
+
+---
+
+## Fields
+
+**Core identity** (required, `em slice new` sets these):
+
+| Field | Meaning |
+|---|---|
+| `schemaVersion` | Frontmatter format version. `1`. |
+| `id` | Stable key, kebab-case, generated once. **Never** re-derived from the title. Reference slices by `id`, never by title or filename. |
+| `title` | Human display name. |
+| `pattern` | `state-change \| state-view \| automation \| translation` — the read/write/automation/translation facet. |
+| `status` | See Lifecycle below. |
+| `version` | Integer, bumped via `em slice update --bump-version` on a meaningful content change. Git log is the real history — this is just a "has it changed" signal. |
+| `model` | Relative path to the `.em` file. |
+| `sliceElement` | The `.em` `Element.id` this doc is linked from (via `note "slices/<id>.md"`). |
+
+**Generated** (never hand-edit — run `em slice sync` after any `.em` edit that touches this
+slice's elements):
+
+| Field | Meaning |
+|---|---|
+| `commands`, `events`, `readModels` | Names of the command/event/view elements in this slice. |
+| `contexts`, `personas` | Contexts/personas touched by this slice's event/ui elements. |
+| `triggers` | (automation/translation only) The `id` of the slice doc for the command this reaction triggers, in the next slice. |
+| `triggeredBy` | (command slices only) The inverse — set on the doc for the command an automation/translation triggers. |
+
+`em validate` warns "frontmatter out of sync with .em; run \`em slice sync\`" if these drift from
+what the `.em` actually says. It never auto-fixes this — you have to run `sync` yourself.
+
+**Optional / authored:**
+
+| Field | Meaning |
+|---|---|
+| `swimlane` | `{ persona, context }` — structured form of the body's `**Swimlane:**` line. |
+| `upstreamEvents` | Only for dependencies **not** visible in the `.em`'s wiring (an invariant reading state from an event not consumed via `from`). If the `.em` already expresses it, it belongs in the generated fields above, not here. |
+| `relatedSlices` | Freeform cross-references to other slice `id`s. |
+| `tags` | Free text, searchable via `em slice search --tag`. |
+| `owner`, `created`, `updated` | |
+| `supersededBy`, `implementedRef` | Written by external build tools, not by `em` — see Handoff below. |
+
+**`compliance` — reserved, unvalidated.** For regulated domains (financial, medical, etc.). `em`
+never writes, reads, or validates this key — it's a documented convention only, so it works the
+same way across industries without `em` having to know any regulation's specifics. Only ask about
+it when the model's Regulatory scope (state file) isn't "none" — see the `slice` phase below.
+
+```yaml
+compliance:
+  frameworks: [PCI-DSS, SOX, GAAP]          # or [HIPAA], [GDPR], etc. — whatever applies
+  dataClassification: restricted             # public | internal | confidential | restricted
+  sensitiveDataCategories: [PCI, financial]   # freeform: PCI, PHI, PII, financial, biometric, ...
+  controlRefs: [PCI-DSS-3.4, SOX-404]         # specific control/citation ids
+  retention: 7y
+  dataResidency: US-only
+  reviewedBy: jane@co.com
+  reviewedAt: 2026-06-01
+```
+
+`em slice search` includes this block in its free-text match, so it stays findable even though
+it's unvalidated (e.g. `em slice search "PCI-DSS"`).
+
+---
+
+## Lifecycle
+
+```
+draft → reviewed → ready-to-implement → in-progress → implemented → (deprecated | superseded)
+```
+
+- `draft` / `reviewed` / `ready-to-implement` — the `slice` phase drives these. Move a doc forward
+  with `em slice update <id> --status <status>`.
+- `in-progress` / `implemented` / `deprecated` / `superseded` — **post-handoff.** `em` never writes
+  these; they exist so validation tolerates a build tool writing them back into the same file.
+  Don't set these yourself during a design session.
+
+---
+
+## Handoff to build / SDD tooling
+
+A slice is **ready** when `status` is `ready-to-implement` or later, **and** `em validate` is
+clean for both the `.em` and this doc. At that point, here's what's authoritative for whatever
+implements it:
+
+- **`id`** — the only stable key. Never key generated code, tests, or tickets on title/filename.
+- **Command/Input field table** — the real parameter contract (richer than the `.em`'s lightweight
+  inline `{ field: Type }`, which is a structural preview only — they aren't cross-validated in
+  1.0, so the doc wins if they disagree).
+- **Event table's "Immutable Fact?" column** — treat as compile-time-enforced immutability.
+- **`INV-n` invariant ids** — cite them in generated tests (`test("INV-1: ...")`).
+- **Given/When/Then** — acceptance criteria. Happy path is the floor; rule-boundary scenarios
+  trace to their `INV-n`.
+- **Alternate & Error Flows** — required test cases, not optional.
+- `triggers`/`triggeredBy` plus upstream/downstream (joining doc + `.em`) — a sequencing hint for
+  a build orchestrator (don't build a slice until its upstream slices are `implemented`),
+  advisory only.
+
+`em` never clobbers fields it doesn't recognize on write (`sync`/`update` shallow-merge) — a build
+tool's own bookkeeping fields survive.
+
+---
+
+## CLI
+
+```bash
+em slice new "Place Order" [--pattern state-change] [--id <id>]   # scaffold slices/<id>.md
+em slice sync <id>                     # after wiring `note "slices/<id>.md"` into the .em
+em slice sync --all                    # re-sync every doc in the directory
+em slice list [--status <s>] [--pattern <p>] [--context <c>] [--tag <t>] [--format json] [--full]
+em slice show <id> [--body] [--format json]
+em slice search "<query>" [--pattern <p>] [--status <s>] [--context <c>] [--tag <t>] [--format json] [--full]
+em slice update <id> [--status <s>] [--bump-version]
+em migrate <model-dir> [--dry-run] [--report <path>]    # one-time upgrade from a pre-1.0 model
+```
+
+All commands take `--dir <path>` (default `.`) and `--model <path.em>` if a directory has more
+than one `.em` file. `list`/`show`/`search` read **frontmatter only** — never the `.em`, never the
+doc body — so they stay cheap across a large model.
+
+`list`/`search` emit a summary row per slice by default. Add **`--full`** (with `--format json`)
+to get every frontmatter field instead — use it when you need the filtered slices' commands,
+events, or contexts, so you don't follow a search with one `slice show` per hit.

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

@@ -111,6 +111,16 @@ List the domain **events** as past-tense facts, unordered at first. Go wide; cap
 state change anyone can think of. No commands, no UI yet — just facts.
 - Prompts: *"What are all the things that happen in this process? Say each as something that
   already occurred. What changed when that happened?"*
+- **Is it an event?** Events here are *business* facts, not technical ones. Test: if this fact
+  failed to occur, would it wake the CEO at 3am? Yes → event. No → not an event.
+  - **Yes:** Order Created, Item Added to Order, Order Shipped, Order Delivered, Order
+    Cancelled, User Registered, Item Provisioned.
+  - **No — derived values** (a read model computes these from other events; they aren't
+    independent facts): Order Total Calculated, Order Tax Calculated, Discount Applied.
+  - **No — activity, not business state** (telemetry, not something the domain decides on):
+    User Clicked Button, User Viewed Page, User Logged In.
+- Model the process the business **needs**, not how the current system happens to work. Existing
+  system behavior is a common source of fake events — screens and tables leaking in as facts.
 - Output: a flat list of candidate `event` names.
 
 ### Step 2 — The Plot / Storyboard  *(discover)*

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

@@ -19,10 +19,10 @@ Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 - **Translation** — External input (or Read Model) → Translation → (next slice) Command → Event
 
 ## Slices
-<!-- Keep this index in sync as slice docs are written. -->
-| # | Slice | Pattern | Design doc |
-|---|-------|---------|------------|
-| 1 | {{Slice Name}} | {{Pattern}} | [slices/{{slice-name}}.md](slices/{{slice-name}}.md) |
+<!-- Keep this index in sync as slice docs are written (or regenerate from `em slice list`). -->
+| # | Slice | Pattern | Status | Design doc |
+|---|-------|---------|--------|------------|
+| 1 | {{Slice Name}} | {{Pattern}} | {{status}} | [slices/{{slice-id}}.md](slices/{{slice-id}}.md) |
 
 ## Status
 See [`.event-modeling.md`](.event-modeling.md) for current phase, decisions, and open questions.

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

@@ -3,13 +3,15 @@ Rich slice design document. One per slice, stored in <model>/slices/<slice-name>
 linked from the .em model with:  note "slices/<slice-name>.md"  on the slice's defining element.
 Fill every section through Socratic questioning. Leave "Open Questions" rather than guessing.
 Replace the bracketed placeholders; delete guidance comments before finishing.
+
+This is the body template only — `em slice new` injects the required frontmatter block above
+this content (id, pattern, status, version, sliceElement, and the generated search fields).
+Pattern and status live there now, not as prose here — see reference/frontmatter.md.
 -->
 
 # Slice: {{Slice Name}}
 
-- **Pattern:** {{State Change | State View | Automation | Translation}}
 - **Swimlane:** {{Persona/Actor}} → {{Context/Aggregate}}
-- **Status:** {{draft | reviewed | ready-to-implement}}
 
 ## Intent
 {{Why this slice exists — the user or business goal it serves, in one or two sentences.}}

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

@@ -4,6 +4,11 @@ The skill reads this on `/event-modeling` (no arg) to resume where you left off.
 Keep it current at the end of every working session.
 -->
 
+---
+schemaVersion: 1
+model: {{model-name}}.em
+---
+
 # Event Modeling Progress — {{Model Name}}
 
 - **Model file:** `{{model-name}}.em`
@@ -11,6 +16,12 @@ Keep it current at the end of every working session.
 - **Current step:** {{1–7, see methodology}}
 - **Last updated:** {{YYYY-MM-DD}}
 
+## Session inputs
+- **Scope line:** {{one-line description of what's in/out of bounds for this model}}
+- **PRD / spec reference:** {{path, link, or "none"}}
+- **Headless/API model:** {{yes | no}}
+- **Regulatory scope:** {{e.g. PCI-DSS, SOX, HIPAA, or "none"}}
+
 ## Steps completed
 - [ ] 1. Brainstorm events
 - [ ] 2. Plot / storyboard (personas + UI)
@@ -29,6 +40,6 @@ Keep it current at the end of every working session.
 - [ ] {{question}}
 
 ## Slice inventory
-| Slice | Pattern | Doc status |
-|-------|---------|------------|
-| {{Slice Name}} | {{State Change/View/Automation/Translation}} | {{none / draft / ready}} |
+| Slice | Id | Pattern | Doc status |
+|-------|-----|---------|------------|
+| {{Slice Name}} | {{slice-id}} | {{state-change/state-view/automation/translation}} | {{none / draft / reviewed / ready-to-implement}} |

package/README.md

@@ -148,9 +148,12 @@ em render <file> -o out.png           # PNG (in-process, no system deps)
 em render <file> --emit-dot           # print the generated DOT instead of rendering
 em render <file> --keep-empty-lanes   # don't collapse the API lane when empty
 em watch <file> [-o out.svg]          # re-render on every save
-em validate <file>                    # check event-modeling rules (non-zero exit on errors)
+em validate <file>                    # check event-modeling rules + slice-doc frontmatter
+em migrate <model-dir>                # one-time upgrade of a pre-1.0 model to the frontmatter standard
 ```
 
+See [Slice docs & frontmatter](#slice-docs--frontmatter) below for the `em slice` command group.
+
 ## Validation rules (`em validate`)
 
 - two same-band elements in one slice (collision) → **error** (split into separate slices)
@@ -162,8 +165,34 @@ em validate <file>                    # check event-modeling rules (non-zero exi
 - a read model with no source event → **warning**
 - a name defined more than once and referenced → **warning** (resolves to first)
 
+## Slice docs & frontmatter
+
+Slice design docs (`slices/<id>.md`, written during the skill's `slice` phase or via
+`em slice new`) carry a required YAML frontmatter block — a stable `id`, lifecycle `status`,
+integer `version`, and fields generated from the `.em` (`commands`/`events`/`readModels`/
+`contexts`/`personas`, plus `triggers`/`triggeredBy` for automation/translation) — so an AI agent
+can search and filter across a model with hundreds of slices from frontmatter alone, without
+reading every doc's body or re-parsing the `.em`:
+
+```bash
+em slice new "Place Order" --pattern state-change   # scaffold slices/place-order.md
+em slice sync place-order                           # after wiring note "slices/..." into the .em
+em slice list --status ready-to-implement
+em slice search --pattern automation --context Payment --format json
+em slice search --status ready-to-implement --format json --full   # every field, not just a summary
+em slice update place-order --status reviewed --bump-version
+```
+
+The doc body itself is **yours to define** — point `em.config.json` at a custom template
+(`{ "sliceTemplate": "path/to/template.md" }`) and `em` injects the frontmatter on top of it
+regardless of what sections you ask for. Full schema, lifecycle model, and the handoff contract a
+build/SDD tool should treat as authoritative once a slice is `ready-to-implement`:
+[docs/1.0.0-spec.md](docs/1.0.0-spec.md).
+
 ## Documentation
 
+- [docs/1.0.0-spec.md](docs/1.0.0-spec.md) — slice frontmatter standard, config, `em slice`/
+  `em migrate`, and the SDD handoff contract
 - [docs/why-dot-not-plantuml.md](docs/why-dot-not-plantuml.md) — why DOT + the strict-grid /
   self-drawn-edges architecture
 - [docs/features.md](docs/features.md) — full feature list and roadmap
@@ -195,7 +224,7 @@ Then, in Claude Code, run:
 /event-modeling           # start (or resume) a guided session
 /event-modeling discover  # steps 1–4: brainstorm events, timeline, commands, read models
 /event-modeling model     # steps 5–7: swimlanes, patterns, completeness check
-/event-modeling slice     # deep implementation specs, one per slice
+/event-modeling slice     # deep implementation specs, one per slice (frontmatter via `em slice new`)
 /event-modeling watch     # open a live browser view for team modeling sessions
 /event-modeling validate  # run em validate and resolve all diagnostics
 ```