@milehimikey/em-portal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 milehimikey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# em-portal
+
+A stakeholder-facing, **fully static** portal for [`em`](https://github.com/milehimikey/em)
+event models — a read-only, multi-model browser built entirely from `em export`/`em status`
+JSON. No server, no database, no storage of its own: git stays the only history store, and
+`em-portal build` is a pure function of your `.em` files that a CI job runs and publishes to
+static hosting (GitHub Pages, an S3/GCS bucket, ...).
+
+This executes the decision recorded in the `em` repo at
+[`docs/decisions/mil-162-teachable-navigator.md`](https://github.com/milehimikey/em/blob/main/docs/decisions/mil-162-teachable-navigator.md):
+a **separate add-on tool**, not a rework of `em catalog`, built for the audience `em catalog`
+names but doesn't fully serve — a non-technical stakeholder who wants "is this healthy" up
+front and a way to navigate a system of several models, not a flat per-model site.
+
+## Status
+
+**0.1.0 — read-only multi-model browser.** See [What 0.1.0 includes](#what-01-includes) below.
+
+## Quickstart
+
+```bash
+npm install --save-dev @milehimikey/em @milehimikey/em-portal
+npx em-portal build models/*/*.em -o site
+```
+
+```
+site/
+  index.html                 # landing page: em status rollup (state up front)
+  <model-key>/
+    index.html                # model page: diagram + slice table
+    diagram.svg
+    slices/
+      <slice-key>.html         # slice page: diagram, doc, driftSignal, PR link
+      <slice-key>.svg
+```
+
+Open `site/index.html` directly (`file://` works, no server needed) or serve the directory with
+anything that serves static files.
+
+### CLI
+
+```
+em-portal build <models...> [options]
+
+Arguments:
+  models             Paths to .em model files (same argument form as `em status`)
+
+Options:
+  -o, --out <dir>     Output directory (default: "site")
+  --title <title>     Site title shown on the landing page (default: "em portal")
+  --tests <dir>       Directory to scan for INV-* test citations (enables invariant
+                       coverage on the landing page — forwarded to `em status --tests`)
+  --repo <path>       Git repo to compute commits-behind-HEAD in (forwarded to
+                       `em status --repo`; default: each model's own directory)
+```
+
+Multiple models in one invocation is how a multi-model system's cross-model index and
+`em status` rollup get built — same "one directory per model" convention
+[`examples/multi-model`](https://github.com/milehimikey/em/tree/main/examples/multi-model) in
+the em repo documents:
+
+```bash
+em-portal build models/checkout/checkout.em models/fulfillment/fulfillment.em -o site
+```
+
+## How it works
+
+em-portal is a **separate package from `em`** — it never imports em's internal modules. Every
+fact it shows comes from shelling out to the installed `em` CLI (a real dependency of your
+project, resolved the normal npm way):
+
+- `em export <file>` — the normalized model as JSON (schema 1.8+): slices, elements, stable
+  `ref`s, the slice-doc frontmatter join (`status`, `driftSignal`, `implementedIn`, ...).
+- `em status <files...> --json` — the state-of-the-system rollup across every model given:
+  slices by lifecycle status, drift-signal breakdown, invariant coverage (with `--tests`),
+  open issues, and freshness (last-conformed revision, commits/slice-PRs behind HEAD).
+- `em render <file>` / `em render <file> --slice <name>` — the model's full diagram and each
+  slice's own canonical-pattern diagram (SVG).
+
+`em export`'s doc join is deliberately frontmatter-only ("never the markdown body" — see the em
+repo's `docs/cli.md`); em-portal reads the bound `slices/<key>.md` file itself (the same
+`doc.path` the join already names) and renders its body with `marked`, the same markdown engine
+`em catalog` uses.
+
+**Consumers must tolerate unknown fields.** em's own versioning policy is additive-minor-bump,
+breaking-major-bump; `src/em/exportDoc.ts`/`statusDoc.ts` declare only the fields em-portal
+reads (nothing is `.strict()`-validated), and `checkExportSchemaCompatible`/
+`checkStatusSchemaCompatible` only warn on a **major** version mismatch. MIL-171 (landing in the
+em repo in parallel with this ticket) adds `owner:`/`tracking:` fields to the doc join — this is
+exactly the kind of change em-portal's ingestion layer is built to shrug off.
+
+## Deep links (MIL-173)
+
+Portal URLs are built on em's own stable element `ref`s (`<sliceKey>/<kind>.<slug>`, assigned by
+`em export` and edit-stable — inserting or reordering slices never changes an existing ref). One
+addressing scheme for both audiences: an agent citing `checkout/event.order-placed` (via
+`em query`/MCP) and a stakeholder clicking the matching row on a slice page mean the same
+element.
+
+A slice page's URL already **is** its slice's own key (`<model-key>/slices/<sliceKey>.html`);
+every element row on that page carries its full `ref` as both its DOM `id` and a visible,
+copyable `#`-fragment permalink next to it (`src/refs.ts`). The full deep link to one element is:
+
+```
+<model-key>/slices/<sliceKey>.html#<sliceKey>/<kind>.<slug>
+```
+
+For example, in `examples/order-fulfillment`'s `Checkout` slice, the `Submit Payment` command's
+deep link is:
+
+```
+order-fulfillment/slices/checkout.html#checkout/command.submit-payment
+```
+
+`src/refs.ts` exports `elementDeepLink(modelKey, ref)` / `sliceUrl(modelKey, sliceKey)` to build
+these, and `parseDeepLink(link)` to resolve one back into `{ modelKey, sliceKey, elementRef }`
+(returns `null` for anything not shaped like a page this portal generates — an external URL, the
+site's own landing page, ...). The landing page's cross-model links table (below) uses the same
+builder to link straight at the specific publishing/referencing element on each side, not just
+the two models' index pages. Refs never depend on layout/coordinates or on the portal's own
+directory-naming choices for the `<model-key>` segment (see `src/slug.ts`) — only on `em
+export`'s own ref-stability guarantee.
+
+## Multi-model navigation
+
+The landing page indexes every model given to `em-portal build` and rolls up `em status` across
+all of them. Where one model's `public` event feeds another model's slice, em-portal resolves
+that as a **cross-model link** (`src/crossModel.ts`) — matching a public event's exact name
+against every other model's element names. This is a naming-convention join, **not** a
+compiler-verified reference: em has no DSL-level construct for "this element's trigger is
+another model file's public event" (confirmed against `em validate`'s `view-from-unresolved`
+error — see the decision doc). If a link looks wrong, the fix is in the `.em` naming, not in
+em-portal.
+
+## What 0.1.0 includes
+
+- Package scaffold, CLI (`em-portal build`), export/status-ingestion tolerant of schema minor
+  bumps.
+- Landing page: the `em status` rollup up front (slice counts, drift signal, invariant coverage,
+  open issues, freshness/commits-behind-HEAD per model) — a reader's first question ("is this
+  healthy") answered before any slice list.
+- Multi-model index + the cross-model link heuristic.
+- Per-model pages (diagram + slice table) and per-slice pages (diagram, rendered doc,
+  driftSignal, implemented-in link).
+- Deep links on em's stable element refs (MIL-173) — see [Deep links](#deep-links-mil-173) above.
+- Fully static, self-contained output; deterministic builds (same inputs -> byte-identical
+  site, verified in `test/build.test.ts`); no LLM anywhere.
+
+**Deferred to 0.2.0** (MIL-174, "guided first read"): the onboarding/teaching layer — real
+click-driven interaction that annotates a first-time reader's own model as they encounter each
+element/pattern kind, rather than a glossary page. 0.1.0's pages are informative but not
+teaching-aware.
+
+**Deferred to 0.3.0** (MIL-175, "async review intake"): a "raise a question" affordance on a
+slice page, triaged into an `issue "..."` marker through the normal ratified path. 0.1.0 is
+read-only.
+
+**Also deferred / open, not yet built**:
+- A real GitHub Pages/bucket deploy workflow wired to a specific target repo — see
+  [CI publish recipe](#ci-publish-recipe) below for the pattern; this repo's own CI only builds
+  and tests, since it has no real event models of its own to publish.
+- Parallelizing the per-model `em export`/`em render` calls (they run sequentially today — see
+  [Open questions](#open-questions)).
+- Any client-side JS (search, filtering, sort) — pages are plain static HTML, same posture as
+  `em catalog`.
+
+## CI publish recipe
+
+A downstream project (one that actually has `.em` models) publishes the portal from CI like
+this — build, then hand the output directory to whichever static-hosting deploy action you use:
+
+```yaml
+# .github/workflows/portal.yml
+name: em-portal
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npx em-portal build models/*/*.em -o site
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: site }
+      - uses: actions/deploy-pages@v4
+```
+
+This repo's own [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs `npm test` (which
+builds the portal against the fixture models under `test/fixtures/`) on every push — the build
+half of the recipe above, exercised continuously; the deploy half needs a real target repo with
+real models, which this package intentionally isn't.
+
+## Test fixtures
+
+`test/fixtures/` holds `.em` files (plus their `slices/*.md` docs) copied verbatim from the `em`
+repo's own `examples/order-fulfillment` and `examples/multi-model`, generated by running that
+`em` checkout's CLI (`npx tsx src/cli.ts` from the em repo) against those examples and confirming
+they still compile clean. `test/fixtures/invalid/broken.em` is hand-written to exercise the
+refuse-on-error path (an unresolvable `view ... from`). `test/fixtures/cross-model/` is a small
+hand-written pair (`producer`/`consumer`) exercising the cross-model link heuristic end to end: a
+`public` event in one model whose exact name appears inside two of the other model's element
+names.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm test           # vitest — packs and shells out to the real @milehimikey/em devDependency
+npm run typecheck
+```
+
+`@milehimikey/em` is installed from a packed tarball checked into `vendor/` (`npm pack` output
+from the em repo) rather than a registry version, since em-portal is developed alongside
+unreleased em changes; see `package.json`'s devDependency and re-pack with a newer em checkout
+as needed (`cd ../em && npm run build && npm pack && cp *.tgz ../em-portal/vendor/`, then bump
+the `vendor/*.tgz` filename referenced in `package.json` and `npm install`). A production
+install of em-portal in a downstream project instead takes `@milehimikey/em` as a normal
+(published) dependency — see [Quickstart](#quickstart).
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,21 @@
+export interface BuildOptions {
+    outDir: string;
+    title?: string;
+    testsDir?: string;
+    repo?: string;
+}
+export interface BuildTiming {
+    file: string;
+    exportMs: number;
+    renderMs: number;
+}
+export interface BuildResult {
+    models: number;
+    slices: number;
+    crossModelLinks: number;
+    warnings: string[];
+    timing: BuildTiming[];
+    statusTimingMs: number;
+    totalMs: number;
+}
+export declare function buildPortal(files: string[], opts: BuildOptions): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MIT
+// Orchestrates the portal's static-site build: one `em export --json` +
+// `em render` pass per input model, one `em status --json` pass across all of
+// them, the cross-model link heuristic, then every page written to disk.
+//
+//   <outDir>/
+//     index.html                 landing page: em status rollup + model index
+//     <model-key>/
+//       index.html                model page: diagram + slice table
+//       diagram.svg
+//       slices/
+//         <slice-key>.html        slice page: diagram, doc, driftSignal, PR link
+//         <slice-key>.svg
+//
+// Every model gets its own output directory (mirroring `em catalog`'s
+// convention) so slice keys from different models can never collide, even
+// without a cross-file dedupe pass.
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { emExportJson, emRenderModel, emRenderSlice, emStatusJson } from "./em/run.js";
+import { checkExportSchemaCompatible } from "./em/exportDoc.js";
+import { renderDocBody } from "./em/docBody.js";
+import { checkStatusSchemaCompatible } from "./em/statusDoc.js";
+import { buildCrossModelLinks } from "./crossModel.js";
+import { dedupe, kebabSlug } from "./slug.js";
+import { renderIndexPage } from "./pages/index.js";
+import { renderModelPage } from "./pages/model.js";
+import { renderSlicePage } from "./pages/slice.js";
+export async function buildPortal(files, opts) {
+    const t0 = performance.now();
+    if (files.length === 0)
+        throw new Error("em-portal build: at least one model file is required");
+    const outDir = opts.outDir;
+    await mkdir(outDir, { recursive: true });
+    const warnings = [];
+    const usedModelKeys = new Set();
+    const compiled = [];
+    const modelSummaries = [];
+    const timing = [];
+    let sliceCount = 0;
+    for (const file of files) {
+        const tExportStart = performance.now();
+        const doc = (await emExportJson(file));
+        const exportWarning = checkExportSchemaCompatible(doc);
+        if (exportWarning)
+            warnings.push(`${file}: ${exportWarning}`);
+        for (const d of doc.diagnostics) {
+            if (d.severity === "warning")
+                warnings.push(`${file}:${d.line ?? "?"}: ${d.message}`);
+        }
+        const tExportEnd = performance.now();
+        const modelKey = dedupe(kebabSlug(doc.model.name ?? basename(file, extname(file))), usedModelKeys);
+        const modelDir = join(outDir, modelKey);
+        const slicesDir = join(modelDir, "slices");
+        await mkdir(slicesDir, { recursive: true });
+        const tRenderStart = performance.now();
+        const diagramFile = "diagram.svg";
+        await emRenderModel(file, join(modelDir, diagramFile));
+        const sliceSummaries = [];
+        for (const slice of doc.model.slices) {
+            const sliceDiagramFile = `${slice.key}.svg`;
+            await emRenderSlice(file, slice.name, join(slicesDir, sliceDiagramFile));
+            const page = renderSlicePage({
+                modelName: doc.model.name ?? modelKey,
+                modelKey,
+                diagramFile: `../${diagramFile}`,
+                sliceDiagramFile,
+                slice,
+                pattern: slice.pattern,
+                doc: slice.doc,
+                docBodyHtml: renderDocBody(file, slice.doc.path),
+            });
+            await writeFile(join(slicesDir, `${slice.key}.html`), page, "utf8");
+            sliceSummaries.push({
+                key: slice.key,
+                name: slice.name,
+                pattern: slice.pattern,
+                hasDoc: slice.doc.found,
+                status: slice.doc.status,
+                driftSignal: slice.doc.driftSignal,
+            });
+            sliceCount++;
+        }
+        const tRenderEnd = performance.now();
+        const modelPage = renderModelPage({
+            modelKey,
+            modelName: doc.model.name ?? modelKey,
+            file,
+            diagramFile,
+            slices: sliceSummaries,
+        });
+        await writeFile(join(modelDir, "index.html"), modelPage, "utf8");
+        modelSummaries.push({
+            key: modelKey,
+            name: doc.model.name ?? modelKey,
+            file,
+            sliceCount: doc.model.slices.length,
+            slices: sliceSummaries,
+        });
+        compiled.push({ modelKey, file, doc });
+        timing.push({
+            file,
+            exportMs: tExportEnd - tExportStart,
+            renderMs: tRenderEnd - tRenderStart,
+        });
+    }
+    const tStatusStart = performance.now();
+    const statusDoc = (await emStatusJson(files, { testsDir: opts.testsDir, repo: opts.repo }));
+    const statusWarning = checkStatusSchemaCompatible(statusDoc);
+    if (statusWarning)
+        warnings.push(statusWarning);
+    const tStatusEnd = performance.now();
+    const crossModelLinks = buildCrossModelLinks(compiled);
+    const summary = {
+        title: opts.title ?? "em portal",
+        models: modelSummaries,
+        crossModelLinks,
+    };
+    const indexHtml = renderIndexPage(statusDoc, summary);
+    await writeFile(join(outDir, "index.html"), indexHtml, "utf8");
+    const t1 = performance.now();
+    return {
+        models: modelSummaries.length,
+        slices: sliceCount,
+        crossModelLinks: crossModelLinks.length,
+        warnings,
+        timing,
+        statusTimingMs: tStatusEnd - tStatusStart,
+        totalMs: t1 - t0,
+    };
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+import { Command } from "commander";
+import { buildPortal } from "./build.js";
+import { EmCliError } from "./em/run.js";
+const program = new Command();
+program
+    .name("em-portal")
+    .description("Stakeholder-facing static portal for em event models")
+    .version("0.1.0");
+program
+    .command("build")
+    .description("Build a static, read-only multi-model portal site from one or more .em model files")
+    .argument("<models...>", "Paths to .em model files (same argument form as `em status`)")
+    .option("-o, --out <dir>", "Output directory", "site")
+    .option("--title <title>", "Site title shown on the landing page", "em portal")
+    .option("--tests <dir>", "Directory to scan for INV-* test citations (enables invariant coverage on the landing page)")
+    .option("--repo <path>", "Git repo to compute commits-behind-HEAD in (default: each model's own directory)")
+    .action(async (models, options) => {
+    try {
+        const result = await buildPortal(models, {
+            outDir: options.out,
+            title: options.title,
+            testsDir: options.tests,
+            repo: options.repo,
+        });
+        for (const w of result.warnings)
+            console.warn(`warning: ${w}`);
+        console.log(`${result.models} model(s), ${result.slices} slice(s), ${result.crossModelLinks} cross-model link(s) — wrote ${options.out}/ in ${result.totalMs.toFixed(0)}ms`);
+    }
+    catch (err) {
+        if (err instanceof EmCliError) {
+            process.stderr.write(`${err.message}\n`);
+            if (err.stdout.trim())
+                process.stderr.write(`${err.stdout}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+});
+program.parseAsync(process.argv);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,+BAA+B;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,sDAAsD,CAAC;KACnE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,oFAAoF,CAAC;KACjG,QAAQ,CAAC,aAAa,EAAE,8DAA8D,CAAC;KACvF,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,CAAC;KACrD,MAAM,CAAC,iBAAiB,EAAE,sCAAsC,EAAE,WAAW,CAAC;KAC9E,MAAM,CAAC,eAAe,EAAE,6FAA6F,CAAC;KACtH,MAAM,CAAC,eAAe,EAAE,kFAAkF,CAAC;KAC3G,MAAM,CAAC,KAAK,EAAE,MAAgB,EAAE,OAAsE,EAAE,EAAE;IACzG,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE;YACvC,MAAM,EAAE,OAAO,CAAC,GAAG;YACnB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,KAAK;YACvB,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAC;QACH,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CACT,GAAG,MAAM,CAAC,MAAM,cAAc,MAAM,CAAC,MAAM,cAAc,MAAM,CAAC,eAAe,gCAAgC,OAAO,CAAC,GAAG,QAAQ,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAChK,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YACzC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;YAC/D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/crossModel.d.ts

@@ -0,0 +1,14 @@
+import { ExportDoc } from "./em/exportDoc.js";
+export interface CompiledModel {
+    modelKey: string;
+    file: string;
+    doc: ExportDoc;
+}
+export interface CrossModelLink {
+    eventName: string;
+    fromModelKey: string;
+    fromRef: string;
+    toModelKey: string;
+    toElementRef: string;
+}
+export declare function buildCrossModelLinks(compiled: CompiledModel[]): CrossModelLink[];

package/dist/crossModel.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+// The cross-model navigation join (MIL-162's "multi-model navigation"
+// property #3). em has no DSL-level construct for "this element's trigger is
+// another model file's public event" — each model compiles independently,
+// and `from` only resolves within the model being compiled. So the only
+// thing carried across independently-built `em export` documents today is a
+// public event's exact NAME (docs/dsl.md "Integration surface"). This is
+// exactly that heuristic join, ported from prototypes/portal-spike/spike.ts's
+// buildCrossModelLinks in the em repo (the MIL-162 prototype that tested this
+// approach at scale) — pure string matching over the independently-computed
+// export JSON for each model, no access to em's internal model objects, no
+// LLM, no fuzzy matching. It's honest about what it is: a naming-convention
+// join with no compiler guarantee behind it (see the decision doc's "What
+// the prototype found" section).
+export function buildCrossModelLinks(compiled) {
+    const publicEventsByName = new Map();
+    for (const c of compiled) {
+        for (const slice of c.doc.model.slices) {
+            for (const el of slice.elements) {
+                if (el.kind === "event" && el.public) {
+                    publicEventsByName.set(el.name, { modelKey: c.modelKey, ref: el.ref });
+                }
+            }
+        }
+    }
+    const links = [];
+    for (const c of compiled) {
+        for (const slice of c.doc.model.slices) {
+            for (const el of slice.elements) {
+                for (const [eventName, source] of publicEventsByName) {
+                    // An element referencing its OWN model's public event isn't a cross-model link.
+                    if (source.modelKey === c.modelKey)
+                        continue;
+                    if (el.name.includes(eventName)) {
+                        links.push({
+                            eventName,
+                            fromModelKey: source.modelKey,
+                            fromRef: source.ref,
+                            toModelKey: c.modelKey,
+                            toElementRef: el.ref,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return links;
+}
+//# sourceMappingURL=crossModel.js.map

package/dist/crossModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crossModel.js","sourceRoot":"","sources":["../src/crossModel.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,sEAAsE;AACtE,6EAA6E;AAC7E,0EAA0E;AAC1E,wEAAwE;AACxE,4EAA4E;AAC5E,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,iCAAiC;AAkBjC,MAAM,UAAU,oBAAoB,CAAC,QAAyB;IAC5D,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA6C,CAAC;IAChF,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACvC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAChC,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;oBACrC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACvC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAChC,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,kBAAkB,EAAE,CAAC;oBACrD,gFAAgF;oBAChF,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;wBAAE,SAAS;oBAC7C,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;wBAChC,KAAK,CAAC,IAAI,CAAC;4BACT,SAAS;4BACT,YAAY,EAAE,MAAM,CAAC,QAAQ;4BAC7B,OAAO,EAAE,MAAM,CAAC,GAAG;4BACnB,UAAU,EAAE,CAAC,CAAC,QAAQ;4BACtB,YAAY,EAAE,EAAE,CAAC,GAAG;yBACrB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/em/docBody.d.ts

@@ -0,0 +1,5 @@
+/** Returns rendered HTML for the slice doc bound at `docRelPath` (relative to
+ *  `modelFile`'s own directory), or `null` if the file can't be read — a
+ *  routine, non-fatal state (no doc bound, or a stale `path` from a `found:
+ *  false` join). */
+export declare function renderDocBody(modelFile: string, docRelPath: string): string | null;

package/dist/em/docBody.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// `em export`'s slice-doc join is deliberately frontmatter-only — "never the
+// markdown body" (docs/cli.md) — so a portal that wants to show the rendered
+// doc has to read and render the body itself. This reads the same
+// `slices/<key>.md` file the join's own `path` field names (resolved
+// relative to the `.em` file's directory, the same sibling-file convention
+// every doc-aware em command uses), strips the leading YAML frontmatter
+// block, and renders the remainder with `marked` — the same markdown engine
+// em's own catalog/sliceDoc.ts uses, so headings/lists/code fences render
+// the same way a reader would see in `em catalog`.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { marked } from "marked";
+function stripFrontmatter(markdown) {
+    if (!markdown.startsWith("---"))
+        return markdown;
+    const lines = markdown.split("\n");
+    if (lines[0].trim() !== "---")
+        return markdown;
+    const closeIndex = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    if (closeIndex === -1)
+        return markdown;
+    return lines.slice(closeIndex + 1).join("\n");
+}
+/** Returns rendered HTML for the slice doc bound at `docRelPath` (relative to
+ *  `modelFile`'s own directory), or `null` if the file can't be read — a
+ *  routine, non-fatal state (no doc bound, or a stale `path` from a `found:
+ *  false` join). */
+export function renderDocBody(modelFile, docRelPath) {
+    const absPath = join(dirname(modelFile), docRelPath);
+    let raw;
+    try {
+        raw = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const body = stripFrontmatter(raw).trim();
+    if (!body)
+        return null;
+    return marked.parse(body, { async: false });
+}
+//# sourceMappingURL=docBody.js.map

package/dist/em/docBody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docBody.js","sourceRoot":"","sources":["../../src/em/docBody.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,6EAA6E;AAC7E,6EAA6E;AAC7E,kEAAkE;AAClE,qEAAqE;AACrE,2EAA2E;AAC3E,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,mDAAmD;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,SAAS,gBAAgB,CAAC,QAAgB;IACxC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC;IAChF,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC;AAED;;;oBAGoB;AACpB,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,UAAkB;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;IACrD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAW,CAAC;AACxD,CAAC"}