sad-mcp 2.1.0 → 2.2.0

package/dist/usecase/index.d.ts

@@ -1,2 +1,15 @@
-export { validateModel, parseAndValidate, formatIssues } from "./validate.js";
-export type { ValidateResult, ValidationIssue } from "./validate.js";
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function formatIssues(issues: ValidationIssue[]): string;
+export declare function parseAndValidate(jsonText: string): ValidateResult;

package/dist/usecase/index.js

@@ -1 +1,218 @@
-export { validateModel, parseAndValidate, formatIssues } from "./validate.js";
+// Validator for use-case diagramModel JSON (kind: 'use-case').
+// Called by uml_usecase_validate_model MCP tool in tools.ts.
+// Returns all errors and warnings at once so an LLM can self-correct in one pass.
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return "(none)";
+    return issues.map(i => `- [${i.code}] ${i.path}: ${i.message}`).join("\n");
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function hasHebrew(s) {
+    return /[\u0590-\u05FF\uFB1D-\uFB4F]/.test(s);
+}
+const SEND_ONLY_PREFIXES = [
+    /^שליחת /i, /^הודעה ל/i, /^הודעת /i, /^משלוח /i,
+    /^Send /i, /^Print /i, /^Notify /i,
+];
+const PHYSICAL_VERB_PREFIXES = [
+    /^ביצוע /i, /^הכנת /i, /^ספירת /i, /^מסירת /i,
+    /^תשלום ב/i, /^Perform /i, /^Execute /i,
+];
+const UNSAFE_WF = [
+    /<script\b/i, /\son\w+\s*=/i, /<iframe\b/i,
+    /src\s*=\s*["']https?:/i, /href\s*=\s*["']https?:/i,
+    /@import\b/i, /<style\b/i,
+];
+function wireframeSafe(html) {
+    return !UNSAFE_WF.some(rx => rx.test(html));
+}
+// ── Main validator ────────────────────────────────────────────────────────
+export function parseAndValidate(jsonText) {
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, warnings: [], issues: [{ path: "(root)", code: "invalid-json", message: `JSON parse failed: ${msg}` }] };
+    }
+    const errors = [];
+    const warnings = [];
+    const err = (path, code, message) => errors.push({ path, code, message });
+    const warn = (path, code, message) => warnings.push({ path, code, message });
+    const m = raw;
+    if (!m || typeof m !== "object") {
+        err("(root)", "not-object", "model must be an object");
+        return { ok: false, issues: errors, warnings };
+    }
+    if (m["kind"] !== "use-case")
+        err("kind", "wrong-kind", `expected "use-case", got "${m["kind"]}"`);
+    const parts = Array.isArray(m["parts"]) ? m["parts"] : [];
+    if (!Array.isArray(m["parts"]) || parts.length === 0)
+        err("parts", "missing-parts", "parts array is required and must be non-empty");
+    // Narrative field checks at model level
+    for (const [key, val] of [["assumptions", m["assumptions"]], ["openQuestions", m["openQuestions"]]]) {
+        if (Array.isArray(val)) {
+            val.forEach((item, i) => {
+                if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                    err(`${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                }
+            });
+        }
+    }
+    for (const [pi, part] of parts.entries()) {
+        const pp = `parts[${pi}]`;
+        const elements = Array.isArray(part["elements"]) ? part["elements"] : [];
+        const relationships = Array.isArray(part["relationships"]) ? part["relationships"] : [];
+        const actorIds = new Set();
+        const ucIds = new Set();
+        // Index actors and UCs
+        for (const el of elements) {
+            if (el["kind"] === "actor" && typeof el["id"] === "string")
+                actorIds.add(el["id"]);
+            if (el["kind"] === "useCase" && typeof el["id"] === "string")
+                ucIds.add(el["id"]);
+        }
+        // Build relationship indexes
+        const includesByTarget = new Map(); // targetUcId → [baseUcId...]
+        const assocsByUc = new Map(); // ucId → [actorId...]
+        const includeSet = new Set(); // "from:to"
+        let totalIncludeExtend = 0;
+        for (const rel of relationships) {
+            if (rel["kind"] === "include") {
+                const from = String(rel["from"] ?? ""), to = String(rel["to"] ?? "");
+                const list = includesByTarget.get(to) ?? [];
+                list.push(from);
+                includesByTarget.set(to, list);
+                includeSet.add(`${from}:${to}`);
+                totalIncludeExtend++;
+            }
+            if (rel["kind"] === "extend")
+                totalIncludeExtend++;
+            if (rel["kind"] === "actorAssoc") {
+                const ucId = String(rel["ucId"] ?? ""), actorId = String(rel["actorId"] ?? "");
+                const list = assocsByUc.get(ucId) ?? [];
+                list.push(actorId);
+                assocsByUc.set(ucId, list);
+            }
+        }
+        if (totalIncludeExtend > 2)
+            warn(`${pp}.relationships`, "too-many-include-extend", `${totalIncludeExtend} include+extend relationships found — more than 2 is almost always wrong`);
+        // Check «include» targets
+        for (const [targetId, bases] of includesByTarget) {
+            if (bases.length < 2) {
+                err(`${pp}.relationships[include→${targetId}]`, "single-incoming-include", `UC "${targetId}" has exactly one incoming «include» (from "${bases[0]}") — fold it into the parent instead`);
+            }
+            if (assocsByUc.has(targetId)) {
+                err(`${pp}.relationships[include→${targetId}]`, "include-target-has-assoc", `UC "${targetId}" is an «include» target but also has direct actor associations — it cannot be both`);
+            }
+        }
+        // Check UC elements
+        for (const el of elements) {
+            if (el["kind"] !== "useCase")
+                continue;
+            const id = String(el["id"] ?? "");
+            const name = String(el["name"] ?? "");
+            const ePath = `${pp}.elements[id=${id}]`;
+            // Send-only check
+            if (SEND_ONLY_PREFIXES.some(rx => rx.test(name))) {
+                err(ePath, "send-only-uc", `UC "${id}" name "${name}" appears to be send-only — fold the send step into the UC that decided to send`);
+            }
+            // Physical verb check
+            if (PHYSICAL_VERB_PREFIXES.some(rx => rx.test(name))) {
+                warn(ePath, "physical-verb", `UC "${id}" name "${name}" uses a physical verb — wrap with a system verb (רישום, הזנה, עדכון, סימון…)`);
+            }
+            // Primary actor
+            const primaryActor = el["primaryActor"];
+            if (!primaryActor) {
+                err(ePath, "missing-primary-actor", `UC "${id}" has no primaryActor`);
+            }
+            else {
+                if (!actorIds.has(primaryActor)) {
+                    err(ePath, "unknown-primary-actor", `UC "${id}" primaryActor "${primaryActor}" is not in actors list`);
+                }
+                // Check that an actorAssoc with role=initiator exists for this actor↔UC pair
+                const initiatorAssoc = relationships.find(r => r["kind"] === "actorAssoc" && r["ucId"] === id && r["actorId"] === primaryActor && r["role"] === "initiator");
+                if (!initiatorAssoc) {
+                    err(ePath, "primary-not-initiator", `UC "${id}" primaryActor "${primaryActor}" has no actorAssoc with role="initiator"`);
+                }
+            }
+            // Narrative fields — must contain Hebrew
+            for (const [key, val] of [["description", el["description"]]]) {
+                if (typeof val === "string" && val.length > 0 && !hasHebrew(val)) {
+                    err(`${ePath}.${key}`, "narrative-non-hebrew", `${key} contains no Hebrew characters`);
+                }
+            }
+            for (const [key, arr] of [["preconditions", el["preconditions"]], ["postconditions", el["postconditions"]]]) {
+                if (!Array.isArray(arr) || arr.length === 0) {
+                    warn(`${ePath}.${key}`, `missing-${key}`, `UC "${id}" has no ${key}`);
+                }
+                else {
+                    arr.forEach((item, i) => {
+                        if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                            err(`${ePath}.${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                        }
+                    });
+                }
+            }
+            // User stories
+            const userStories = Array.isArray(el["userStories"]) ? el["userStories"] : [];
+            if (userStories.length < 2) {
+                warn(`${ePath}.userStories`, "few-user-stories", `UC "${id}" has ${userStories.length} user stor${userStories.length === 1 ? "y" : "ies"} — cover every distinct stakeholder goal`);
+            }
+            // Scenarios / flow steps
+            const scenarios = Array.isArray(el["scenarios"]) ? el["scenarios"] : [];
+            if (scenarios.length === 0) {
+                err(`${ePath}.scenarios`, "missing-scenarios", `UC "${id}" has no scenarios`);
+            }
+            for (const [si, sce] of scenarios.entries()) {
+                const sPath = `${ePath}.scenarios[${si}]`;
+                const flow = Array.isArray(sce["flow"]) ? sce["flow"] : [];
+                if (flow.length === 0) {
+                    err(`${sPath}.flow`, "empty-flow", `scenario "${sce["id"]}" in UC "${id}" has no flow steps`);
+                }
+                const flowLen = flow.length;
+                for (const [fi, step] of flow.entries()) {
+                    const stepPath = `${sPath}.flow[${fi}]`;
+                    if (step["kind"] === "actor" && typeof step["actor"] === "string" && !actorIds.has(step["actor"])) {
+                        err(stepPath, "unknown-actor-ref", `flow step references unknown actor id "${step["actor"]}"`);
+                    }
+                    if (step["kind"] === "include") {
+                        const targetUc = String(step["uc"] ?? "");
+                        if (!ucIds.has(targetUc)) {
+                            err(stepPath, "unknown-uc-ref", `«include» step references unknown UC id "${targetUc}"`);
+                        }
+                        else if (!includeSet.has(`${id}:${targetUc}`)) {
+                            err(stepPath, "include-step-no-relationship", `«include» step references "${targetUc}" but no include relationship exists from "${id}" to "${targetUc}"`);
+                        }
+                    }
+                    if (typeof step["text"] === "string" && step["text"].length > 0 && !hasHebrew(step["text"])) {
+                        err(stepPath, "narrative-non-hebrew", "flow step text contains no Hebrew characters");
+                    }
+                }
+                const extensions = Array.isArray(sce["extensions"]) ? sce["extensions"] : [];
+                for (const [ei, ext] of extensions.entries()) {
+                    const extPath = `${sPath}.extensions[${ei}]`;
+                    if (typeof ext["at"] === "number" && (ext["at"] < 1 || ext["at"] > flowLen)) {
+                        err(extPath, "invalid-extension-at", `extension "at" value ${ext["at"]} is out of range (flow has ${flowLen} steps)`);
+                    }
+                    if (typeof ext["text"] === "string" && ext["text"].length > 0 && !hasHebrew(ext["text"])) {
+                        err(extPath, "narrative-non-hebrew", "extension text contains no Hebrew characters");
+                    }
+                }
+            }
+            // Wireframe safety (only when present and non-empty)
+            if (typeof el["wireframe"] === "string" && el["wireframe"].length > 0) {
+                if (!wireframeSafe(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "unsafe-wireframe", `wireframe for UC "${id}" contains forbidden patterns (script/on*/iframe/external URL/@import/style)`);
+                }
+                if (!hasHebrew(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "wireframe-non-hebrew", `wireframe for UC "${id}" contains no Hebrew characters`);
+                }
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, issues: errors, warnings };
+    return { ok: true, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {

package/skills/uml-use-case-diagram/SKILL.md

@@ -272,8 +272,14 @@ const diagramLayout = {
 
 ### fixLayout implementation
 
+`fixLayout`, its constants, and all other runtime functions are provided by
+`https://themathbible.com/sad-mcp/uc-diagram-common.js` — **do not inline them**.
+The HTML `<script>` block must contain only the diagram-specific data objects
+(`diagramLayouts`, `actorDescriptions`, `assocDescriptions`, `useCaseDocs`, `diagramModel`).
+
+The function signature and constants for reference (implementation is external):
+
 ```javascript
-// Named constants — tune these, do not hardcode magic numbers elsewhere.
 const HEADER_H  = 44;   // boundary header height
 const UC_PAD    = 30;   // min gap from boundary edge to nearest UC edge
 const UC_GAP    = 14;   // min gap between UC ellipses in the same column
@@ -439,13 +445,6 @@ function fixLayout(layout) {
 </div>
 ```
 
-```css
-.fix-btn { padding: 8px 20px; border: 1px solid #3b82f6; background: #eff6ff;
-  color: #1e40af; font-size: 12px; font-weight: 600; cursor: pointer;
-  border-radius: 6px; font-family: 'Noto Sans Hebrew', sans-serif; }
-.fix-btn:hover { background: #dbeafe; }
-```
-
 ---
 
 ## 7. Splitting Into Multiple Diagrams
@@ -495,7 +494,11 @@ function showDesc(id, type, event) {
 }
 ```
 
-### 8b. Small popup for actors and associations
+All popup and modal functions (`showDesc`, `showPopup`, `hideDesc`, `openUcModal`,
+`closeUcModal`, `pulseActor`, `wireframeSafe`) are provided by
+`uc-diagram-common.js` — **do not inline them**.
+
+### 8b. Data objects for popups (inline in the HTML `<script>` block)
 
 ```javascript
 const actorDescriptions = {
@@ -503,48 +506,16 @@ const actorDescriptions = {
   // ... one entry per actor
 };
 const assocDescriptions = {
-  // keyed by connection id; name = actor-name ↔ UC-name (auto-composed is fine)
+  // keyed by connection id; name = actor-name ↔ UC-name
   'a1': { name: 'לקוח ↔ פתיחת הזמנה', desc: 'הלקוח יוזם את פתיחת ההזמנה. תפקיד: Initiator.' },
   // ... one entry per association line you want described
 };
-
-function showPopup(id, type, event) {
-  hideDesc();
-  const data = type === 'actor' ? actorDescriptions[id]
-             : type === 'assoc' ? assocDescriptions[id]
-             : null;
-  if (!data) return;
-  const panel = document.createElement('div');
-  panel.id = 'desc-panel';
-  panel.innerHTML = `
-    <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:6px;">
-      <strong style="font-size:12px;color:#1e40af;direction:rtl;">${data.name}</strong>
-      <span onclick="hideDesc()" style="cursor:pointer;color:#94a3b8;font-size:18px;line-height:1;margin-right:6px;">×</span>
-    </div>
-    <div style="font-size:11px;color:#334155;line-height:1.6;direction:rtl;">${data.desc}</div>`;
-  Object.assign(panel.style, {
-    position:'fixed', background:'#fff', border:'1.5px solid #2980b9',
-    borderRadius:'8px', padding:'12px 16px', maxWidth:'300px',
-    boxShadow:'0 4px 14px rgba(0,0,0,.15)', zIndex:'1000',
-    left: event.clientX + 'px', top: event.clientY + 'px'
-  });
-  document.body.appendChild(panel);
-  const r = panel.getBoundingClientRect();
-  if (r.right  > window.innerWidth)  panel.style.left = (window.innerWidth  - r.width  - 10) + 'px';
-  if (r.bottom > window.innerHeight) panel.style.top  = (event.clientY - r.height - 10) + 'px';
-  event.stopPropagation();
-}
-function hideDesc() { document.getElementById('desc-panel')?.remove(); }
-document.addEventListener('click', e => {
-  if (!e.target.closest('[data-uc-id]') &&
-      !e.target.closest('[data-actor-id]') &&
-      !e.target.closest('[data-conn-id]')) hideDesc();
-});
 ```
 
-### 8a. Full-screen modal for UCs
+### 8a. useCaseDocs data object (inline in the HTML `<script>` block)
 
-Every UC ellipse's click routes to `openUcModal(id)`, which reads `useCaseDocs[id]` (populated from the §4.4 documentation blocks) and renders a full-screen modal with the complete UC spec. The modal has sections for: header (id + name + primary actor link), description, scenarios (numbered flow with typed steps + extensions), a row with preconditions / postconditions / user stories, and an optional wireframe.
+`openUcModal(id)` reads `useCaseDocs[id]` and renders a full-screen modal with
+the complete UC spec. Populate one entry per UC:
 
 ```javascript
 const useCaseDocs = {
@@ -559,10 +530,10 @@ const useCaseDocs = {
     scenarios: [
       { id: 'sc-happy', name: 'מסלול מרכזי',
         flow: [
-          { kind: 'actor',   actor: 'customer',      text: 'בוחר פריט מהקטלוג' },
-          { kind: 'system',                          text: 'מוסיף את הפריט לעגלה' },
-          { kind: 'include', uc:    'uc-authenticate', text: '' },
-          { kind: 'actor',   actor: 'customer',      text: 'מאשר את ההזמנה' }
+          { kind: 'actor',   actor: 'customer',        text: 'בוחר פריט מהקטלוג' },
+          { kind: 'system',                            text: 'מוסיף את הפריט לעגלה' },
+          { kind: 'include', uc: 'uc-authenticate',    text: '' },
+          { kind: 'actor',   actor: 'customer',        text: 'מאשר את ההזמנה' }
         ],
         extensions: [
           { at: 1, text: 'אם הפריט אזל במלאי — מציג הודעה וחוזר לשלב 1.' }
@@ -576,130 +547,6 @@ const useCaseDocs = {
   }
   // ... one entry per UC
 };
-
-function openUcModal(id) {
-  const doc = useCaseDocs[id];
-  if (!doc) return;
-  const actorName = aid => (actorDescriptions[aid]?.name) || aid;
-  const ucName    = uid => (useCaseDocs[uid]?.name) || uid;
-  const modal = document.getElementById('uc-modal');
-  modal.querySelector('.uc-id').textContent       = doc.id;
-  modal.querySelector('.uc-name').textContent     = doc.name;
-  const paLink = modal.querySelector('.uc-primary-link');
-  paLink.textContent  = actorName(doc.primaryActor);
-  paLink.dataset.actorId = doc.primaryActor;
-  paLink.onclick = () => { closeUcModal(); pulseActor(doc.primaryActor); };
-
-  modal.querySelector('.uc-description').textContent = doc.description || '';
-
-  // Scenarios
-  const sc = modal.querySelector('.uc-scenarios');
-  sc.innerHTML = '';
-  (doc.scenarios || []).forEach(sce => {
-    const h = document.createElement('h3'); h.textContent = sce.name || sce.id; sc.appendChild(h);
-    const ol = document.createElement('ol');
-    (sce.flow || []).forEach((step, i) => {
-      const li = document.createElement('li');
-      if (step.kind === 'actor') {
-        const strong = document.createElement('strong');
-        strong.className = 'step-actor';
-        strong.dataset.actorId = step.actor;
-        strong.textContent = actorName(step.actor);
-        strong.onclick = () => { closeUcModal(); pulseActor(step.actor); };
-        li.appendChild(strong);
-        li.appendChild(document.createTextNode(': ' + (step.text || '')));
-      } else if (step.kind === 'system') {
-        const em = document.createElement('em');
-        em.className = 'step-system'; em.textContent = 'המערכת';
-        li.appendChild(em);
-        li.appendChild(document.createTextNode(': ' + (step.text || '')));
-      } else if (step.kind === 'include') {
-        const span = document.createElement('span');
-        span.className = 'step-include'; span.textContent = '«include» ';
-        const a = document.createElement('a');
-        a.className = 'step-uc-ref'; a.textContent = ucName(step.uc);
-        a.onclick = () => openUcModal(step.uc);
-        li.appendChild(span); li.appendChild(a);
-        if (step.text) li.appendChild(document.createTextNode(' — ' + step.text));
-      } else if (step.kind === 'extension') {
-        li.className = 'ext-inline';
-        li.textContent = (step.at ? step.at + 'a. ' : '') + (step.text || '');
-      }
-      ol.appendChild(li);
-      // Inline extensions defined in sce.extensions anchored to this step number:
-      (sce.extensions || []).filter(e => e.at === i + 1).forEach((ext, j) => {
-        const sub = document.createElement('li');
-        sub.className = 'ext-sub';
-        const letter = String.fromCharCode(97 + j);  // a, b, c, ...
-        sub.textContent = (i + 1) + letter + '. ' + ext.text;
-        ol.appendChild(sub);
-      });
-    });
-    sc.appendChild(ol);
-  });
-
-  const fillList = (selector, items) => {
-    const el = modal.querySelector(selector);
-    el.innerHTML = '';
-    (items || []).forEach(s => { const li = document.createElement('li'); li.textContent = s; el.appendChild(li); });
-  };
-  fillList('.uc-pre ul',    doc.preconditions);
-  fillList('.uc-post ul',   doc.postconditions);
-  const usList = modal.querySelector('.uc-stories ul');
-  usList.innerHTML = '';
-  (doc.userStories || []).forEach(us => {
-    const li = document.createElement('li');
-    li.textContent = `As a ${us.role}, I want ${us.want}, so that ${us.so}`;
-    usList.appendChild(li);
-  });
-
-  // Wireframe — safety-checked before insertion
-  const wf = modal.querySelector('.uc-wireframe');
-  wf.innerHTML = '';
-  if (doc.wireframe && wireframeSafe(doc.wireframe)) {
-    wf.innerHTML = doc.wireframe;
-    wf.hidden = false;
-  } else {
-    wf.hidden = true;
-    if (doc.wireframe) console.warn(`Wireframe for ${id} failed safety check.`);
-  }
-
-  modal.hidden = false;
-  document.body.classList.add('uc-modal-open');
-}
-
-function closeUcModal() {
-  const modal = document.getElementById('uc-modal');
-  modal.hidden = true;
-  document.body.classList.remove('uc-modal-open');
-}
-
-// Esc closes the modal.
-document.addEventListener('keydown', e => {
-  if (e.key === 'Escape') closeUcModal();
-});
-
-// Highlight an actor on the diagram for ~2s.
-function pulseActor(actorId) {
-  const g = document.getElementById('actor-group-' + actorId);
-  if (!g) return;
-  g.classList.add('actor-pulse');
-  setTimeout(() => g.classList.remove('actor-pulse'), 2000);
-}
-
-// Wireframe sanity check — see §WF. Rejects scripts, event handlers, external URLs.
-function wireframeSafe(html) {
-  const forbidden = [
-    /<script\b/i,
-    /\son\w+\s*=/i,
-    /<iframe\b/i,
-    /src\s*=\s*["']https?:/i,
-    /href\s*=\s*["']https?:/i,
-    /@import\b/i,
-    /<style\b/i
-  ];
-  return !forbidden.some(rx => rx.test(html));
-}
 ```
 
 UC group: `<g id="uc-uc1" data-uc-id="uc1" onclick="showDesc('uc1','uc',event)" style="cursor:pointer">`
@@ -742,46 +589,10 @@ Associations without a meaningful description (e.g., auto-generated from trivial
 
 ### Timing labels on cron/time-actor associations (required)
 
-When a connection carries a `timing` field (every connection from a system-time actor MUST have one — see §2), inject the label at the line midpoint **after** `fixLayout` has written the endpoints. The helper below is idempotent: it removes any existing `.timing-label` group before re-rendering, so calling it again after another `fixLayout` pass is safe.
-
-```javascript
-function renderTimingLabels(layout) {
-  const svg = document.getElementById(layout.svgId);
-  if (!svg) return;
-  svg.querySelectorAll('.timing-label').forEach(el => el.remove());
-  const NS = 'http://www.w3.org/2000/svg';
-  (layout.connections || []).forEach(conn => {
-    if (!conn.timing) return;
-    const line = svg.querySelector(
-      `[data-conn-from="${conn.from}"][data-conn-to="${conn.to}"]`);
-    if (!line) return;
-    const x1 = +line.getAttribute('x1'), y1 = +line.getAttribute('y1');
-    const x2 = +line.getAttribute('x2'), y2 = +line.getAttribute('y2');
-    const mx = (x1 + x2) / 2, my = (y1 + y2) / 2;
-    const w = 10 + conn.timing.length * 7, h = 16;
-    const g = document.createElementNS(NS, 'g');
-    g.setAttribute('class', 'timing-label');
-    const rect = document.createElementNS(NS, 'rect');
-    rect.setAttribute('x', mx - w / 2); rect.setAttribute('y', my - h / 2);
-    rect.setAttribute('width', w);      rect.setAttribute('height', h);
-    rect.setAttribute('fill', 'white'); rect.setAttribute('stroke', '#334155');
-    rect.setAttribute('stroke-width', '0.8'); rect.setAttribute('rx', '3');
-    const text = document.createElementNS(NS, 'text');
-    text.setAttribute('x', mx); text.setAttribute('y', my + 4);
-    text.setAttribute('font-size', '10'); text.setAttribute('text-anchor', 'middle');
-    text.setAttribute('fill', '#334155');
-    text.setAttribute('font-family', "'Noto Sans Hebrew', sans-serif");
-    text.setAttribute('direction', 'rtl');
-    text.textContent = conn.timing;
-    g.appendChild(rect); g.appendChild(text);
-    svg.appendChild(g);
-  });
-}
-```
-
-Call `renderTimingLabels(layout)` at the end of every `fixLayout` invocation, **and** on `DOMContentLoaded` (after the initial `fixLayout`). Add it inside `showDiagram(index)` too so the label tracks the active tab.
+`renderTimingLabels(layout)` is provided by `uc-diagram-common.js` — do not inline it.
+It is called automatically at the end of every `fixLayout` invocation.
 
-The `connections` entry for a timed link looks like:
+Every connection from a system-time actor MUST carry a `timing` field:
 
 ```javascript
 { from: 'cron', to: 'uc-daily-reconcile', type: 'association', timing: 'פעם ביום' }
@@ -789,9 +600,15 @@ The `connections` entry for a timed link looks like:
 
 ---
 
-## §WF. Wireframe Authoring (Per-UC, Optional)
+## §WF. Wireframe Authoring (Opt-In)
 
-Where a UC benefits from a visual mock of the UI the user sees, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
+**Wireframes are generated only when the user explicitly requests them** (e.g., "add wireframes", "include UI mocks"). Do not generate wireframes unless asked — they significantly increase generation time.
+
+When wireframes are requested, generate them only for UCs whose `primaryActor.actorType === 'human'`. Skip wireframes for:
+- UCs whose primary actor is a system or cron (`actorType: 'system'`) — no human sees a screen.
+- Pure include-target UCs (sub-behaviors with no actor association).
+
+When generated, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
 
 Claude authors the wireframe using its own UI-generation judgment — there is no DSL. But the skill enforces a consistent look and safe sandbox via a scoped CSS theme and a set of forbidden patterns.
 
@@ -860,9 +677,10 @@ The `wireframeSafe()` regex rejects any of the following. A failing wireframe re
 
 ### When NOT to include a wireframe
 
-- The UC has no user-facing screen (e.g., a back-end cron job, an automated reconciliation).
-- The UI is trivial (e.g., a single "Approve" confirmation prompt) — prose in the scenario flow is enough.
-- You cannot author the wireframe without making up details the spec does not support — put those in `diagramModel.openQuestions` instead.
+- Primary actor is a system / cron (`actorType: 'system'`) — e.g., a back-end reconciliation triggered by the clock.
+- The UC is purely an `«include»` target (a sub-behavior, not a user-visible goal).
+
+**"The UI is trivial" is not a valid reason to skip.** A single approval prompt still deserves a mock — it shows the reader what the button says, what data is visible on the screen, and what confirmation text appears. If you genuinely cannot author the wireframe because the spec is silent, record the gap in `diagramModel.openQuestions` AND still emit a placeholder wireframe with the questions visible inside it.
 
 ---
 
@@ -908,107 +726,9 @@ Assumptions li:     #334155, 12px, line-height 1.6, list-style disc inside
 Fonts:              'Noto Sans Hebrew' + 'IBM Plex Mono' from Google Fonts
 ```
 
-The assumptions panel CSS must be included in the HTML `<style>` block:
-
-```css
-.assumptions-panel { display: flex; gap: 24px; max-width: 1000px;
-  margin: 20px auto; padding: 16px 20px; background: #fff;
-  border: 1px solid #cbd5e1; border-radius: 8px; direction: rtl; }
-.assumptions-col { flex: 1; min-width: 0; }
-.assumptions-col h3 { margin: 0 0 6px; font-size: 13px; font-weight: 600;
-  color: #1e40af; }
-.assumptions-col ul { margin: 0; padding-right: 18px; }
-.assumptions-col li { color: #334155; font-size: 12px; line-height: 1.6; }
-```
-
-### v2 — UC modal styling
-
-```css
-/* Lock body scroll while the modal is open */
-body.uc-modal-open { overflow: hidden; }
-
-.uc-modal { position: fixed; inset: 0; z-index: 2000; display: flex;
-  align-items: flex-start; justify-content: center; padding: 40px 20px;
-  overflow-y: auto; direction: rtl;
-  font-family: 'Noto Sans Hebrew', sans-serif; }
-.uc-modal-backdrop { position: absolute; inset: 0; background: rgba(15, 23, 42, 0.55); }
-.uc-modal-body { position: relative; z-index: 1; width: 100%; max-width: 960px;
-  background: #fff; border-radius: 12px; box-shadow: 0 10px 40px rgba(0,0,0,.25);
-  padding: 28px 32px 32px; color: #1e293b; }
-.uc-modal-close { position: absolute; top: 10px; left: 14px; background: none;
-  border: none; font-size: 24px; color: #64748b; cursor: pointer; }
-.uc-modal-body header { border-bottom: 1px solid #e2e8f0; padding-bottom: 12px;
-  margin-bottom: 18px; }
-.uc-modal-body .uc-id { display: inline-block; font-family: 'IBM Plex Mono',monospace;
-  font-size: 11px; color: #64748b; background: #f1f5f9; padding: 2px 8px;
-  border-radius: 4px; margin-bottom: 6px; }
-.uc-modal-body .uc-name { margin: 0 0 4px; font-size: 20px; color: #1e40af; font-weight: 700; }
-.uc-modal-body .uc-primary { font-size: 13px; color: #334155; }
-.uc-modal-body .uc-primary-label { color: #64748b; margin-left: 6px; }
-.uc-modal-body .uc-primary-link { color: #1e40af; cursor: pointer; font-weight: 600;
-  text-decoration: underline dotted; }
-.uc-description { margin-bottom: 20px; font-size: 14px; line-height: 1.7; color: #334155; }
-
-.uc-scenarios h3 { font-size: 14px; color: #1e40af; margin: 18px 0 6px;
-  border-right: 3px solid #3b82f6; padding-right: 10px; }
-.uc-scenarios ol { margin: 0 0 14px; padding-right: 22px; }
-.uc-scenarios ol li { color: #1e293b; font-size: 13px; line-height: 1.9; }
-.step-actor { color: #1e40af; font-weight: 600; cursor: pointer; text-decoration: underline dotted; }
-.step-system { color: #475569; font-style: italic; }
-.step-include { color: #7c3aed; font-family: 'IBM Plex Mono', monospace; font-size: 11px; }
-.step-uc-ref { color: #7c3aed; cursor: pointer; text-decoration: underline; }
-.ext-inline, .ext-sub { list-style: none; color: #64748b; font-size: 12px;
-  padding-right: 24px; line-height: 1.7; }
-
-.uc-prepostuser { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 18px;
-  margin: 18px 0 20px; }
-.uc-prepostuser > div { background: #f8fafc; border: 1px solid #e2e8f0;
-  border-radius: 8px; padding: 12px 14px; }
-.uc-prepostuser h4 { margin: 0 0 6px; font-size: 12px; color: #1e40af; font-weight: 600; }
-.uc-prepostuser ul { margin: 0; padding-right: 18px; font-size: 12px;
-  color: #334155; line-height: 1.7; }
-
-.uc-wireframe { border-top: 1px dashed #cbd5e1; padding-top: 16px; margin-top: 6px; }
-.uc-wireframe:empty, .uc-wireframe[hidden] { display: none; }
-
-/* Actor pulse animation used by pulseActor() */
-.actor-pulse { animation: actor-pulse 0.6s ease-in-out 3; }
-@keyframes actor-pulse {
-  0%, 100% { filter: none; }
-  50%      { filter: drop-shadow(0 0 8px #3b82f6); }
-}
-```
+All styles are in `https://themathbible.com/sad-mcp/uc-diagram-common.css` — **do not add a `<style>` block**. Do not inline any CSS.
 
-### v2 — Wireframe scoped theme
-
-```css
-.wf-screen { background: #f8fafc; border: 1px solid #cbd5e1; border-radius: 8px;
-  padding: 18px 20px; font-family: 'Noto Sans Hebrew', sans-serif;
-  color: #1e293b; direction: rtl; max-width: 760px; margin: 0 auto; }
-.wf-heading { margin: 0 0 14px; font-size: 15px; color: #1e40af; font-weight: 700;
-  border-bottom: 1px solid #e2e8f0; padding-bottom: 6px; }
-.wf-section { margin: 14px 0; }
-.wf-row { display: flex; gap: 10px; align-items: center; margin: 6px 0; }
-.wf-label { font-size: 12px; color: #475569; min-width: 120px; }
-.wf-input, .wf-textarea, .wf-select { flex: 1; background: #fff;
-  border: 1px solid #cbd5e1; border-radius: 4px; padding: 6px 8px;
-  font-size: 12px; color: #334155; }
-.wf-textarea { min-height: 60px; }
-.wf-table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 12px; }
-.wf-table th, .wf-table td { border: 1px solid #cbd5e1; padding: 6px 8px;
-  text-align: right; }
-.wf-table th { background: #e2e8f0; color: #1e40af; font-weight: 600; }
-.wf-actions { display: flex; gap: 8px; margin-top: 12px; justify-content: flex-start; }
-.wf-button { background: #fff; border: 1px solid #64748b; border-radius: 4px;
-  padding: 6px 14px; font-size: 12px; color: #334155; cursor: default; }
-.wf-primary { background: #1e40af; color: #fff; border-color: #1e40af; }
-.wf-image-box { border: 1px dashed #94a3b8; background: #f1f5f9; color: #64748b;
-  text-align: center; padding: 24px; border-radius: 4px; font-size: 12px;
-  margin: 10px 0; }
-.wf-hint { font-size: 11px; color: #64748b; font-style: italic; margin: 6px 0; }
-.wf-badge { display: inline-block; background: #e0f2fe; color: #0369a1;
-  padding: 2px 8px; border-radius: 999px; font-size: 10px; font-weight: 600; }
-```
+Available wireframe classes (for §WF): `wf-screen`, `wf-heading`, `wf-row`, `wf-label`, `wf-input`, `wf-textarea`, `wf-select`, `wf-button`, `wf-primary`, `wf-actions`, `wf-table`, `wf-image-box`, `wf-hint`, `wf-section`, `wf-badge`.
 
 ---
 
@@ -1021,7 +741,7 @@ body.uc-modal-open { overflow: hidden; }
   <meta charset="UTF-8">
   <title>[System] — Use Case Diagram</title>
   <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@400;600&family=IBM+Plex+Mono:wght@400;700&display=swap" rel="stylesheet">
-  <style>/* tab bar, fix-btn, body layout */</style>
+  <link href="https://themathbible.com/sad-mcp/uc-diagram-common.css" rel="stylesheet">
 </head>
 <body>
   <!-- Tab bar (only when split) -->
@@ -1033,7 +753,7 @@ body.uc-modal-open { overflow: hidden; }
   <!-- Split rationale (only when split) -->
   <div class="split-rationale">Split by UC count: N UCs &gt; 8 threshold</div>
 
-  <!-- Fix Layout button (above each diagram) -->
+  <!-- Fix Layout button -->
   <div style="text-align:center;margin:8px 0;">
     <button onclick="fixLayout(currentLayout())" class="fix-btn">Fix Layout</button>
   </div>
@@ -1049,99 +769,34 @@ body.uc-modal-open { overflow: hidden; }
     <svg id="diagram-svg-1" viewBox="0 0 1100 900" xmlns="http://www.w3.org/2000/svg">...</svg>
   </div>
 
-  <!-- Assumptions / open-questions panel (render only if at least one non-empty) -->
+  <!-- Assumptions / open-questions panel -->
   <div id="assumptions-panel" class="assumptions-panel" hidden>
     <div class="assumptions-col" id="assumptions-col">
-      <h3>הנחות</h3>
-      <ul id="assumptions-list"></ul>
+      <h3>הנחות</h3><ul id="assumptions-list"></ul>
     </div>
     <div class="assumptions-col" id="open-questions-col">
-      <h3>שאלות פתוחות</h3>
-      <ul id="open-questions-list"></ul>
+      <h3>שאלות פתוחות</h3><ul id="open-questions-list"></ul>
     </div>
   </div>
 
-  <!-- v2 — UC modal (populated by openUcModal; hidden by default) -->
+  <!-- UC modal (body is populated by openUcModal in common.js; starts empty) -->
   <div id="uc-modal" class="uc-modal" hidden role="dialog" aria-modal="true">
     <div class="uc-modal-backdrop" onclick="closeUcModal()"></div>
-    <div class="uc-modal-body">
-      <button class="uc-modal-close" onclick="closeUcModal()" aria-label="Close">×</button>
-      <header>
-        <span class="uc-id"></span>
-        <h2 class="uc-name"></h2>
-        <div class="uc-primary">
-          <span class="uc-primary-label">שחקן ראשי:</span>
-          <a class="uc-primary-link"></a>
-        </div>
-      </header>
-      <section class="uc-description"></section>
-      <section class="uc-scenarios"></section>
-      <section class="uc-prepostuser">
-        <div class="uc-pre"><h4>תנאים מוקדמים</h4><ul></ul></div>
-        <div class="uc-post"><h4>תנאים סופיים</h4><ul></ul></div>
-        <div class="uc-stories"><h4>סיפורי משתמש</h4><ul></ul></div>
-      </section>
-      <section class="uc-wireframe" hidden></section>
-    </div>
+    <div class="uc-modal-body"></div>
   </div>
 
   <!-- VP export button -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
+  <!-- DIAGRAM DATA ONLY — all functions are in uc-diagram-common.js -->
   <script>
-    const diagramLayouts = [ /* one layout object per tab, per §6 */ ];
-    const actorDescriptions   = { /* §8b */ };
-    const assocDescriptions   = { /* §8b */ };
-    const useCaseDocs         = { /* §8a — full v2 per-UC documentation */ };
+    const diagramLayouts      = [ /* one layout object per tab, per §6 */ ];
+    const actorDescriptions   = { /* §8b — one entry per actor */ };
+    const assocDescriptions   = { /* §8b — one entry per association line */ };
+    const useCaseDocs         = { /* §8a — full per-UC documentation */ };
     const diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
-
-    let activeTab = 0;
-    function currentLayout() { return diagramLayouts[activeTab]; }
-    function showDiagram(index) {
-      activeTab = index;
-      document.querySelectorAll('.diagram-part').forEach((p, i) => p.hidden = i !== index);
-      document.querySelectorAll('.tab').forEach((t, i) => t.classList.toggle('active', i === index));
-      fixLayout(diagramLayouts[index]);  // idempotent
-    }
-
-    function fixLayout(layout)        { /* §6 */ }
-    function showDesc(id, type, event){ /* §8: routes to openUcModal for UCs, showPopup otherwise */ }
-    function showPopup(id, type, event){ /* §8b */ }
-    function hideDesc()               { /* §8b */ }
-    function openUcModal(id)          { /* §8a */ }
-    function closeUcModal()           { /* §8a */ }
-    function pulseActor(actorId)      { /* §8a */ }
-    function wireframeSafe(html)      { /* §8a / §WF */ }
-    function xmiBody(elements, rels)  { /* export-buttons.md — v2 emits preconditions/postconditions/ownedBehavior */ }
-    function exportXMI()              { /* export-buttons.md */ }
-
-    function renderAssumptions() {
-      const a = (diagramModel && diagramModel.assumptions)   || [];
-      const q = (diagramModel && diagramModel.openQuestions) || [];
-      const panel = document.getElementById('assumptions-panel');
-      if (!panel) return;
-      if (!a.length && !q.length) { panel.hidden = true; return; }
-      panel.hidden = false;
-      const ul = id => document.getElementById(id);
-      const fill = (listEl, items) => {
-        listEl.innerHTML = '';
-        items.forEach(s => {
-          const li = document.createElement('li');
-          li.textContent = s;
-          listEl.appendChild(li);
-        });
-      };
-      fill(ul('assumptions-list'),    a);
-      fill(ul('open-questions-list'), q);
-      document.getElementById('assumptions-col').hidden    = !a.length;
-      document.getElementById('open-questions-col').hidden = !q.length;
-    }
-
-    document.addEventListener('DOMContentLoaded', () => {
-      diagramLayouts.forEach(l => fixLayout(l));
-      renderAssumptions();
-    });
   </script>
+  <script src="https://themathbible.com/sad-mcp/uc-diagram-common.js"></script>
 </body>
 </html>
 ```
@@ -1170,7 +825,7 @@ The validator runs locally (no API cost) and catches what the §4 and CR gates c
 - Extensions referencing invalid step numbers → ERROR
 - Narrative text missing Hebrew characters (description, preconditions, postconditions, flow/extension text, user stories, assumptions, openQuestions) → ERROR
 - Unsafe wireframe HTML (script / on*= / iframe / external URL / @import / inline style) → ERROR
-- Warnings: fewer than 2 user stories on a UC, no preconditions/postconditions, overall >2 include+extend relationships
+- Warnings: fewer than 2 user stories on a UC, no preconditions/postconditions, overall >2 include+extend relationships, wireframe present on a UC when none were requested
 
 If the response is `✗ Model invalid`, fix every listed error and call the validator again. **Do not write the HTML file until the validator returns `✓ Model valid`.**
 
@@ -1188,7 +843,8 @@ Briefly report: actor count, use case count, include/extend count, whether split
 - [ ] Every `primaryActor` id exists in `actors[]` AND has an association with `role: 'initiator'` on that UC (aligning §4.1 with §4.4).
 - [ ] Every flow step of `kind: 'actor'` references a real actor id; every `kind: 'include'` references a real UC id; every `extension.at` references a valid step number in its scenario's flow.
 - [ ] Clicking a UC on the diagram opens the full-screen modal (§8a); Esc / backdrop click closes it. Step actor/UC references are clickable. Actor popup + association popup (§8b) still work for non-UC clicks.
-- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only.
+- [ ] Wireframes generated only if the user explicitly requested them (§WF). If generated, only for human-initiated UCs; system/cron and include-targets omitted.
+- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only; visible text is in Hebrew.
 - [ ] Every actor-UC association has a written §4.1 justification block (role, initiates? one-line "why"); every UC has ≥1 association with `initiates = yes`.
 - [ ] Every association line carries a transparent click-hitbox (stroke-width ≥12, `data-conn-id`) wired to `showDesc(id,'assoc',event)`; `assocDescriptions` entry exists for each id.
 - [ ] `assumptions` and `openQuestions` arrays are present in `diagramModel`; the HTML renders the bottom panel whenever either is non-empty.

package/dist/usecase/validate.d.ts

@@ -1,17 +0,0 @@
-export interface ValidationIssue {
-    severity: "error" | "warning";
-    code: string;
-    path: string;
-    message: string;
-}
-export type ValidateResult = {
-    ok: true;
-    warnings: ValidationIssue[];
-} | {
-    ok: false;
-    issues: ValidationIssue[];
-    warnings: ValidationIssue[];
-};
-export declare function validateModel(model: unknown): ValidateResult;
-export declare function parseAndValidate(jsonText: string): ValidateResult;
-export declare function formatIssues(issues: ValidationIssue[]): string;

package/dist/usecase/validate.js

@@ -1,384 +0,0 @@
-// Structural validator for UML use-case diagramModel JSON.
-//
-// Purpose: catch the business-rule violations the SKILL prompts for but cannot
-// enforce on its own — overeager «include», send-only UCs, physical-verb
-// labels, missing primary actor, broken references in scenario flows, etc.
-//
-// Returns ALL issues at once so the calling LLM can self-correct in a single
-// pass rather than iterating error-by-error.
-// ── Name heuristics (CR #8 and CR #10) ──────────────────────────────────
-// Send-only / output-only verbs that on their own do not constitute a UC.
-// Pattern allows "Record sending" etc. — only bare send-verbs flag.
-const SEND_ONLY_PATTERNS = [
-    /^(send|notify|email|sms|alert|push|broadcast)\b/i,
-    /^(print)\s+\w+\s+(label|receipt|ticket|slip)\b/i,
-    /^שליחת\s/,
-    /^הודעה\s/,
-    /^התראה\s/,
-    /^הפצת\s/,
-];
-// Physical verbs that describe actions outside the IS. Allowed only when
-// wrapped by a system verb (רישום / הזנה / עדכון / סימון / Record / Enter / ...).
-const PHYSICAL_VERBS = [
-    /^(perform|do|execute|conduct)\b/i,
-    /^(pick|pack|ship|deliver|receive|count|pay|collect)\b/i,
-    /^(ביצוע|הכנת|קבלת|מסירת|ספירת|תשלום|איסוף)\s/,
-];
-const SYSTEM_VERB_WRAPPERS = [
-    /^(record|register|enter|log|capture|mark|update|create|save)\b/i,
-    /^(רישום|הזנת|עדכון|סימון|יצירת|שמירת|קליטת|תיעוד)\s/,
-];
-function looksSendOnly(name) {
-    return SEND_ONLY_PATTERNS.some((rx) => rx.test(name.trim()));
-}
-function looksPhysical(name) {
-    const n = name.trim();
-    if (SYSTEM_VERB_WRAPPERS.some((rx) => rx.test(n)))
-        return false;
-    return PHYSICAL_VERBS.some((rx) => rx.test(n));
-}
-// CR #11 — narrative UC docs must be in Hebrew. We accept "contains at least
-// one Hebrew character" as a cheap heuristic; trivial strings (empty, whitespace,
-// pure punctuation) are treated as missing-content rather than English.
-const HEBREW_RANGE = /[\u0590-\u05FF]/;
-function hasHebrew(text) {
-    return typeof text === "string" && HEBREW_RANGE.test(text);
-}
-function isMeaningful(text) {
-    return typeof text === "string" && text.trim().length >= 2;
-}
-function asArray(v) {
-    return Array.isArray(v) ? v : [];
-}
-function getParts(model) {
-    if (!model || typeof model !== "object")
-        return [];
-    const parts = asArray(model.parts);
-    return parts.map((p) => {
-        const obj = (p && typeof p === "object") ? p : {};
-        return {
-            elements: asArray(obj.elements),
-            relationships: asArray(obj.relationships),
-        };
-    });
-}
-// ── Main validator ──────────────────────────────────────────────────────
-export function validateModel(model) {
-    const errors = [];
-    const warnings = [];
-    const err = (code, path, message) => {
-        errors.push({ severity: "error", code, path, message });
-    };
-    const warn = (code, path, message) => {
-        warnings.push({ severity: "warning", code, path, message });
-    };
-    // --- Root shape ---
-    if (!model || typeof model !== "object") {
-        err("not-object", "(root)", "diagramModel must be a JSON object.");
-        return { ok: false, issues: errors, warnings };
-    }
-    const root = model;
-    if (root.kind !== "use-case") {
-        err("wrong-kind", "kind", `Expected kind: "use-case", got ${JSON.stringify(root.kind)}.`);
-    }
-    const parts = getParts(root);
-    if (parts.length === 0) {
-        err("no-parts", "parts", "parts[] is empty — at least one part (tab) is required.");
-        return { ok: false, issues: errors, warnings };
-    }
-    // Collect everything across all parts for cross-part id lookup.
-    const allElements = [];
-    const allRelationships = [];
-    parts.forEach((p, i) => {
-        p.elements.forEach((el) => allElements.push({ part: i, el }));
-        p.relationships.forEach((rel) => allRelationships.push({ part: i, rel }));
-    });
-    const ucs = allElements.filter((x) => x.el.kind === "useCase").map((x) => x.el);
-    const actors = allElements.filter((x) => x.el.kind === "actor").map((x) => x.el);
-    const ucIds = new Set(ucs.map((u) => String(u.id)));
-    const actorIds = new Set(actors.map((a) => String(a.id)));
-    // --- Element shape checks ---
-    ucs.forEach((uc) => {
-        const id = String(uc.id ?? "");
-        const path = `useCase[${id || "?"}]`;
-        if (!id)
-            err("uc-missing-id", path, "useCase is missing an id.");
-        if (!uc.name)
-            err("uc-missing-name", path, "useCase is missing a name.");
-        if (uc.name && typeof uc.name === "string") {
-            if (looksSendOnly(uc.name)) {
-                err("send-only-uc", `${path}.name`, `UC name "${uc.name}" looks send-only (CR #10). Fold into the UC that decided to send.`);
-            }
-            if (looksPhysical(uc.name)) {
-                warn("physical-verb", `${path}.name`, `UC name "${uc.name}" starts with a physical verb (CR #8). Prefer "Record X" / "Enter X" / "Register X" to describe the IS action.`);
-            }
-        }
-    });
-    actors.forEach((a) => {
-        const id = String(a.id ?? "");
-        const path = `actor[${id || "?"}]`;
-        if (!id)
-            err("actor-missing-id", path, "actor is missing an id.");
-        if (!a.name)
-            err("actor-missing-name", path, "actor is missing a name.");
-    });
-    // --- Relationship cross-references + CR #4 + single-include + orphaned UC ---
-    const actorAssocsByUc = new Map();
-    const includeIntoByUc = new Map();
-    const initiatorByUc = new Map();
-    allRelationships.forEach(({ rel }, i) => {
-        const path = `relationships[${i}]`;
-        const kind = rel.kind;
-        if (kind === "actorAssoc") {
-            const actorId = String(rel.actorId ?? "");
-            const ucId = String(rel.ucId ?? "");
-            if (!actorIds.has(actorId))
-                err("unknown-actor", path, `actorAssoc.actorId "${actorId}" does not exist in actors[].`);
-            if (!ucIds.has(ucId))
-                err("unknown-uc", path, `actorAssoc.ucId "${ucId}" does not exist in use cases.`);
-            if (actorIds.has(actorId) && ucIds.has(ucId)) {
-                if (!actorAssocsByUc.has(ucId))
-                    actorAssocsByUc.set(ucId, []);
-                actorAssocsByUc.get(ucId).push(rel);
-                if (rel.role === "initiator") {
-                    if (!initiatorByUc.has(ucId))
-                        initiatorByUc.set(ucId, new Set());
-                    initiatorByUc.get(ucId).add(actorId);
-                }
-            }
-        }
-        else if (kind === "include") {
-            const from = String(rel.from ?? "");
-            const to = String(rel.to ?? "");
-            if (!ucIds.has(from))
-                err("unknown-uc", path, `include.from "${from}" does not exist.`);
-            if (!ucIds.has(to))
-                err("unknown-uc", path, `include.to "${to}" does not exist.`);
-            if (ucIds.has(to)) {
-                if (!includeIntoByUc.has(to))
-                    includeIntoByUc.set(to, []);
-                includeIntoByUc.get(to).push(rel);
-            }
-        }
-        else if (kind === "extend") {
-            const from = String(rel.from ?? "");
-            const to = String(rel.to ?? "");
-            if (!ucIds.has(from))
-                err("unknown-uc", path, `extend.from "${from}" does not exist.`);
-            if (!ucIds.has(to))
-                err("unknown-uc", path, `extend.to "${to}" does not exist.`);
-        }
-        else if (kind === "generalization") {
-            const from = String(rel.from ?? "");
-            const to = String(rel.to ?? "");
-            if (!ucIds.has(from) && !actorIds.has(from))
-                err("unknown-endpoint", path, `generalization.from "${from}" is neither a UC nor an actor.`);
-            if (!ucIds.has(to) && !actorIds.has(to))
-                err("unknown-endpoint", path, `generalization.to "${to}" is neither a UC nor an actor.`);
-        }
-    });
-    // CR #4 — include target checks
-    for (const [ucId, includes] of includeIntoByUc) {
-        const path = `useCase[${ucId}]`;
-        if (includes.length < 2) {
-            err("include-single-base", path, `UC "${ucId}" is the target of only ${includes.length} «include» arrow — an include target requires ≥2 bases (CR #4). Fold into the parent UC.`);
-        }
-        if ((actorAssocsByUc.get(ucId) || []).length > 0) {
-            err("include-target-has-actor", path, `UC "${ucId}" is an «include» target AND has a direct actor association — forbidden (CR #4). An include target must have ZERO actor associations.`);
-        }
-    }
-    // §4.1 — every UC must have ≥1 initiator (unless it's purely an include target)
-    ucs.forEach((uc) => {
-        const id = String(uc.id ?? "");
-        if (!id)
-            return;
-        const path = `useCase[${id}]`;
-        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
-        const hasInitiator = (initiatorByUc.get(id)?.size ?? 0) > 0;
-        const hasAnyActor = (actorAssocsByUc.get(id) || []).length > 0;
-        if (!isIncludeTarget && !hasAnyActor) {
-            err("uc-no-actor", path, `UC "${id}" has no actor association and is not an include target. Either connect an actor or remove the UC.`);
-        }
-        if (!isIncludeTarget && hasAnyActor && !hasInitiator) {
-            err("uc-no-initiator", path, `UC "${id}" has actor associations but none with role: "initiator" (§4.1). Every UC needs at least one initiator.`);
-        }
-    });
-    // §4.4 — per-UC documentation checks (only for non-include-target UCs; include
-    // targets are sub-behaviors and can use lighter docs in practice, but we still
-    // require description + at least one scenario if any doc is present).
-    ucs.forEach((uc) => {
-        const id = String(uc.id ?? "");
-        if (!id)
-            return;
-        const path = `useCase[${id}]`;
-        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
-        const primaryActor = uc.primaryActor;
-        if (!isIncludeTarget) {
-            if (!primaryActor) {
-                err("uc-missing-primary-actor", path, `UC "${id}" is missing primaryActor (§4.4).`);
-            }
-            else if (!actorIds.has(primaryActor)) {
-                err("uc-primary-actor-unknown", path, `UC "${id}" primaryActor "${primaryActor}" is not an actor.`);
-            }
-            else if (!(initiatorByUc.get(id)?.has(primaryActor))) {
-                err("uc-primary-actor-not-initiator", path, `UC "${id}" primaryActor "${primaryActor}" is not connected with role: "initiator". The primary actor must be an initiator.`);
-            }
-        }
-        const scenarios = asArray(uc.scenarios);
-        if (!isIncludeTarget && scenarios.length === 0) {
-            err("uc-no-scenarios", path, `UC "${id}" has no scenarios. At least one scenario with a flow is required (§4.4).`);
-        }
-        scenarios.forEach((sc, si) => {
-            const sco = (sc && typeof sc === "object") ? sc : {};
-            const scPath = `${path}.scenarios[${si}]`;
-            const flow = asArray(sco.flow);
-            if (flow.length === 0) {
-                err("scenario-no-flow", scPath, `Scenario has no flow steps. At least one step is required.`);
-            }
-            flow.forEach((step, stepIdx) => {
-                const s = (step && typeof step === "object") ? step : {};
-                const sPath = `${scPath}.flow[${stepIdx}]`;
-                const k = s.kind;
-                if (k === "actor") {
-                    const aId = String(s.actor ?? "");
-                    if (!actorIds.has(aId))
-                        err("flow-unknown-actor", sPath, `Flow step references unknown actor id "${aId}".`);
-                }
-                else if (k === "include") {
-                    const uId = String(s.uc ?? "");
-                    if (!ucIds.has(uId))
-                        err("flow-unknown-uc", sPath, `Flow step «include» references unknown UC id "${uId}".`);
-                    // Also require a matching include relationship to exist.
-                    const targets = includeIntoByUc.get(uId) || [];
-                    const hasMatching = targets.some((rel) => String(rel.from) === id);
-                    if (ucIds.has(uId) && !hasMatching) {
-                        err("flow-include-mismatch", sPath, `Flow step «include» ${uId} from UC "${id}" does not have a matching include relationship in relationships[]. Add { kind: "include", from: "${id}", to: "${uId}" } or remove this step.`);
-                    }
-                }
-                else if (k === "system" || k === "extension") {
-                    // no refs to check
-                }
-                else if (k) {
-                    err("flow-unknown-kind", sPath, `Flow step kind "${String(k)}" is not one of: actor, system, include, extension.`);
-                }
-            });
-            const extensions = asArray(sco.extensions);
-            extensions.forEach((ext, ei) => {
-                const e = (ext && typeof ext === "object") ? ext : {};
-                const at = Number(e.at);
-                if (!Number.isFinite(at) || at < 1 || at > flow.length) {
-                    err("extension-bad-at", `${scPath}.extensions[${ei}]`, `Extension.at=${String(e.at)} does not reference a valid flow step (1..${flow.length}).`);
-                }
-            });
-        });
-        if (!isIncludeTarget) {
-            const pre = asArray(uc.preconditions);
-            const post = asArray(uc.postconditions);
-            const stories = asArray(uc.userStories);
-            if (pre.length === 0)
-                warn("uc-no-preconditions", path, `UC "${id}" has no preconditions — recommended.`);
-            if (post.length === 0)
-                warn("uc-no-postconditions", path, `UC "${id}" has no postconditions — recommended.`);
-            if (stories.length === 0)
-                err("uc-no-user-stories", path, `UC "${id}" has no userStories (§4.4). Add as many as the UC warrants — one per distinct user goal.`);
-            else if (stories.length === 1)
-                warn("uc-single-user-story", path, `UC "${id}" has only 1 user story. Add one per distinct stakeholder goal behind the UC; a single token story is usually incomplete.`);
-            // CR #11 — narrative content must be in Hebrew.
-            if (isMeaningful(uc.description) && !hasHebrew(uc.description)) {
-                err("non-hebrew-text", `${path}.description`, `UC description must be written in Hebrew (CR #11).`);
-            }
-            pre.forEach((p, i) => {
-                if (isMeaningful(p) && !hasHebrew(p))
-                    err("non-hebrew-text", `${path}.preconditions[${i}]`, `Precondition must be written in Hebrew (CR #11).`);
-            });
-            post.forEach((p, i) => {
-                if (isMeaningful(p) && !hasHebrew(p))
-                    err("non-hebrew-text", `${path}.postconditions[${i}]`, `Postcondition must be written in Hebrew (CR #11).`);
-            });
-            stories.forEach((s, i) => {
-                const obj = (s && typeof s === "object") ? s : {};
-                const combined = `${obj.role ?? ""} ${obj.want ?? ""} ${obj.so ?? ""}`;
-                if (isMeaningful(combined) && !hasHebrew(combined))
-                    err("non-hebrew-text", `${path}.userStories[${i}]`, `User story must be written in Hebrew (role/want/so — CR #11).`);
-            });
-            scenarios.forEach((sc, si) => {
-                const sco = (sc && typeof sc === "object") ? sc : {};
-                const scPath = `${path}.scenarios[${si}]`;
-                asArray(sco.flow).forEach((step, stepIdx) => {
-                    const s = (step && typeof step === "object") ? step : {};
-                    if (isMeaningful(s.text) && !hasHebrew(s.text))
-                        err("non-hebrew-text", `${scPath}.flow[${stepIdx}].text`, `Flow step text must be written in Hebrew (CR #11).`);
-                });
-                asArray(sco.extensions).forEach((ext, ei) => {
-                    const e = (ext && typeof ext === "object") ? ext : {};
-                    if (isMeaningful(e.text) && !hasHebrew(e.text))
-                        err("non-hebrew-text", `${scPath}.extensions[${ei}].text`, `Extension text must be written in Hebrew (CR #11).`);
-                });
-            });
-            // Wireframe safety pre-check (regex-only; defense in depth — the HTML runtime
-            // also re-checks via wireframeSafe()).
-            const wf = uc.wireframe;
-            if (typeof wf === "string" && wf.length > 0) {
-                const forbidden = [
-                    /<script\b/i,
-                    /\son\w+\s*=/i,
-                    /<iframe\b/i,
-                    /src\s*=\s*["']https?:/i,
-                    /href\s*=\s*["']https?:/i,
-                    /@import\b/i,
-                    /<style\b/i,
-                ];
-                const hit = forbidden.find((rx) => rx.test(wf));
-                if (hit) {
-                    err("wireframe-unsafe", `${path}.wireframe`, `Wireframe HTML contains a forbidden pattern (${hit}). Remove scripts / on*= / iframe / external URLs / @import / <style>.`);
-                }
-                // CR #11 — the visible text inside the wireframe (labels, buttons, headings)
-                // must be in Hebrew since the product is Hebrew. A wireframe with zero
-                // Hebrew characters is an English UI mock.
-                if (!hasHebrew(wf)) {
-                    err("wireframe-non-hebrew", `${path}.wireframe`, `Wireframe contains no Hebrew characters. Visible labels, headings, and buttons inside the wireframe must be in Hebrew (CR #11). Identifier/class names (wf-*) stay ASCII.`);
-                }
-            }
-        }
-    });
-    // CR #11 — assumptions / openQuestions must be Hebrew (they live at the model root).
-    asArray(root.assumptions).forEach((s, i) => {
-        if (isMeaningful(s) && !hasHebrew(s))
-            err("non-hebrew-text", `assumptions[${i}]`, `Assumption must be written in Hebrew (CR #11).`);
-    });
-    asArray(root.openQuestions).forEach((s, i) => {
-        if (isMeaningful(s) && !hasHebrew(s))
-            err("non-hebrew-text", `openQuestions[${i}]`, `Open question must be written in Hebrew (CR #11).`);
-    });
-    // --- Warn on too many includes (diagrams with 3+ usually have a design smell) ---
-    const totalIncludes = allRelationships.filter((r) => r.rel.kind === "include").length;
-    const totalExtends = allRelationships.filter((r) => r.rel.kind === "extend").length;
-    if (totalIncludes + totalExtends > 2) {
-        warn("many-include-extend", "relationships", `Diagram has ${totalIncludes} «include» and ${totalExtends} «extend» relationships. Most UC diagrams need ≤2 combined — review each against the §4 gate.`);
-    }
-    if (errors.length > 0)
-        return { ok: false, issues: errors, warnings };
-    return { ok: true, warnings };
-}
-export function parseAndValidate(jsonText) {
-    let parsed;
-    try {
-        parsed = JSON.parse(jsonText);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            ok: false,
-            issues: [{ severity: "error", code: "invalid-json", path: "(root)", message: `JSON parse failed: ${msg}` }],
-            warnings: [],
-        };
-    }
-    return validateModel(parsed);
-}
-export function formatIssues(issues) {
-    if (issues.length === 0)
-        return "(no issues)";
-    return issues
-        .map((i) => `- [${i.severity === "error" ? "ERROR" : "warn"}] [${i.code}] ${i.path}: ${i.message}`)
-        .join("\n");
-}