@milehimikey/em 1.20.0 → 1.22.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,16 +15,19 @@ 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 { resolveWatchStoryline, storylineFileFor, storylineVariants } from "./cli/watchStoryline.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 { generateContract, runApiCheck, formatApiCheckText, runApiSurface, formatApiSurfaceText } from "./cli/api.js";
 import { buildApiCheckJson } from "./emit/apiCheckJson.js";
+import { buildApiSurfaceJson } from "./emit/apiSurfaceJson.js";
 import { buildValidateJson, buildShapeJson, buildSliceReadyJson, buildValidateListJson, collectMarkers } from "./emit/validateJson.js";
 import { buildDiffJson } from "./emit/diffJson.js";
 import { diffModels, formatModelDiff, hasChanges } from "./model/diff.js";
@@ -43,10 +47,11 @@ import { observeSigners, renderRoster } from "./roster/init.js";
 import { rosterContextFor } from "./roster/context.js";
 import { computeModelKey } from "./model/qualifiedRef.js";
 import { checkRoster, formatRosterCheck, buildRosterCheckJson, grandfatheredNotice } from "./roster/check.js";
-import { applyEngagementClose, applyEngagementSet, buildNewEngagement, buildUnitIndex, effectiveTracking, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
+import { applyEngagementClose, applyEngagementSet, applyEngagementSetContext, buildNewEngagement, buildUnitIndex, effectiveTracking, engagementMembersFor, engagementPlanFor, engagementStatusFor, formatEngagementPlanText, formatEngagementStatusText, } from "./cli/engagement.js";
 import { LEDGER_STATES, engagementPath, loadEngagement, readOpenEngagements } from "./cli/engagementFile.js";
-import { buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
+import { buildEngagementBriefJson, buildEngagementFoundationJson, buildEngagementPlanJson, buildEngagementStatusJson } from "./emit/engagementJson.js";
 import { checkFoundation, formatFoundationText } from "./cli/engagementFoundation.js";
+import { engagementBriefFor, formatEngagementBriefText } from "./cli/engagementBrief.js";
 import { detectSliceDocCollisions } from "./catalog/modelCollisionValidate.js";
 import { checkLedger, readLedgerWaiverTrailers, applyLedgerWaivers } from "./cli/ledgerCheck.js";
 import { planMigration, verifyMigration } from "./cli/migrateReactionShape.js";
@@ -68,7 +73,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";
@@ -95,13 +100,15 @@ import { runDefer, runDeferFromIssue } from "./cli/defer.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 { runBindingsCheck, buildBindingsCheckJson, renderBindingsCheckText } from "./cli/bindings.js";
 import { STATE_FILE_NAME, PHASES, isPhase, loadStateFile, parseState, setPhase, setConformance, setModelVersion, setCertified, setEmVersion, setReview, isValidDateString, modelPathMismatch, } from "./cli/stateFile.js";
 import { findCertifiedVersion, latestModelVersionNumber, modelVersionDrift, runCertifyModelVersion, runModelVersionBump, } from "./cli/modelVersion.js";
-import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldConstitution } from "./templates.js";
+import { STARTER_EM, starterEmFor, scaffoldReadme, scaffoldStateFile, scaffoldConstitution, SLICES_DIR_README, CONTRACTS_DIR_README, MODEL_VERSIONS_DIR_README, CONFORMANCE_BINDINGS_DIR_README, } from "./templates.js";
 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";
@@ -117,6 +124,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). */
@@ -156,7 +165,10 @@ program
     .command("scaffold")
     .description("scaffold a full project: <slug>/<slug>.em, README.md, .event-modeling.md, and " +
     "constitution.md (the implementation constitution — skipped, with a note, in a spec-kit " +
-    "project, where `.specify/memory/constitution.md` IS that document) " +
+    "project, where `.specify/memory/constitution.md` IS that document), plus the standard " +
+    "slices/, contracts/, model-versions/ and conformance/bindings/ directories (each seeded " +
+    "with a one-line README naming what lands there and which command writes it, instead of " +
+    "a .gitkeep) " +
     "(see docs/cli.md — for just a starter .em, use `em init`; for a multi-model project, " +
     "pass --under to nest it under a shared parent directory)")
     .argument("<name>", "model display name — kebab-cased for the directory and file names, used as-is for titles/prose")
@@ -180,6 +192,20 @@ program
     writeFileSync(join(dirPath, `${slugName}.em`), starterEmFor(name));
     writeFileSync(join(dirPath, "README.md"), scaffoldReadme(name, slugName));
     writeFileSync(join(dirPath, STATE_FILE_NAME), scaffoldStateFile(name, slugName, today, PKG_VERSION));
+    // GH #453: the full standardized model-directory family, not just the four files above —
+    // every doc-aware command eventually writes into one of these. Git doesn't track empty
+    // directories, so each gets a one-line README (never a .gitkeep) naming what lands there
+    // and which command writes it.
+    await mkdir(join(dirPath, "slices"), { recursive: true });
+    writeFileSync(join(dirPath, "slices", "README.md"), SLICES_DIR_README);
+    await mkdir(join(dirPath, "contracts"), { recursive: true });
+    writeFileSync(join(dirPath, "contracts", "README.md"), CONTRACTS_DIR_README);
+    await mkdir(join(dirPath, "model-versions"), { recursive: true });
+    writeFileSync(join(dirPath, "model-versions", "README.md"), MODEL_VERSIONS_DIR_README);
+    // conformance/bindings/ (GH #449) — creating it also creates its conformance/ parent, which
+    // otherwise only appears once the conform phase writes its first report/findings file.
+    await mkdir(join(dirPath, "conformance", "bindings"), { recursive: true });
+    writeFileSync(join(dirPath, "conformance", "bindings", "README.md"), CONFORMANCE_BINDINGS_DIR_README);
     // MIL-202: the implementation constitution. One document per project, never two — in a
     // spec-kit project `.specify/memory/constitution.md` already IS that slot, so em defers to it
     // and writes nothing rather than seeding a second, competing copy beside the model. Same
@@ -201,12 +227,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);
@@ -239,6 +270,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) {
@@ -261,7 +313,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, {
@@ -410,6 +462,25 @@ api
     if (!outcome.report.current)
         process.exitCode = 1;
 });
+api
+    .command("surface")
+    .description("the model's public commands, events, views and reachable declared types as a versioned " +
+    "JSON document for companion tools (GH #448, see docs/cli.md)")
+    .argument("<file>", "input .em file")
+    .option("--json", "print a JSON document instead of the text listing (see docs/cli.md)")
+    .action((file, opts) => {
+    const outcome = runApiSurface(file);
+    printDiagnostics(outcome.diagnostics);
+    if (!outcome.ok) {
+        console.error(outcome.message);
+        process.exit(1);
+    }
+    if (opts.json)
+        process.stdout.write(buildApiSurfaceJson(outcome.report) + "\n");
+    else
+        for (const line of formatApiSurfaceText(outcome.report))
+            console.log(line);
+});
 program
     .command("typespec")
     .description("DEPRECATED alias of `em api generate --stdout` (use em api generate)")
@@ -441,7 +512,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);
@@ -452,7 +526,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")
@@ -475,7 +552,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;
@@ -596,8 +673,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);
@@ -617,12 +698,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);
@@ -634,8 +728,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:`);
@@ -739,6 +833,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);
@@ -746,7 +841,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);
@@ -758,6 +853,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")
@@ -1445,8 +1544,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));
@@ -1489,13 +1588,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);
@@ -1679,6 +1778,44 @@ conformFindings
     if (!result.ok)
         process.exit(1);
 });
+const conform = program.command("conform").description("file-contract conformance checks (advisory only, GH #449 — never wired into validate/--slice-ready)");
+const conformBindings = conform.command("bindings").description("per-slice bindings manifests (conformance/bindings/<slice-key>.yaml, see docs/bindings.md)");
+conformBindings
+    .command("check")
+    .description("verify every per-slice bindings manifest (conformance/bindings/<slice-key>.yaml, see " +
+    "docs/bindings.md): each bound element's `ref` resolves against the compiled model, and " +
+    "each bound `file` exists under --repo and contains its `identifier` as a plain substring " +
+    "(grep-level only, never code-parsed — language-agnostic). Distinct failure kinds: an " +
+    "unknown `--slice` key, a missing bindings file, malformed YAML, an unknown slice named " +
+    "inside a file, and an unknown element ref. Advisory only — exit code stays 0 unless " +
+    "--exit-code is given and a binding failed (the opt-in CI gate, same posture as `em refs " +
+    "--reachable-from`).")
+    .argument("<file>", "input .em file")
+    .requiredOption("--repo <path>", "path to the target codebase (bound `file`s resolve relative to it; never required to be a git repository)")
+    .option("--slice <key>", "check only this slice's bindings file (default: every conformance/bindings/*.yaml)")
+    .option("--json", "print a JSON document instead of the text report")
+    .option("--exit-code", "exit 1 if any binding failed (git-diff convention) — the opt-in CI gate")
+    .action((file, opts) => {
+    const { model, diagnostics, refs } = compileFile(file);
+    printDiagnostics(diagnostics);
+    if (hasErrors(diagnostics)) {
+        console.error("em conform bindings check: fix the model's errors above first");
+        process.exit(1);
+    }
+    const sliceKey = opts.slice !== undefined ? resolveSliceOrExit("em conform bindings check", model, refs, opts.slice) : undefined;
+    const result = runBindingsCheck(refs, dirname(file), opts.repo, sliceKey);
+    if (opts.json) {
+        console.log(buildBindingsCheckJson(result));
+    }
+    else {
+        console.log(renderBindingsCheckText(result));
+    }
+    // Same rationale as `em diff`/`em api check`'s --exit-code: set the code rather than
+    // process.exit() so a large --json document piped downstream isn't truncated, and so this
+    // advisory check NEVER fails a run by default (GH #449 — opt-in CI gate only).
+    if (opts.exitCode && !result.ok)
+        process.exitCode = 1;
+});
 const discover = program.command("discover").description("checks for the discover skill's records (GH #295)");
 discover
     .command("triage-check")
@@ -1745,6 +1882,10 @@ program
     // --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.
@@ -1787,14 +1928,26 @@ program
                 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.
+                // --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));
@@ -1812,11 +1965,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(liveFile)}`);
+                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 {
@@ -1833,7 +1991,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");
@@ -1892,9 +2063,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)
@@ -1908,7 +2079,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
@@ -2310,11 +2481,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");
@@ -2368,11 +2539,11 @@ program
     // merged `sliceFacts` above (which spans every input file when several are given).
     const conformance = compiled.map(({ file }) => {
         const facts = factsByFile.get(file) ?? [];
-        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn, shipped: f.shipped }));
+        const sliceDocFacts = facts.map((f) => ({ key: f.key, status: f.rawStatus, implementedIn: f.implementedIn, shipped: f.shipped, file: f.sliceFile }));
         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))
@@ -2630,6 +2801,7 @@ engagement
     .option("--by <name>", "who created the engagement (createdBy)")
     .option("--tracking <key>", "an issue-tracker key or URL the slice PRs cite (a slice doc's own tracking: wins)")
     .option("--pr-title <template>", "PR title template for the slice PRs; {key} = tracking key, {slice} = slice name, {sliceKey} = slice key (default \"{key}: {slice}\", or \"{slice}\" without a key)")
+    .option("--context-doc <path>", "repo-relative path to a document implementers need beyond the slice doc — the constitution, an NFR doc, an ADR (repeatable; GH #455)", (value, previous) => [...previous, value], [])
     .option("--force", "overwrite an existing engagement file with this slug")
     .action((file, slug, opts) => {
     const fail = (m) => {
@@ -2649,7 +2821,7 @@ engagement
     const parallel = /^\d+$/.test(opts.parallel) ? Number(opts.parallel) : NaN;
     const { model, refs } = compileFile(file);
     const path = engagementPath(file, slug);
-    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, prTitle: opts.prTitle ?? null, created: localIsoDate() });
+    const result = buildNewEngagement({ file, model, refs, baseDir: dirname(file) }, { slug, selector, parallel, createdBy: opts.by ?? null, tracking: opts.tracking ?? null, prTitle: opts.prTitle ?? null, context: opts.contextDoc, created: localIsoDate() });
     if (!result.ok)
         return fail(result.message);
     if (existsSync(path) && !opts.force)
@@ -2680,8 +2852,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
@@ -2727,22 +2899,76 @@ engagement
     if (!check.ok)
         process.exitCode = 1;
 });
+engagement
+    .command("brief")
+    .description("GH #454: a deterministic, self-contained per-slice work brief for implementers em does not " +
+    "control (a ticket-driven cloud agent) — the bound slice doc verbatim (or the model's own " +
+    "elements when there is none), model context from the edge list, the public-contract " +
+    "surface, a definition-of-done (bindings manifest skeleton + conform check + isolation + PR " +
+    "title), and the engagement's context: documents. One brief per engagement slice unless " +
+    "--slice narrows it")
+    .argument("<file>", "input .em file")
+    .argument("<slug>", "engagement slug")
+    .option("--slice <key>", "only this slice's brief (export key, display name, or unique prefix)")
+    .option("--inline-context", "embed each context document's full text instead of just its path")
+    .option("--json", "print a JSON document instead of text (same document as the MCP engagement_brief tool)")
+    .action((file, slug, opts) => {
+    const { model, refs } = compileFile(file);
+    // GH #237: an input that resolves to no slice goes through as typed, so the engagement's own
+    // "is not in engagement" refusal (which names what the Ledger holds) still speaks.
+    let sliceKey = null;
+    if (opts.slice !== undefined) {
+        const resolved = resolveSliceKey(model, refs, opts.slice);
+        sliceKey = resolved.ok ? resolved.key : opts.slice;
+    }
+    const result = engagementBriefFor({ file, model, refs, baseDir: dirname(file) }, slug, { sliceKey, inlineContext: opts.inlineContext === true });
+    if (!result.ok) {
+        console.error(`em engagement brief: ${result.message}`);
+        process.exit(1);
+    }
+    process.stdout.write((opts.json ? buildEngagementBriefJson(result.brief) : formatEngagementBriefText(result.brief)) + "\n");
+});
 engagement
     .command("set")
     .description("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")
+    "idempotent; merged is terminal; --state held records a human hold. Or, on its own (no slice " +
+    "key), --context-doc replaces the engagement-level context: list (GH #455)")
     .argument("<file>", "input .em file")
     .argument("<slug>", "engagement slug")
-    .argument("<key>", "slice export key")
-    .requiredOption("--state <state>", `one of: ${LEDGER_STATES.join(" | ")}`)
+    .argument("[key]", "slice export key (omit when using --context-doc alone)")
+    .option("--state <state>", `one of: ${LEDGER_STATES.join(" | ")}`)
     .option("--branch <name>", "the slice's branch")
     .option("--base <name>", "the branch the slice's PR targets")
     .option("--pr <url>", "the slice's PR URL")
+    .option("--context-doc <path>", "repo-relative path to a document implementers need beyond the slice doc (repeatable; replaces the whole engagement-level context: list; GH #455)", (value, previous) => [...previous, value], [])
     .action((file, slug, key, opts) => {
     const fail = (m) => {
         console.error(`em engagement set: ${m}`);
         process.exit(1);
     };
+    const sliceFields = opts.state !== undefined || opts.branch !== undefined || opts.base !== undefined || opts.pr !== undefined;
+    if (opts.contextDoc.length > 0) {
+        if (key !== undefined || sliceFields) {
+            return fail("--context-doc sets the engagement-level context: list on its own — pass it without a slice key or --state/--branch/--base/--pr");
+        }
+        const loaded = loadEngagement(file, slug);
+        if (!loaded.ok)
+            return fail(loaded.message);
+        const result = applyEngagementSetContext(slug, loaded.text, loaded.file, opts.contextDoc);
+        if (!result.ok)
+            return fail(result.message);
+        if (!result.changed) {
+            console.log(`no change: context is already [${result.context.join(", ")}] (${loaded.path})`);
+            return;
+        }
+        writeFileSync(loaded.path, result.text);
+        console.log(`set context: ${result.context.length} path${result.context.length === 1 ? "" : "s"} (${loaded.path})`);
+        return;
+    }
+    if (!key)
+        return fail("a slice export key is required (or pass --context-doc to set the engagement-level context: list)");
+    if (!opts.state)
+        return fail("--state is required when setting a slice");
     const loaded = loadEngagement(file, slug);
     if (!loaded.ok)
         return fail(loaded.message);
@@ -2752,7 +2978,7 @@ engagement
     const resolved = resolveSliceKey(model, refs, key);
     if (resolved.ok)
         key = resolved.key;
-    const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, ...opts });
+    const result = applyEngagementSet({ file, model, refs, baseDir: dirname(file) }, slug, loaded.text, loaded.file, { key, state: opts.state, branch: opts.branch, base: opts.base, pr: opts.pr });
     if (!result.ok)
         return fail(result.message);
     if (!result.changed) {
@@ -3014,17 +3240,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 " +
@@ -3066,9 +3299,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;
@@ -3088,10 +3320,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}`);
@@ -3121,7 +3356,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 });
@@ -3130,7 +3365,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())));
@@ -3142,15 +3377,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;
@@ -3181,9 +3419,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
@@ -3196,7 +3438,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);
@@ -3373,7 +3615,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 " +
@@ -3516,8 +3825,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):");
@@ -3543,18 +3852,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) {
@@ -3563,6 +3871,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;
     }
 }
@@ -3578,7 +3892,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)),
@@ -3587,7 +3902,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. */
@@ -3601,18 +3916,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);
@@ -3623,9 +3951,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)) {
@@ -3715,7 +4045,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