@milehimikey/em 1.20.0 → 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,12 +15,14 @@ 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";
@@ -68,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";
@@ -102,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";
@@ -117,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). */
@@ -201,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);
@@ -239,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) {
@@ -261,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, {
@@ -441,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);
@@ -452,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")
@@ -475,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;
@@ -596,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);
@@ -617,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);
@@ -634,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:`);
@@ -739,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);
@@ -746,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);
@@ -758,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")
@@ -1445,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));
@@ -1489,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);
@@ -1745,6 +1805,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 +1851,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 +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(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 +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");
@@ -1892,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)
@@ -1908,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
@@ -2310,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");
@@ -2372,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))
@@ -2680,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
@@ -3014,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 " +
@@ -3066,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;
@@ -3088,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}`);
@@ -3121,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 });
@@ -3130,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())));
@@ -3142,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;
@@ -3181,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
@@ -3196,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);
@@ -3373,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 " +
@@ -3516,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):");
@@ -3543,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) {
@@ -3563,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;
     }
 }
@@ -3578,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)),
@@ -3587,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. */
@@ -3601,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);
@@ -3623,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)) {
@@ -3715,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