sad-mcp 2.1.1 → 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.1",
+  "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.
+`renderTimingLabels(layout)` is provided by `uc-diagram-common.js` — do not inline it.
+It is called automatically at the end of every `fixLayout` invocation.
 
-```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.
-
-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,15 +600,15 @@ The `connections` entry for a timed link looks like:
 
 ---
 
-## §WF. Wireframe Authoring (Mandatory for Human-Initiated UCs)
+## §WF. Wireframe Authoring (Opt-In)
 
-**A wireframe is required for every UC whose `primaryActor.actorType === 'human'`.** The user sees a screen; a use case without a visual mock of that screen is incomplete documentation. The validator (§12) errors on any human-initiated UC missing a wireframe.
+**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.
 
-Wireframe is **optional** (and usually omitted) only for:
+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).
 
-For every other UC, 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).
+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.
 
@@ -915,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`.
 
 ---
 
@@ -1028,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) -->
@@ -1040,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>
@@ -1056,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>
 ```
@@ -1177,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`.**
 
@@ -1195,7 +843,7 @@ 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.
-- [ ] Every UC whose primary actor is human has a wireframe (§WF). System/cron-initiated UCs and pure include-targets may omit.
+- [ ] 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.

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,393 +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;
-            // §WF — a UC initiated by a human actor must have a wireframe.
-            if (primaryActor && actorIds.has(primaryActor)) {
-                const pa = actors.find((a) => String(a.id) === primaryActor);
-                const isHuman = !pa || pa.actorType !== "system";
-                const wfMissing = typeof wf !== "string" || wf.trim() === "";
-                if (isHuman && wfMissing) {
-                    err("wireframe-missing", `${path}.wireframe`, `UC "${id}" has a human primary actor ("${primaryActor}") but no wireframe. Every human-initiated UC requires a wireframe per §WF. Add one, or explicitly use a placeholder describing what info is missing.`);
-                }
-            }
-            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");
-}