@milehimikey/em 1.19.7 → 1.21.0

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
-import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
-import { cp, mkdir } from "node:fs/promises";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, renameSync } from "node:fs";
+import { cp, mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { compile } from "./pipeline.js";
+import { compileModelFile, compileModelText } from "./pipeline.js";
+import { ModelLoadError, attributeDiagnosticFiles, diskReader } from "./model/loadModel.js";
 import { isMainModule } from "./util/isMainModule.js";
 import { localIsoDate } from "./util/localDate.js";
 import { continuationOf } from "./model/continuation.js";
@@ -14,11 +15,16 @@ import { renderDot, layoutDot, composeSvg, writeRendered, formatFromPath } from
 import { buildSliceDiagram } from "./render/sliceDiagram.js";
 import { resolveSliceArg, defaultSliceOut, defaultStorylineOut } from "./cli/render-inputs.js";
 import { buildStorylineDiagram, resolveStorylineArg } from "./render/storylineDiagram.js";
+import { buildStorylineMapHtml } from "./render/storylineMap.js";
+import { storylineMap } from "./model/storylineMap.js";
+import { embedStorylinePicker } from "./render/storylinePicker.js";
+import { liveViewUrl, resolveWatchStoryline, storylineFileFor, storylineVariants } from "./cli/watchStoryline.js";
 import { resolveSliceKey } from "./model/resolveSlice.js";
 import { serializeBuilds, watchFile } from "./render/watch.js";
 import { startLiveServer } from "./render/serve.js";
-import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader } from "./model/validate.js";
+import { formatDiagnostic, hasErrors, publicViewsWithoutInModelReader, formatDiagnosticWithFile } from "./model/validate.js";
 import { buildExport, buildSliceExport, GENERATOR_VERSION } from "./emit/json.js";
+import { buildDocJsonExport } from "./emit/docJson.js";
 import { generateContract, runApiCheck, formatApiCheckText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
 import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
@@ -50,7 +56,7 @@ import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
 import { buildLedgerJson } from "./emit/ledgerJson.js";
 import { buildRefsJson } from "./emit/refsJson.js";
 import { buildShapeReport, formatShapeText } from "./cli/shape.js";
-import { applyRefWaivers, checkRefs, readWaiveFile } from "./cli/refsCheck.js";
+import { applyRefWaivers, checkRatificationOrder, checkRefs, readWaiveFile } from "./cli/refsCheck.js";
 import { buildCoverageReport, resolveScopedSlices, resolveCoverageSliceKey } from "./cli/coverage.js";
 import { buildCoverageJson } from "./emit/coverageJson.js";
 import { resolveSliceStatusFacts, countOpenIssues, resolveConformanceEntry, aggregateInvariantTotals, buildStatusReport, formatStatusText, formatStatusMarkdown, buildStatusBadge, formatConformancePart, findSpecifyRoot, resolveModelVersionStatusEntry, resolveEmVersionStatusEntry, } from "./cli/status.js";
@@ -65,7 +71,7 @@ import { checkSkillSyncBundle, checkAgentFiles } from "./cli/skillCheck.js";
 import { buildSkillCheckJson } from "./emit/skillCheckJson.js";
 import { checkPlugin, claudePluginsDir, detectPlugin, pluginInstallCommands } from "./cli/pluginPin.js";
 import { readContract } from "./cli/contract.js";
-import { EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES, EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR, EM_AGENT_FILES } from "./cli/skillDirs.js";
+import { EM_SKILL_DIR_NAMES, EM_SHARED_DIR_NAMES, EM_ALL_SKILL_BUNDLE_DIRS, EM_SKILL_ANCHOR_DIR, EM_AGENT_FILES, resolveVendoredDirs } from "./cli/skillDirs.js";
 import { createServer as createMcpServer } from "./mcp/server.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { syncAgentsMd } from "./cli/agentsMd.js";
@@ -89,7 +95,7 @@ import { listModelCommits } from "./cli/changelog-git.js";
 import { buildChangelogDoc } from "./cli/changelogBuild.js";
 import { runRevise } from "./cli/revise.js";
 import { runDefer, runDeferFromIssue } from "./cli/defer.js";
-import { runSliceConform, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles } from "./cli/sliceConform.js";
+import { runSliceConform, runSliceConformPreview, writePreviewFindings, resolveFindingsForReport, findingsFilesOf, unruledAcrossFiles, } from "./cli/sliceConform.js";
 import { checkPrdTriage, buildCheckPrdTriageJson, renderPrdTriageMarkdown, validatePrdTriage } from "./cli/prdTriage.js";
 import { checkFindingsFile, buildCheckFindingsJson, FINDING_LOCI } from "./cli/findings.js";
 import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
@@ -99,6 +105,7 @@ import { kebabSlug } from "./util/slug.js";
 import { ciWorkflowPath, conformWorkflowPath, buildCiWorkflowFile, buildConformWorkflowFile, buildCiWorkflowFileMulti, buildConformWorkflowFileMulti, ciManagedBody, ciManagedBodyMulti, conformManagedBody, conformManagedBodyMulti, ciModelsFromManifest, describeOtherModels, describeSetChange, fileBlockModels, planCiFile, refreshCiPullRequestPaths, applyCiPullRequestPathsRefresh, applyCiFile, findUnsafeCiInitArg, CI_WORKFLOW_MARKER, CONFORM_WORKFLOW_MARKER, } from "./cli/ciInit.js";
 import { resolveRepoRoot, detectUpgrade, applyUpgrade, checkUpgrade } from "./cli/upgrade.js";
 import { buildStorylineSuggestion } from "./cli/storylineSuggest.js";
+import { planStorylineSplit } from "./cli/storylineSplit.js";
 import { buildUpgradeJson } from "./emit/upgradeJson.js";
 import { isOlder } from "./util/semver.js";
 import { RULES } from "./model/rules.js";
@@ -114,6 +121,8 @@ import { runCodeowners } from "./system/codeowners.js";
 import { buildCodeownersJson } from "./emit/codeownersJson.js";
 import { verifySystem } from "./system/verify.js";
 import { buildSystemJson } from "./emit/systemJson.js";
+import { docDirOf } from "./model/sliceDocPath.js";
+import { docDirs } from "./catalog/docLocate.js";
 /** GH #253: the trailing note `em slice defer` prints after `deferred: …` on a ratified/shipped
  *  doc — the item went into the signed body, outside `ratifiedHash`, and when the stamp was still
  *  in an older scope (pre-1.17 whole-body, or 1.17–1.18) it was re-stamped in the same edit (body unchanged). */
@@ -198,12 +207,17 @@ program
     .option("-T, --format <fmt>", "output format (svg, png, pdf, ...)")
     .option("--slice <name>", "render only this slice, redrawn in its own canonical pattern shape " +
     "(default out: slices/<kebab-slug>.svg)")
-    .option("--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`) " +
+    .option("--storyline <name>", "render only this storyline: its own slices in order, nothing from outside it " +
     "(default out: storylines/<kebab-slug>.svg)")
+    .option("--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)")
     .option("--emit-dot", "print the generated DOT instead of rendering")
     .option("--keep-empty-lanes", "keep the API lane even when empty")
     .action(async (file, opts) => {
+    if (opts.map && (opts.slice !== undefined || opts.storyline !== undefined || opts.emitDot)) {
+        console.error("em render: --map cannot be combined with --slice, --storyline or --emit-dot");
+        process.exit(1);
+    }
     if (opts.slice !== undefined && opts.emitDot) {
         console.error("em render: --slice cannot be combined with --emit-dot");
         process.exit(1);
@@ -236,6 +250,27 @@ program
         console.error("not rendering: fix the errors above");
         process.exit(1);
     }
+    if (opts.map) {
+        const storylines = model.storylines ?? [];
+        if (storylines.length === 0) {
+            console.error("em render --map: this model declares no storylines");
+            process.exit(1);
+        }
+        const out = opts.out ?? join(dirname(file), "storylines", "map.html");
+        const outDir = dirname(out);
+        await mkdir(outDir, { recursive: true });
+        const frames = [];
+        for (const st of storylines) {
+            const sub = buildStorylineDiagram(model, st, { keepEmptyLanes: opts.keepEmptyLanes });
+            const svg = composeSvg(await layoutDot(sub.dot), sub.model, sub.grid, dirname(file), outDir);
+            const slug = kebabSlug(st.name);
+            await writeRendered(svg, join(outDir, `${slug}.svg`), "svg");
+            frames.push({ name: st.name, slug, sliceCount: st.sliceIndexes.length, svg });
+        }
+        await writeFile(out, buildStorylineMapHtml(model, frames, storylineMap(model)), "utf8");
+        console.log(`rendered ${out} (+ ${frames.length} storyline svg${frames.length === 1 ? "" : "s"})`);
+        return;
+    }
     if (opts.storyline !== undefined) {
         const found = resolveStorylineArg(model, opts.storyline);
         if ("error" in found) {
@@ -258,7 +293,7 @@ program
             console.error(lookup.error);
             process.exit(1);
         }
-        const out = opts.out ?? defaultSliceOut(file, opts.slice);
+        const out = opts.out ?? defaultSliceOut(file, opts.slice, docDirOf(model.slices[lookup.index]));
         const fmt = opts.format ?? formatFromPath(out);
         await mkdir(dirname(out), { recursive: true }); // slices/ may not exist yet
         const { model: sliceModel, grid: sliceGrid, dot: sliceDot } = buildSliceDiagram(model, lookup.index, {
@@ -283,9 +318,35 @@ program
     .option("--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)")
+    .option("--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)")
+    .option("--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)")
     .action((file, opts) => {
     const { model, refs, diagnostics, source } = compileFile(file);
     printDiagnostics(diagnostics);
+    if (opts.docJson) {
+        if (opts.slice) {
+            console.error("em export --doc-json: exports the whole model and does not combine with --slice");
+            process.exit(1);
+        }
+        if (hasErrors(diagnostics)) {
+            console.error("not exporting: fix the errors above");
+            process.exit(1);
+        }
+        const exportedDoc = buildDocJsonExport(model, refs, diagnostics, source, file, { includeHtml: opts.includeHtml });
+        printDiagnostics(newDiagnostics(exportedDoc.diagnostics, diagnostics));
+        if (opts.out) {
+            writeFileSync(opts.out, exportedDoc.text + "\n");
+            console.log(`wrote ${opts.out}`);
+        }
+        else {
+            process.stdout.write(exportedDoc.text + "\n");
+        }
+        return;
+    }
     if (opts.slice) {
         // Scoped export deliberately does NOT reuse the whole-model error guard below: the
         // ticket's own motivation for `--slice` is an agent implementing one already-ratified
@@ -412,7 +473,10 @@ program
             oldDoc: (key) => readSliceDoc(dirname(plan.oldFile), key),
             newDoc: (key) => readSliceDoc(dirname(plan.newFile), key),
         };
-        runDiff(oldSource, plan.oldFile, newSource, plan.newFile, opts.exitCode, opts.json, lineage);
+        runDiff(oldSource, plan.oldFile, newSource, plan.newFile, opts.exitCode, opts.json, lineage, {
+            old: diskReader(dirname(plan.oldFile)),
+            new: diskReader(dirname(plan.newFile)),
+        });
         return;
     }
     const oldSource = readAtRevision(plan.file, plan.from);
@@ -423,7 +487,10 @@ program
         oldDoc: (key) => resolveDocAtRevision(plan.file, key, plan.from),
         newDoc: (key) => plan.to ? resolveDocAtRevision(plan.file, key, plan.to) : readSliceDoc(dirname(plan.file), key),
     };
-    runDiff(oldSource, oldLabel, newSource, newLabel, opts.exitCode, opts.json, lineage);
+    runDiff(oldSource, oldLabel, newSource, newLabel, opts.exitCode, opts.json, lineage, {
+        old: gitReader(plan.file, plan.from),
+        new: plan.to ? gitReader(plan.file, plan.to) : diskReader(dirname(plan.file)),
+    });
 });
 program
     .command("glossary")
@@ -446,7 +513,7 @@ program
     let anyErrors = false;
     for (const file of files) {
         const source = readFileOrExit(file);
-        const result = compileSource(source, file);
+        const result = compileSource(source, file, diskReader(dirname(file)));
         printDiagnosticsFor(file, result.diagnostics);
         if (hasErrors(result.diagnostics))
             anyErrors = true;
@@ -567,8 +634,12 @@ slice
         process.exit(1);
     }
     const key = sliceDocKey(name);
-    const dir = "slices";
-    const path = join(dir, `${key}.md`);
+    // The note clause written into the model is always `slices/<key>.md`, relative to the file
+    // that declares the slice (GH #421). Where the FILE goes: `slices/` under the cwd, or — with
+    // --wire naming a model whose slice sits in a storyline folder — that folder's `slices/`.
+    const notePath = `slices/${key}.md`;
+    let dir = "slices";
+    let path = join(dir, `${key}.md`);
     if (existsSync(path) && !opts.force) {
         console.error(`refusing to overwrite ${path} (use --force)`);
         process.exit(1);
@@ -588,12 +659,25 @@ slice
             console.error(`em slice new --wire: not wiring — fix the errors in ${opts.wire} above`);
             process.exit(1);
         }
-        const result = wireSliceNote(source, model, refs, key, opts.pattern, path);
+        // GH #421: a slice declared in a storyline model file is wired in THAT file (its line
+        // numbers count there); a root slice in the root as before.
+        const sliceFile = model.slices[refs.sliceKeys.indexOf(key)]?.file;
+        const wireTarget = sliceFile ? resolve(dirname(opts.wire), sliceFile) : opts.wire;
+        const wireSource = sliceFile ? readFileSync(wireTarget, "utf8") : source;
+        if (sliceFile) {
+            dir = join(dirname(opts.wire), docDirOf(model.slices[refs.sliceKeys.indexOf(key)]), "slices");
+            path = join(dir, `${key}.md`);
+            if (existsSync(path) && !opts.force) {
+                console.error(`refusing to overwrite ${path} (use --force)`);
+                process.exit(1);
+            }
+        }
+        const result = wireSliceNote(wireSource, model, refs, key, opts.pattern, notePath);
         if (!result.ok) {
             console.error(`em slice new --wire: ${result.message}`);
             process.exit(1);
         }
-        wired = result;
+        wired = { ...result, target: wireTarget };
         regions = buildSliceRegions(model, [refs.sliceKeys.indexOf(key)]);
         const sliceEvents = model.slices[refs.sliceKeys.indexOf(key)].elements.filter((e) => e.kind === "event");
         alternatives = sliceEvents.filter((e) => e.alternativeGroup !== undefined).map((e) => e.name);
@@ -605,8 +689,8 @@ slice
     writeFileSync(path, content);
     console.log(`wrote ${path}`);
     if (wired) {
-        writeFileSync(opts.wire, wired.content);
-        console.log(`wired ${path} onto ${wired.elementName} in slice "${wired.sliceName}" (${opts.wire})`);
+        writeFileSync(wired.target, wired.content);
+        console.log(`wired ${path} onto ${wired.elementName} in slice "${wired.sliceName}" (${wired.target})`);
     }
     else {
         console.log(`add this to the slice's primary element in the .em file:`);
@@ -710,6 +794,7 @@ slice
     "facts (key, pattern, doc status/implementedIn) — the hand-maintained table is deprecated")
     .argument("<file>", "input .em file")
     .option("--check", "verify the table is current; exit non-zero on drift without writing (CI)")
+    .option("--full", "every lifecycle column (reviewed/ratified/owner/tracking/implemented/conformed) instead of the reader's five")
     .action((file, opts) => {
     const { model, diagnostics, refs } = compileFile(file);
     printDiagnostics(diagnostics);
@@ -717,7 +802,7 @@ slice
         console.error("not indexing: fix the errors above");
         process.exit(1);
     }
-    const result = runSliceIndex(model, refs, file, !!opts.check);
+    const result = runSliceIndex(model, refs, file, !!opts.check, { full: !!opts.full });
     printDiagnostics(newDiagnostics(result.table.diagnostics, diagnostics));
     if (!result.ok) {
         console.error(result.message);
@@ -729,6 +814,10 @@ slice
     else {
         console.log(`ok — ${result.readmePath}'s Slices table is already up to date`);
     }
+    if (result.storylines === "absent") {
+        console.log(`note: ${result.readmePath} has no <!-- GENERATED:storylines:start --> / :end markers, so the storyline table ` +
+            "was not written — add the ## Storylines section from templates/model-readme.md to get it");
+    }
 });
 slice
     .command("mark-implemented")
@@ -1088,7 +1177,10 @@ slice
     "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.")
+    "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.")
     .argument("<file>", "input .em file")
     .argument("<slice-key>", "slice export key (kebab-case)")
     .requiredOption("--at <rev>", "the target-repo revision this certification sweep diffed against — or, when what was exercised is not a commit " +
@@ -1096,12 +1188,31 @@ slice
     "`<kind>:<id>` such as build:1234 or deploy:eu-1-2026-10-15 (GH #261); recorded verbatim, skipped by git-reachability checks")
     .option("--on <date>", "certification date, YYYY-MM-DD (default: today, local date)")
     .option("--skip-findings-check", "certify even with unruled findings in scope — prints a loud notice on stderr")
+    .option("--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)")
+    .option("--write-findings", "with --preview: persist the preview's own unruled findings as conformance/<on>-<slice-key>-preview-findings.json")
+    .option("--json", "with --preview: print a JSON document instead of the text report")
     .action((file, sliceKey, opts) => {
+    if (opts.writeFindings === true && opts.preview !== true) {
+        console.error("em slice conform: --write-findings only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.json === true && opts.preview !== true) {
+        console.error("em slice conform: --json only applies with --preview");
+        process.exit(1);
+    }
+    if (opts.preview === true && opts.skipFindingsCheck === true) {
+        console.error("em slice conform: --skip-findings-check has no effect with --preview (preview never blocks on findings)");
+        process.exit(1);
+    }
     const { model, refs, diagnostics } = compileFile(file);
     printDiagnostics(diagnostics);
     sliceKey = resolveSliceOrExit("em slice conform", model, refs, sliceKey);
     // Scoped the same way `em slice ratify`/`em slice revise`/`em slice mark-implemented` are:
-    // only an error concerning THIS slice refuses.
+    // only an error concerning THIS slice refuses. Not waived by --preview — an erroring model
+    // isn't a fact worth previewing against either.
     const scopedErrors = diagnostics.filter((d) => d.severity === "error" && d.refs?.some((r) => r === sliceKey || r.startsWith(`${sliceKey}/`)));
     if (scopedErrors.length > 0) {
         console.error(`em slice conform: slice "${sliceKey}" has errors — fix them first`);
@@ -1113,6 +1224,44 @@ slice
         console.error(`em slice conform: invalid --on date "${opts.on}" — expected YYYY-MM-DD`);
         process.exit(1);
     }
+    if (opts.preview === true) {
+        const baseDir = dirname(file);
+        const result = runSliceConformPreview(model, refs, baseDir, sliceKey, opts.at);
+        if (!result.ok) {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, message: result.message }, null, 2));
+            }
+            else {
+                console.error(`em slice conform --preview: ${result.message}`);
+            }
+            process.exit(1);
+        }
+        const writtenTo = opts.writeFindings === true ? writePreviewFindings(baseDir, file, sliceKey, result.at, on, result.unruledFindings) : null;
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                preview: true,
+                slice: sliceKey,
+                path: result.path,
+                status: result.status,
+                version: result.version,
+                at: result.at,
+                findingsFiles: result.findingsFiles,
+                unruledFindings: result.unruledFindings,
+                writtenTo,
+            }, null, 2));
+        }
+        else {
+            const findingsNote = result.unruledFindings.length === 0
+                ? result.findingsFiles.length === 0
+                    ? `no conformance findings file matches --at ${result.at} (conformance/<date>[-<name>]-findings.json with that revision)`
+                    : `no unruled conformance findings in scope (checked: ${result.findingsFiles.join(", ")})`
+                : `${result.unruledFindings.length} unruled conformance finding(s) in scope (id ${result.unruledFindings.map((f) => f.id).join(", ")}) in ${result.findingsFiles.join(", ")}`;
+            console.log(`preview: ${result.path} (status: ${result.status ?? "(empty)"}) @ ${result.at} — ${findingsNote}`);
+            console.log(writtenTo !== null ? `wrote: ${writtenTo}` : "ephemeral — nothing written; pass --write-findings to persist a snapshot");
+        }
+        return;
+    }
     const result = runSliceConform(model, refs, dirname(file), sliceKey, opts.at, on, opts.skipFindingsCheck === true);
     if (!result.ok) {
         console.error(`em slice conform: ${result.message}`);
@@ -1356,8 +1505,8 @@ state
         process.exit(1);
     }
     const phases = sortUsagePhases(rawPhases);
-    const { model, diagnostics, refs, source } = compileFile(file);
-    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    const { model, diagnostics, refs, hashSource } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, hashSource);
     const categorySet = new Set(allDiagnostics.map((d) => RULES[d.code].usageCategory));
     const categories = categorySet.size > 0 ? [...categorySet].sort() : ["none"];
     const loaded = loadStateFile(dirname(file));
@@ -1400,13 +1549,13 @@ modelVersionCmd
     }
     const today = localIsoDate();
     const on = opts.on ?? today;
-    const { model: compiledModel, refs, diagnostics, source } = compileFile(file);
+    const { model: compiledModel, refs, diagnostics, hashSource } = compileFile(file);
     printDiagnostics(diagnostics);
     if (hasErrors(diagnostics)) {
         console.error(`em model version bump: "${file}" has errors — fix them first`);
         process.exit(1);
     }
-    const result = runModelVersionBump(baseDir, basename(file), compiledModel, refs, source, opts.by, on, GENERATOR_VERSION, opts.force === true);
+    const result = runModelVersionBump(baseDir, basename(file), compiledModel, refs, hashSource, opts.by, on, GENERATOR_VERSION, opts.force === true);
     if (!result.ok) {
         console.error(`em model version bump: ${result.message}`);
         process.exit(1);
@@ -1638,10 +1787,28 @@ program
     .option("--keep-empty-lanes", "keep the API lane even when empty")
     .option("--serve", "serve a live viewer with instant push-reload (no polling)")
     .option("--port <n>", "port for --serve (default 5173)", (v) => parseInt(v, 10))
+    .option("--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")
     .action(async (file, opts) => {
     const out = opts.out ?? defaultOut(file, opts.format ?? "svg");
     const fmt = opts.format ?? formatFromPath(out);
+    if (opts.storyline !== undefined && !opts.serve) {
+        console.error("em watch: --storyline applies only with --serve");
+        process.exit(1);
+    }
     let server;
+    // The file the printed live-view URL points at — basename(out) (the full model) unless
+    // --storyline resolves, in which case build() below points it at that storyline's own
+    // subset file instead (GH #309).
+    let liveFile = basename(out);
+    // GH #422: the storyline canvas (the page `em render --map` writes), rebuilt on every build
+    // and served live at /map — undefined while the model declares no storylines, so /map 404s.
+    let canvas;
+    let hasStorylines = false;
     // serializeBuilds: chokidar can fire several events for one save (and an
     // editor's write can land while a slow png/pdf render is still in flight) —
     // overlapping builds would race each other writing the same output file.
@@ -1662,7 +1829,52 @@ program
                 server?.notifyError(first ? formatDiagnostic(first).trim() : "model has errors — see terminal");
                 return;
             }
-            await renderDot(dot, model, grid, out, fmt, dirname(file));
+            // GH #309: --storyline is validated on every build, same as `em render --storyline`
+            // (resolveWatchStoryline shares findStoryline's resolution) — a save that renames or
+            // drops the storyline must not kill the watcher.
+            const resolved = resolveWatchStoryline(model, opts.storyline);
+            if ("error" in resolved) {
+                console.error(resolved.error);
+                server?.notifyError(resolved.error);
+                return;
+            }
+            if (opts.serve && fmt === "svg") {
+                const baseDir = dirname(file);
+                const outDir = dirname(out);
+                const outFile = basename(out);
+                liveFile = "storyline" in resolved ? storylineFileFor(resolved.storyline.name) : outFile;
+                // The full model, always rendered to `out` (unchanged default) — carries the
+                // storyline-picker metadata (a no-op when the model declares none) so the viewer can
+                // offer it regardless of whether --storyline was passed.
+                const fullRaw = await layoutDot(dot);
+                const fullSvg = embedStorylinePicker(composeSvg(fullRaw, model, grid, baseDir, outDir), storylineVariants(model, outFile, liveFile));
+                await writeRendered(fullSvg, out, "svg");
+                // Every declared storyline's own subset (GH #277's `em render --storyline` subset,
+                // reused verbatim) — rendered alongside the full model on every build, independent of
+                // --storyline, so the viewer's picker always has somewhere to navigate to. The same
+                // subsets fill the live canvas's frames (GH #422), each frame opening into its
+                // storyline's viewer page.
+                const frames = [];
+                for (const st of model.storylines ?? []) {
+                    const sub = buildStorylineDiagram(model, st, { keepEmptyLanes: opts.keepEmptyLanes });
+                    const subFile = storylineFileFor(st.name);
+                    const subRaw = await layoutDot(sub.dot);
+                    const subSvg = embedStorylinePicker(composeSvg(subRaw, sub.model, sub.grid, baseDir, outDir), storylineVariants(model, outFile, subFile));
+                    await writeRendered(subSvg, join(outDir, subFile), "svg");
+                    frames.push({
+                        name: st.name,
+                        slug: kebabSlug(st.name),
+                        sliceCount: st.sliceIndexes.length,
+                        svg: subSvg,
+                        href: `/?svg=${encodeURIComponent(subFile)}`,
+                    });
+                }
+                hasStorylines = frames.length > 0;
+                canvas = hasStorylines ? buildStorylineMapHtml(model, frames, storylineMap(model), { live: true }) : undefined;
+            }
+            else {
+                await renderDot(dot, model, grid, out, fmt, dirname(file));
+            }
             console.log(`rendered ${out} (${Date.now() - started}ms)`);
             server?.notify();
         }
@@ -1676,11 +1888,16 @@ program
         try {
             // Serve the directory the SVG is written to — that's what the browser
             // fetches, and note "..." links inside the SVG resolve relative to it.
-            server = await startLiveServer({ dir: dirname(resolve(out)), port: opts.port });
+            server = await startLiveServer({ dir: dirname(resolve(out)), port: opts.port, canvas: () => canvas });
             // The viewer inlines SVG only — for png/pdf watches there's nothing
             // live to embed, so don't print a ?svg= URL that can't work.
             if (fmt === "svg") {
-                console.log(`→ live view: ${server.url}/?svg=${encodeURIComponent(basename(out))}`);
+                const pinned = opts.storyline !== undefined;
+                console.log(`→ live view: ${liveViewUrl(server.url, liveFile, hasStorylines, pinned)}`);
+                if (hasStorylines && !pinned) {
+                    console.log("  the storyline canvas — click a storyline's “open ›” to step through it;");
+                    console.log(`  the full timeline: ${server.url}/?svg=${encodeURIComponent(liveFile)}`);
+                }
                 console.log("  open it in a browser and share your screen");
             }
             else {
@@ -1697,7 +1914,20 @@ program
     // the .em file. Watching the directory (not a glob — chokidar 4 has none)
     // still fires for docs authored after watch starts; the filter keeps it to .md.
     const slicesDir = join(dirname(file), "slices");
-    watchFile([file, slicesDir], build, 80, (p) => p === file || p.endsWith(".md"));
+    // GH #421: a storyline model file is part of the model — watch each one the root declares
+    // (resolved once at start; a storyline added to the root mid-session needs a restart).
+    const storylineFiles = (() => {
+        try {
+            return compileModelFile(file).files.map((f) => resolve(dirname(file), f));
+        }
+        catch {
+            return [];
+        }
+    })();
+    const watched = new Set([resolve(file), ...storylineFiles]);
+    // GH #421 step 2: docs live beside their declaring file — watch every existing doc folder
+    const docFoldersNow = docDirs(dirname(file));
+    watchFile([file, ...storylineFiles, slicesDir, ...docFoldersNow.filter((d) => resolve(d) !== resolve(slicesDir))], build, 80, (p) => watched.has(resolve(p)) || p.endsWith(".md"));
     console.log(`watching ${file} … (ctrl-c to stop)`);
     if (!opts.serve)
         console.log("tip: add --serve for the live browser view");
@@ -1756,9 +1986,9 @@ program
         console.error("em validate: --shape cannot be combined with --slice-ready, --list-*, --fail-on-issues or --check-signed-bodies");
         process.exit(1);
     }
-    const { model, diagnostics, refs, source } = compileFile(file);
+    const { model, diagnostics, refs, source, hashSource } = compileFile(file);
     if (opts.shape) {
-        const all = computeAllDiagnostics(file, model, refs, diagnostics, source);
+        const all = computeAllDiagnostics(file, model, refs, diagnostics, hashSource);
         const report = buildShapeReport(all, opts.waiveFile ? readWaiveFile(opts.waiveFile) : []);
         const modelErrors = all.filter((d) => d.severity === "error").length;
         for (const k of report.staleWaivers)
@@ -1772,7 +2002,7 @@ program
     // GH #257: an opt-in addition to the unconditional set, so --json, the text report and the
     // exit code all see it the same way every other diagnostic is seen.
     const allDiagnostics = [
-        ...computeAllDiagnostics(file, model, refs, diagnostics, source),
+        ...computeAllDiagnostics(file, model, refs, diagnostics, hashSource),
         ...(opts.checkSignedBodies ? validateSignedBodies(model, refs, dirname(file)) : []),
     ];
     // GH #293: --strict promotes advisory lints to errors (the --slice-ready branch below does
@@ -1938,6 +2168,10 @@ program
     .requiredOption("--reachable-from <rev>", "the branch or commit every ref must be an ancestor of (e.g. origin/main)")
     .option("--waive <slice-key>", "excuse this slice's non-ancestor/unresolved/undecidable results from the exit code (repeatable); still reported", (value, previous) => [...previous, value], [])
     .option("--waive-file <path>", "a baseline file of slice keys to waive, one per line (`#` comments allowed); missing file = no waivers")
+    .option("--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")
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .action((file, opts) => {
     const { model, refs } = compileFile(file);
@@ -1953,8 +2187,11 @@ program
     }
     if (result.shallow)
         console.error("warn: shallow clone — every ref is undecidable; check out with fetch-depth: 0");
+    // GH #399: computed only with --check-order, and never folded into `result`/`result.ok` —
+    // it is a sibling report, not a new ref field, and must never move the exit code (R5).
+    const orderResults = opts.checkOrder ? checkRatificationOrder(model, refs, dirname(file), result.target, result.shallow) : null;
     if (opts.json) {
-        process.stdout.write(buildRefsJson(result, file) + "\n");
+        process.stdout.write(buildRefsJson(result, file, orderResults) + "\n");
     }
     else {
         for (const r of result.results) {
@@ -1971,8 +2208,19 @@ program
         else {
             console.log(`${bad} ref(s) not reachable from ${opts.reachableFrom} (${result.checkedRefs} checked on ${result.checkedDocs} doc(s)${waivedNote})`);
         }
+        if (orderResults) {
+            console.log("");
+            console.log("ratification order (advisory — never affects exit code):");
+            if (orderResults.length === 0) {
+                console.log("  no slice doc carries a ratifiedRef to check");
+            }
+            for (const o of orderResults) {
+                console.log(`  ${o.status.padEnd(23)} ${o.sliceKey} ratifiedRef: ${o.ratifiedRef}${o.detail ? ` — ${o.detail}` : ""}`);
+            }
+        }
     }
     // Set the code rather than process.exit(): stdout to a pipe shouldn't risk truncation.
+    // `orderResults` never participates — advisory only, per R5.
     if (!result.ok)
         process.exitCode = 1;
 });
@@ -2156,11 +2404,11 @@ program
     const compiled = [];
     let anyErrors = false;
     for (const file of files) {
-        const { model, refs, diagnostics, source } = compileFile(file);
+        const { model, refs, diagnostics, source, hashSource } = compileFile(file);
         printDiagnosticsFor(file, diagnostics);
         if (hasErrors(diagnostics))
             anyErrors = true;
-        compiled.push({ file, model, refs, source });
+        compiled.push({ file, model, refs, source, hashSource });
     }
     if (anyErrors) {
         console.error("em status: not reporting status — fix the errors above");
@@ -2218,7 +2466,7 @@ program
         return resolveConformanceEntry(file, opts.repo, sliceDocFacts);
     });
     // MIL-218: one model-version entry per input file.
-    const modelVersion = compiled.map(({ file, model, refs, source }) => resolveModelVersionStatusEntry(file, model, refs, source));
+    const modelVersion = compiled.map(({ file, model, refs, hashSource }) => resolveModelVersionStatusEntry(file, model, refs, hashSource));
     // MIL-219: one em-version entry per input file whose state file resolved.
     const emVersion = compiled
         .map(({ file }) => resolveEmVersionStatusEntry(file, PKG_VERSION))
@@ -2526,8 +2774,8 @@ function resolveSliceOrExit(command, model, refs, input) {
 /** Compile `file` with the full `em validate` diagnostic set — what `engagement plan` needs for
  *  each slice's `--slice-ready` verdict (R34). */
 function engagementModelInput(file) {
-    const { model, refs, diagnostics, source } = compileFile(file);
-    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    const { model, refs, diagnostics, source, hashSource } = compileFile(file);
+    const allDiagnostics = computeAllDiagnostics(file, model, refs, diagnostics, hashSource);
     return { file, model, refs, baseDir: dirname(file), contract: { file, source, diagnostics }, allDiagnostics };
 }
 engagement
@@ -2860,17 +3108,24 @@ const scopeCommand = systemCommand
 function packagedSkillsRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "skills");
 }
-function vendoredSkillsRoot(repoRoot) {
-    return join(resolve(repoRoot), ".claude", "skills");
-}
-// MIL-269 (R32): the four em sub-agent definitions live in `.claude/agents/`, a directory shared
+// GH #412: the consumer side is `.claude/skills/` + `.claude/agents/` by default, `--skills-dir` /
+// `--agents-dir` when given, or `.agents/skills/` (+ `.agents/agents/`) when that neutral folder
+// exists and `.claude/skills/` does not — see resolveVendoredDirs (src/cli/skillDirs.ts).
+// MIL-269 (R32): the four em sub-agent definitions live in the agents dir, a directory shared
 // with the consumer's own agents - install/sync/check only ever handle the fixed EM_AGENT_FILES.
 function packagedAgentsRoot() {
     return join(dirname(fileURLToPath(import.meta.url)), "..", ".claude", "agents");
 }
-function vendoredAgentsRoot(repoRoot) {
-    return join(resolve(repoRoot), ".claude", "agents");
+function vendoredDirs(repoRoot, opts) {
+    const dirs = resolveVendoredDirs(repoRoot, opts);
+    if (dirs.detected)
+        console.log(`using ${relative(resolve(repoRoot), dirs.skillsRoot)}/ (no .claude/skills/ here; pass --skills-dir to choose)`);
+    return dirs;
 }
+const SKILLS_DIR_HELP = "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)";
+const AGENTS_DIR_HELP = "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)";
 program
     .command("contract")
     .description("print the packaged implementation contract (reference/implement.md) to stdout — the " +
@@ -2912,9 +3167,8 @@ const skill = program
     .description("manage Claude Code skills bundled with em");
 // MIL-269: reconcile the four `.claude/agents/em-*.md` files (create the directory if absent);
 // byte-exact restore, never touches any other file there.
-function installAgentFiles(repoRoot) {
+function installAgentFiles(vendored) {
     const packaged = packagedAgentsRoot();
-    const vendored = vendoredAgentsRoot(repoRoot);
     const plan = planAgentSync(packaged, vendored, EM_AGENT_FILES);
     if (plan.changes.length === 0)
         return;
@@ -2934,10 +3188,13 @@ skill
     "bundle's own managed directories the same way `em skill sync` does — never touching an " +
     "unrelated sibling skill (MIL-180)")
     .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
+    .option("--skills-dir <dir>", SKILLS_DIR_HELP)
+    .option("--agents-dir <dir>", AGENTS_DIR_HELP)
     .action(async (opts) => {
     warnVendoredDeprecated();
     const srcRoot = packagedSkillsRoot();
-    const destRoot = vendoredSkillsRoot(process.cwd());
+    const dirs = vendoredDirs(process.cwd(), opts);
+    const destRoot = dirs.skillsRoot;
     const anchor = join(destRoot, EM_SKILL_ANCHOR_DIR);
     if (existsSync(anchor) && !opts.force) {
         console.log(`skill already installed at ${anchor}`);
@@ -2967,7 +3224,7 @@ skill
                 `(${removedCount} removed), ${totalUnchanged} unchanged`);
         }
         console.log("in Claude Code, run /event-modeling to start a guided session");
-        installAgentFiles(process.cwd());
+        installAgentFiles(dirs.agentsRoot);
     }
     else {
         await mkdir(destRoot, { recursive: true });
@@ -2976,7 +3233,7 @@ skill
         }
         console.log(`installed event-modeling skill bundle → ${destRoot}`);
         console.log("in Claude Code, run /event-modeling to start a guided session");
-        installAgentFiles(process.cwd());
+        installAgentFiles(dirs.agentsRoot);
     }
     if (opts.agentsMd !== false) {
         console.log(agentsMdMessage(syncAgentsMd(process.cwd())));
@@ -2988,15 +3245,18 @@ skill
     "installed em package (overwrites unconditionally; local edits are never merged, MIL-93)")
     .argument("[path]", "consumer repo root", ".")
     .option("--no-agents-md", "skip writing/updating the AGENTS.md agent-contract section (on by default, MIL-129)")
+    .option("--skills-dir <dir>", SKILLS_DIR_HELP)
+    .option("--agents-dir <dir>", AGENTS_DIR_HELP)
     .action(async (path, opts) => {
     warnVendoredDeprecated();
     const packagedRoot = packagedSkillsRoot();
-    const vendoredRoot = vendoredSkillsRoot(path);
+    const dirs = vendoredDirs(path, opts);
+    const vendoredRoot = dirs.skillsRoot;
     const bundlePlan = planSkillSyncBundle(packagedRoot, vendoredRoot, EM_ALL_SKILL_BUNDLE_DIRS);
     const skillChanges = bundlePlan.reduce((n, { plan }) => n + plan.changes.length, 0);
     // MIL-269 (R32): the fixed agent-file list, never the shared .claude/agents/ directory as a whole.
     const packagedAgents = packagedAgentsRoot();
-    const vendoredAgents = vendoredAgentsRoot(path);
+    const vendoredAgents = dirs.agentsRoot;
     const agentPlan = planAgentSync(packagedAgents, vendoredAgents, EM_AGENT_FILES);
     const totalChanges = skillChanges + agentPlan.changes.length;
     const totalUnchanged = bundlePlan.reduce((n, { plan }) => n + plan.unchangedCount, 0) + agentPlan.unchangedCount;
@@ -3027,9 +3287,13 @@ skill
     .option("--json", "print a JSON document instead of the text report (see docs/cli.md)")
     .option("--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")
+    .option("--skills-dir <dir>", SKILLS_DIR_HELP)
+    .option("--agents-dir <dir>", AGENTS_DIR_HELP)
     .action((path, opts) => {
     const packagedRoot = packagedSkillsRoot();
-    const vendoredRoot = vendoredSkillsRoot(path);
+    // Detection is silent here: a check prints findings and one verdict line, nothing else.
+    const dirs = resolveVendoredDirs(path, opts);
+    const vendoredRoot = dirs.skillsRoot;
     const ciMode = !!opts.ci || process.env.CI === "true";
     // MIL-231: the plugin signal (a pinned marketplace in .claude/settings*.json) sits beside the
     // vendored signal (the anchor directory). Plugin only -> only the plugin is checked; vendored
@@ -3042,7 +3306,7 @@ skill
     // MIL-269 (R32): the four agent files, only when the vendored bundle is present (a plugin-only
     // repo ships them via the plugin); checked by fixed name, never the shared directory.
     const agents = vendoredPresent
-        ? checkAgentFiles(packagedAgentsRoot(), vendoredAgentsRoot(path), EM_AGENT_FILES)
+        ? checkAgentFiles(packagedAgentsRoot(), dirs.agentsRoot, EM_AGENT_FILES)
         : { findings: [], ok: true };
     const findings = [...vendored.findings, ...agents.findings, ...(pluginCheck?.findings ?? [])];
     const failing = findings.filter((f) => f.code !== "plugin-not-installed-locally" || ciMode);
@@ -3219,7 +3483,74 @@ ci.command("init")
             console.log(`${path} already up to date`);
     }
 });
-const storylineCmd = program.command("storyline").description("storyline blocks (GH #277): advisory helpers for adopting them");
+const storylineCmd = program.command("storyline").description("storylines (GH #277, #421): adopt storyline blocks, split them into storyline model files");
+storylineCmd
+    .command("split")
+    .description("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)")
+    .argument("<file>", "the root .em model")
+    .option("--storyline <name>", "split only this storyline")
+    .option("--dry-run", "print what would be written without touching anything")
+    .option("-f, --force", "overwrite a storyline model file that already exists")
+    .action((file, opts) => {
+    const { model, refs, diagnostics, source } = compileFile(file);
+    printDiagnostics(diagnostics.filter((d) => d.severity === "error"));
+    if (hasErrors(diagnostics)) {
+        console.error("em storyline split: not splitting — fix the errors above");
+        process.exit(1);
+    }
+    if (opts.storyline !== undefined && !(model.storylines ?? []).some((s) => s.name.trim().toLowerCase() === opts.storyline.trim().toLowerCase())) {
+        console.error(`em storyline split: no storyline "${opts.storyline}" (declared: ${(model.storylines ?? []).map((s) => `"${s.name}"`).join(", ") || "none"})`);
+        process.exit(1);
+    }
+    const plan = planStorylineSplit(model, source, opts.storyline);
+    for (const s of plan.skipped)
+        console.log(`skip "${s.storyline}" — ${s.reason}`);
+    if (plan.files.length === 0) {
+        console.log("nothing to split");
+        return;
+    }
+    const rootDir = dirname(file);
+    for (const f of plan.files) {
+        const abs = resolve(rootDir, f.path);
+        if (existsSync(abs) && !opts.force) {
+            console.error(`em storyline split: ${f.path} already exists (use --force to overwrite)`);
+            process.exit(1);
+        }
+    }
+    if (opts.dryRun) {
+        for (const f of plan.files)
+            console.log(`would write ${f.path} (storyline "${f.storyline}", ${f.content.split(/\r?\n/).filter((l) => /^slice\b/.test(l)).length} slice(s))`);
+        console.log(`would rewrite ${file}`);
+        return;
+    }
+    for (const f of plan.files) {
+        const abs = resolve(rootDir, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.content, "utf8");
+        console.log(`wrote ${f.path} (storyline "${f.storyline}")`);
+        // GH #421 step 2: the story's docs (and per-slice diagrams) move beside its file
+        const st = (model.storylines ?? []).find((s) => s.name === f.storyline);
+        const folder = dirname(abs);
+        let moved = 0;
+        for (const i of st?.sliceIndexes ?? []) {
+            for (const ext of [".md", ".svg"]) {
+                const src = join(rootDir, "slices", `${refs.sliceKeys[i]}${ext}`);
+                if (!existsSync(src))
+                    continue;
+                mkdirSync(join(folder, "slices"), { recursive: true });
+                renameSync(src, join(folder, "slices", `${refs.sliceKeys[i]}${ext}`));
+                moved++;
+            }
+        }
+        if (moved > 0)
+            console.log(`  moved ${moved} doc/diagram file(s) into ${relative(rootDir, join(folder, "slices"))}/`);
+    }
+    writeFileSync(file, plan.rootText, "utf8");
+    console.log(`rewrote ${file}: ${plan.files.length} storyline declaration(s) now point at their files`);
+});
 storylineCmd
     .command("suggest")
     .description("advisory (GH #290): propose `storyline` blocks for a model that has none — one per distinct slice " +
@@ -3362,8 +3693,8 @@ program
  *  stands, so an estate sees how many advisory shape findings it carries. Never writes a waive file:
  *  baselining shapes you accept is a decision (`--waive-file`, and a `shape-accepted:` Decisions-log bullet). */
 function printUpgradeShapeSection(file) {
-    const { model, diagnostics, refs, source } = compileFile(file);
-    const all = computeAllDiagnostics(file, model, refs, diagnostics, source);
+    const { model, diagnostics, refs, hashSource } = compileFile(file);
+    const all = computeAllDiagnostics(file, model, refs, diagnostics, hashSource);
     const report = buildShapeReport(all, []);
     console.log("");
     console.log("Shape (em validate --shape, advisory):");
@@ -3389,18 +3720,17 @@ function compileFile(file, opts = {},
 // watcher (and the --serve live view with it) is a session-ending failure.
 // One-shot commands keep the exit-with-message behavior.
 { survive = false } = {}) {
-    let source;
-    try {
-        source = readFileSync(file, "utf8");
-    }
-    catch {
+    if (!existsSync(file)) {
         if (survive)
             throw new Error(`cannot read ${file}`);
         console.error(`cannot read ${file}`);
         process.exit(1);
     }
     try {
-        return { ...compile(source, opts), source };
+        // GH #421: the root plus every storyline model file it declares, compiled as one model.
+        // `source` is the root text (line-based edits of root entities), `files`/`sources` the
+        // storyline files, `hashSource` what a model-level hash covers.
+        return compileModelFile(file, opts);
     }
     catch (e) {
         if (e instanceof ParseError) {
@@ -3409,6 +3739,12 @@ function compileFile(file, opts = {},
             console.error(`parse error in ${file} ${e.message}`);
             process.exit(1);
         }
+        if (e instanceof ModelLoadError) {
+            if (survive)
+                throw new Error(e.message);
+            console.error(e.message);
+            process.exit(1);
+        }
         throw e;
     }
 }
@@ -3424,7 +3760,8 @@ function compileFile(file, opts = {},
  *  report, since its whole job is logging which categories fired. `source` is the `.em` file's
  *  own text — only `validateModelVersionStale` reads it (the modelHash comparison). */
 function computeAllDiagnostics(file, model, refs, diagnostics, source) {
-    return [
+    // GH #421: the fs-aware rules below point at elements too — give each its storyline file.
+    return attributeDiagnosticFiles(model, refs, [
         ...diagnostics,
         ...validateLineage(model, refs, dirname(file)),
         ...validateFrontmatterCoherence(model, refs, dirname(file)),
@@ -3433,7 +3770,7 @@ function computeAllDiagnostics(file, model, refs, diagnostics, source) {
         ...validateOrphanedSliceDocs(model, refs, dirname(file)),
         ...validateModelVersionStale(model, refs, dirname(file), source),
         ...validateInvariants(model, refs, dirname(file)),
-    ];
+    ]);
 }
 /** Read a file's text, or exit with a clear error — shared by `em diff` (both forms) and
  *  `em glossary`, which each read one or more plain `.em` files off disk before compiling. */
@@ -3447,18 +3784,31 @@ function readFileOrExit(file) {
     }
 }
 /** Parse+normalize source text for `em diff`, exiting with a labeled parse error on failure. */
-function compileSource(source, label) {
+function compileSource(source, label, read) {
     try {
-        return compile(source);
+        // GH #421: a split model's storyline files come through `read` (disk, or git at a revision).
+        return compileModelText(source, read, label);
     }
     catch (e) {
         if (e instanceof ParseError) {
             console.error(`parse error in ${label} ${e.message}`);
             process.exit(1);
         }
+        if (e instanceof ModelLoadError) {
+            console.error(e.message);
+            process.exit(1);
+        }
         throw e;
     }
 }
+/** GH #421: a reader for a text with no file behind it — a split root cannot be compiled from text alone. */
+const noStorylineFiles = (rel) => {
+    throw new ModelLoadError(`storyline model file ${rel} is not available for this text`);
+};
+/** GH #421: storyline model files of `file` as of git revision `rev`. */
+function gitReader(file, rev) {
+    return (rel) => readAtRevision(join(dirname(file), rel), rev);
+}
 /** Resolve `file`'s content at a git revision, exiting with a clear error on any git failure. */
 function readAtRevision(file, rev) {
     const result = resolveRevision(file, rev);
@@ -3469,9 +3819,11 @@ function readAtRevision(file, rev) {
     return result.content;
 }
 /** Shared body for both `em diff` forms: compile both sides, gate on errors, print, exit-code. */
-function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json, lineage) {
-    const oldResult = compileSource(oldSource, oldLabel);
-    const newResult = compileSource(newSource, newLabel);
+function runDiff(oldSource, oldLabel, newSource, newLabel, exitCode, json, lineage, 
+// GH #421: how each side's storyline model files are read (disk, or git at a revision).
+readers = { old: noStorylineFiles, new: noStorylineFiles }) {
+    const oldResult = compileSource(oldSource, oldLabel, readers.old);
+    const newResult = compileSource(newSource, newLabel, readers.new);
     printDiagnostics(oldResult.diagnostics);
     printDiagnostics(newResult.diagnostics);
     if (hasErrors(oldResult.diagnostics) || hasErrors(newResult.diagnostics)) {
@@ -3561,7 +3913,7 @@ function printDiagnostics(diags) {
     if (diags.length === 0)
         return;
     for (const d of diags) {
-        const line = formatDiagnostic(d);
+        const line = formatDiagnosticWithFile(d);
         if (d.severity === "error")
             console.error(line);
         else