sad-mcp 1.1.2 → 1.1.3

package/package.json

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

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

@@ -21,13 +21,13 @@ The shared files prepended to this prompt define the layout recipes, model shape
 
 ## CRITICAL RULES — Check Before Every Output
 
-1. **Hebrew: male form only.** אח (not אחות). מזכיר (not מזכירה). מטופל (not מטופלת). רופא (not רופאה). Verify every Hebrew label before writing.
+1. **Hebrew: male form only.** אח (not אחות), מזכיר (not מזכירה), מטופל (not מטופלת), רופא (not רופאה), לקוח (not לקוחה), מנהל (not מנהלת), סטודנט (not סטודנטית). Verify every Hebrew label before writing.
 2. **No generic catch-all use cases.** "ניהול הגדרות מערכת" is forbidden. Each entity → its own UC.
 3. **All ellipses have solid borders.** Dashed = relationship lines only, never ellipse borders.
-4. **«include» target must have ≥2 incoming «include» arrows AND no direct actor association.** A UC connected to an actor can NEVER be an «include» target. A single «include» arrow is always wrong — fold it into the parent.
+4. **«include» requires BOTH: ≥2 base UCs point to it AND zero actor associations on the target.** Fail either half → the «include» is wrong. A single incoming «include» is always wrong — fold into the parent. See §4 for the mandatory justification gate.
 5. **Every use case must have at least one association line to an actor.**
 6. **Actors must not overlap** — minimum 200px vertical distance between actor centers.
-7. **Default: no «include» or «extend».** Most diagrams need zero or one. If you have more than two, you are almost certainly wrong. Treat every «include»/«extend» you consider adding as guilty until proven innocent.
+7. **Default: zero «include» and zero «extend».** Most diagrams need none. More than two is almost always wrong. §4 defines a gate every such relationship must pass before you draw it.
 
 ---
 
@@ -37,24 +37,24 @@ The shared files prepended to this prompt define the layout recipes, model shape
 |---|---|
 | **System name/boundary** | Names the rectangle |
 | **Human actors** (roles) | External humans who interact with the system |
-| **System actors** (external systems) | Draw as «system» rectangle |
+| **System actors** (external systems) | Drawn as a stick figure with `«system»` stereotype (not a rectangle) |
 | **Actor generalizations** | Child actor does everything parent does + more |
 | **System administrator** | Almost always present — manages master data for every entity |
 | **Use cases** | One per user goal at goal-granularity level |
-| **Shared mandatory sub-behaviors** | «include» candidates — must be needed by 2+ UCs |
-| **Optional/conditional behaviors** | «extend» candidates |
+| **Shared mandatory sub-behaviors** | «include» candidates — must pass the §4 gate |
+| **Optional/conditional behaviors** | «extend» candidates — must pass the §4 gate |
 | **Language for labels** | Hebrew, English, or bilingual |
 
 ---
 
 ## 2. Actor Rules
 
-- **Human actor**: stick figure with name below
-- **System actor**: stick figure with `«system»` (italic, 9px) on the first label line and the actor name on the second line. Use a distinct head fill (`#fef3c7` amber) to visually distinguish from human actors. **Do NOT draw a rectangle** — UML rectangles for system actors are not taught in this course.
-- **Primary actors**: left side. **Secondary/admin actors**: right side. **External system actors** (e.g. LTI provider) that only connect to one UC: below the boundary
-- **Generalization**: solid line, hollow triangle at parent end. Route as **L-shape** (horizontal away from boundary, then vertical, then back) — never a straight diagonal that crosses other actors
+- **Human actor**: stick figure with name below.
+- **System actor**: stick figure with `«system»` (italic, 9px) on the first label line and the actor name on the second. Use a distinct head fill (`#fef3c7` amber) to visually distinguish from humans. **Do NOT draw a rectangle** — the course does not teach the rectangle form.
+- **Positioning**: primary actors on the left, secondary/admin on the right, external systems that connect to only one UC below the boundary.
+- **Generalization**: solid line, hollow triangle at the parent end. Route as an **L-shape** (horizontal away from boundary, then vertical, then back) — never a diagonal that crosses other actors.
 
-**System administrator** — add unless explicitly excluded. Responsible for managing the master data of every entity the system references. Each entity gets its own specific UC (not one catch-all).
+**System administrator** — include unless explicitly excluded. Responsible for managing the master data of every entity the system references. Each entity gets its own specific UC (not one catch-all).
 
 ---
 
@@ -63,68 +63,82 @@ The shared files prepended to this prompt define the layout recipes, model shape
 **Granularity**: one complete user goal per UC, achievable in one session.
 
 **When to combine vs. separate "ניהול X":**
-- Simple entity (just a form): single "ניהול X" is fine
-- Complex entity with sub-items, lifecycle states, or different actors per operation: separate UCs (open / update / cancel / approve)
+- Simple entity (just a form): single "ניהול X" is fine.
+- Complex entity with sub-items, lifecycle states, or different actors per operation: separate UCs (open / update / cancel / approve).
 
 **Implied UCs**: every entity the system references needs at least one UC that manages it.
 
 ---
 
-## 4. Include and Extend
+## 4. Include and Extend — Mandatory Justification Gate
 
-**Start with zero.** Add «include» or «extend» only when you can explicitly justify it against the tests below. When in doubt, leave it out.
+**Default to zero.** Treat every «include» and «extend» as guilty until proven innocent. Before drawing ANY such relationship, write the relevant block below in your planning text. **If you cannot fill it in truthfully, the relationship does not exist — do not draw it.**
 
-### «include»
-«include» means: every time the base UC runs, the included UC **always** runs as part of it — no exceptions, no conditions. It is not "if X happens, then Y" — that is «extend». It is "X always does Y as part of its execution."
+### «include» justification block
 
-However, **always-happens does not automatically mean extract**. A step that always happens inside a UC is usually just part of that UC. Only extract it when:
-1. It is shared by **2 or more** base UCs — there must be ≥2 incoming «include» arrows
-2. The included UC has **no direct association to any actor** — actor-connected UCs are standalone UCs, not sub-behaviors
-3. Extracting it genuinely reduces duplication — not just because it feels like a "step"
+```
+«include» candidate: __________________________________
+  Base UC #1 (actor-initiated, runs target every time): __________
+  Base UC #2 (actor-initiated, runs target every time): __________
+  Target has zero direct actor associations?  yes / no
+  Extracting reduces real duplication (not just "feels like a step")?  yes / no
+
+  → If Base UC #2 is blank → DELETE the «include». Fold into Base UC #1.
+  → If actor-associations = yes → DELETE. The target is a regular UC, not a helper.
+  → If duplication reduction = no → DELETE. A step inside one UC is just a step.
+```
+
+Semantics: «include» means the target runs **every single time** the base runs, unconditionally. It is never "sometimes X". That is «extend».
+
+Arrow: dashed, open arrowhead, `Base UC → Included UC`.
 
-Arrow direction: Base UC → Included UC. Dashed line, open arrowhead.
+### «extend» justification block
 
-**Immediate disqualifiers:**
-- Only one base UC points to it → fold it into the parent UC
-- An actor connects to it → it is a regular standalone UC, not an «include» target
-- It is conditional or optional → that is «extend», not «include»
+```
+«extend» candidate: __________________________________
+  Base UC being extended: __________
+  Exact trigger: "when __________ happens" (one sentence, specific condition)
+  Base UC runs correctly without the extension?  yes / no
+  Is this behavior significant enough to model (not every trivial optional path)?  yes / no
+
+  → If trigger is vague or cannot be stated in one sentence → DELETE.
+  → If base UC does NOT run correctly without it → it is not «extend». Reconsider as «include» (if always) or as part of the base UC.
+  → If insignificant → DELETE. Not every optional step deserves «extend».
+```
 
-### «extend»
-«extend» means: sometimes, under a specific condition, an additional behavior fires. The base UC runs fine without it.
+Arrow: dashed, open arrowhead, `Extension UC → Base UC`. Use at most once or twice per diagram.
 
-Arrow direction: Extension UC → Base UC. Use at most once or twice per diagram. If you cannot state the exact condition in one sentence, do not add it.
+### Quick disqualifiers
+
+- Exactly one incoming «include» arrow → fold into the parent.
+- Actor directly connects to an alleged «include» target → it is a standalone UC, not a sub-behavior.
+- "Always happens as part of X" alone is not enough — it must also be shared by ≥2 bases.
+- Conditional or optional behavior → this is «extend» territory, not «include».
 
 ---
 
 ## 5. Notation
 
-### Actors
-```
-Human:       stick figure — circle (head) + lines (body/arms/legs), name below
-System:      rectangle with «system» stereotype label, name inside
-Generalization: solid line, hollow triangle at parent end, L-shaped routing
-```
+Colors, stroke widths, and font sizes live in §10 Styling. Line-type semantics and canonical arrow directions are owned by `NOTATION.md §3`. This section captures only the implementation-specific details the generator needs.
+
+### Actor rendering
+- Human: stick figure — head circle + body/arms/legs lines, name below.
+- System: same stick figure with amber head fill and `«system»` label line above the name.
+- Generalization: solid line, hollow triangle at parent end, L-shaped routing.
 
 ### System boundary
 Large rounded rectangle (`rx=12`), title bar on top with system name (white text on `#1e40af` background).
 
 ### Use case ellipses
-- Horizontal ellipse: `rx` 70–125, `ry` 25–32 (size to fit text)
-- Fill: `#d4e9f7`, solid border `#2980b9` (1.8px) — **always solid, no exceptions**
-- Text: centered, 11px, may wrap 2 lines
-
-### Association lines
-- Actor ↔ UC: solid line, **no arrowhead**
-- «include»/«extend»: dashed (dasharray 6 4), open arrowhead, `#7c3aed` stroke
-- Stereotype label (6 4 dashed line): 9.5px near midpoint
+- Horizontal ellipse: `rx` 70–125, `ry` 25–32 (size to fit text).
+- Fill `#d4e9f7`, solid border `#2980b9` (1.8px) — **always solid, no exceptions**.
+- Text centered, 11px, may wrap to 2 lines.
 
 ### Ellipse endpoint calculation (mandatory)
-
-Use `ellipse-boundary-intersect` from the shared layout recipes for all line endpoints. Never draw a line to the ellipse center — it disappears under the fill.
+Never draw a line to the ellipse center — it disappears under the fill. Compute the boundary intersection:
 
 ```javascript
-// From shared layout-recipes.md:
-// ellipse-boundary-intersect(cx, cy, rx, ry, externalPoint)
+// Shared layout-recipes.md: ellipse-boundary-intersect(cx, cy, rx, ry, externalPoint)
 angle = Math.atan2(externalPoint.y - cy, externalPoint.x - cx);
 endpoint = { x: cx + rx * Math.cos(angle), y: cy + ry * Math.sin(angle) };
 ```
@@ -133,149 +147,20 @@ endpoint = { x: cx + rx * Math.cos(angle), y: cy + ry * Math.sin(angle) };
 1. Background + dot grid
 2. System boundary rectangle
 3. Association lines (solid)
-4. «include»/«extend» dashed lines with labels
+4. «include» / «extend» dashed lines with labels
 5. Generalization lines with triangles
 6. Use case ellipses (covers line endpoints — draw last among shapes)
 7. Actor figures and labels
 
-No legend. Do not add a legend bar to the diagram.
-
----
-
-## 6. Layout Algorithm
-
-**The Fix Layout algorithm (§8) is the primary placement path.** Run it on `DOMContentLoaded` — do not rely on initial coordinates being perfect. Initial coordinates are starting hints only.
-
-### Initial placement
-
-**Step 1 — Assign UCs to actor groups**
-For each UC, identify its primary actor (the one with the most associations or the initiating actor). Assign the UC to that actor's side (left/right/center).
-
-**Step 2 — Sort actors with `actor-adjacency-sort` (from shared layout-recipes.md)**
-Before placing actors, sort actors on each side by the barycentric Y of their UC groups to minimize line crossings.
-
-**Step 3 — Initial UC positions with `row-grid-pack`**
-Place UCs in each column using `row-grid-pack`:
-```
-left column:   x = boundary.x + boundary.width * 0.27
-right column:  x = boundary.x + boundary.width * 0.73
-center column: x = boundary.x + boundary.width * 0.50
-rowHeight = max(ry * 2 + 80, 80)
-```
-
-**Step 4 — Place actors at vertical center of their UC groups**
-```javascript
-actor.y = average(actor.ucIds.map(id => useCases[id].cy));
-actor.x = side === 'left' ? boundary.x - 120 : boundary.x + boundary.width + 120;
-```
-
-**Step 5 — Run `collision-nudge` on UCs** (from shared layout-recipes.md)
-
-**Step 6 — Run `validateLayout()` then `fixLayout()` on `DOMContentLoaded`**
-
-`validateLayout` (§8a) must run before applying positions. It catches three problems the placement step does not: UCs overlapping the header bar, UCs overlapping each other within a column, and UCs overflowing the boundary bottom. After validation, boundary height and SVG viewBox are expanded automatically.
-
-```javascript
-document.addEventListener('DOMContentLoaded', () => {
-  validateLayout(part);   // fix positions, expand boundary if needed
-  applyLayout(svgId, part); // write to SVG
-});
-```
+**No legend.** Do not add a legend bar to the diagram.
 
 ---
 
-## 7. Splitting Rules
+## 6. Layout
 
-Split into multiple tabs when **use case count > 8** OR when the system clearly has distinct functional areas (clinical vs. admin, customer vs. back-office).
+One entry point: `fixLayout(layout)`. It runs on `DOMContentLoaded` **and** whenever the Fix Layout button is clicked. It is idempotent — clicking 1 or 10 times produces the same result. Initial `cx`/`cy` coordinates you write in the SVG are starting hints; `fixLayout` is the authority.
 
-**How to split:**
-- One tab per **actor group** (e.g., "מטופל" tab, "מנהל" tab) or functional area
-- Shared UCs appear in both tabs with a "(shared with Tab N)" badge
-- Each tab has its own complete SVG (its own boundary, actors, ellipses, lines)
-- Each tab has a visible **split rationale line**: `"Split by actor group: [actor names] — [N] UCs > 8 threshold"`
-- Run `fixLayout()` independently per tab on load
-
-For tabbed layouts: `diagramLayouts` array, one entry per tab.
-
----
-
-## 8a. validateLayout — Boundary & Overlap Validation (Required)
-
-Run this **before** writing positions to the SVG. It is idempotent.
-
-```javascript
-// Named constants — tune these, do not hardcode magic numbers elsewhere
-const HEADER_H = 44;   // boundary header height in px
-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
-
-function validateLayout(part) {
-  const b   = part.boundary;
-  const ucs = part.useCases;
-
-  const minX = b.x + UC_PAD;
-  const maxX = b.x + b.w - UC_PAD;
-  const minY = b.y + HEADER_H + UC_PAD;
-
-  let changed = true, iter = 0;
-  while (changed && iter++ < 40) {
-    changed = false;
-
-    // 1. Clamp horizontal positions inside boundary
-    for (const uc of ucs) {
-      const nx = Math.max(minX + uc.rx, Math.min(maxX - uc.rx, uc.cx));
-      if (nx !== uc.cx) { uc.cx = nx; changed = true; }
-    }
-
-    // 2. Push UCs below header
-    for (const uc of ucs) {
-      const ny = Math.max(minY + uc.ry, uc.cy);
-      if (ny !== uc.cy) { uc.cy = ny; changed = true; }
-    }
-
-    // 3. Resolve vertical overlaps within each column
-    const cols = {};
-    for (const uc of ucs) {
-      const col = uc.col || 'center';
-      (cols[col] = cols[col] || []).push(uc);
-    }
-    for (const col of Object.values(cols)) {
-      col.sort((a, b) => a.cy - b.cy);
-      for (let i = 1; i < col.length; i++) {
-        const prev = col[i-1], cur = col[i];
-        const needed = prev.cy + prev.ry + UC_GAP + cur.ry;
-        if (cur.cy < needed) { cur.cy = needed; changed = true; }
-      }
-    }
-  }
-
-  // 4. Expand boundary height to fit all UCs
-  const maxBottom = Math.max(...ucs.map(uc => uc.cy + uc.ry));
-  const requiredH = maxBottom - b.y + UC_PAD;
-  if (requiredH > b.h) b.h = requiredH;
-
-  // 5. Re-center left/right actors on their UC groups
-  for (const actor of part.actors) {
-    if (actor.side === 'left' || actor.side === 'right') {
-      const myUCIds = part.connections.filter(c => c.from === actor.id).map(c => c.to);
-      const myUCs   = ucs.filter(uc => myUCIds.includes(uc.id));
-      if (myUCs.length) actor.y = myUCs.reduce((s, uc) => s + uc.cy, 0) / myUCs.length;
-    }
-    // Push bottom actors below expanded boundary
-    if (actor.side === 'bottom') actor.y = b.y + b.h + 80;
-  }
-}
-```
-
-**When to call**: always before `applyLayout`. Both on `DOMContentLoaded` and when the Fix Layout button is clicked.
-
----
-
-## 8. Fix Layout Algorithm (Primary Placement Path)
-
-This algorithm runs automatically on page load AND is triggered by the "Fix Layout" button. It is **idempotent** — clicking 1 or 10 times produces the same result.
-
-### Required data structure
+### Data structure
 
 ```javascript
 const diagramLayout = {
@@ -298,21 +183,27 @@ const diagramLayout = {
 };
 ```
 
-### SVG element conventions (required for fix algorithm)
+### SVG element conventions (required)
 
-- **UC groups**: `<g id="uc-group-{ucId}">` with `<ellipse cx="..." cy="...">` (NOT transforms for UC positioning)
-- **Actor groups**: `<g id="actor-group-{actorId}" transform="translate(x,y)">`
-- **Connection lines**: `<line data-conn-from="{id}" data-conn-to="{id}" x1 y1 x2 y2>`
+- UC groups: `<g id="uc-group-{ucId}">` with `<ellipse cx="..." cy="...">` — do NOT use `transform` to position UCs.
+- Actor groups: `<g id="actor-group-{actorId}" transform="translate(x,y)">`.
+- Connection lines: `<line data-conn-from="{id}" data-conn-to="{id}" x1 y1 x2 y2>`.
 
-### Fix algorithm
+### fixLayout implementation
 
 ```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
+const ACTOR_PAD = 80;   // horizontal gap between boundary and actor column
+
 function fixLayout(layout) {
   const svg = document.getElementById(layout.svgId);
   if (!svg) return;
-  const pad = 80;
+  const b = layout.boundary;
 
-  // Step 1: Group UCs by actor side
+  // Step 1 — Group UCs by the side of their owning actor.
   const ucSide = {};
   layout.actors.forEach(a =>
     a.ucIds.forEach(uid => {
@@ -322,41 +213,69 @@ function fixLayout(layout) {
   const cols = { left: [], right: [], center: [] };
   layout.useCases.forEach(uc => cols[ucSide[uc.id] || 'center'].push(uc));
 
-  // Step 2: Sort each column by actor order (top-to-bottom on that side)
+  // Step 2 — Sort each column by actor order (top-to-bottom on that side).
   function sortCol(ucs, side) {
-    const ordered = layout.actors.filter(a => a.side === side).sort((a,b) => a.y - b.y);
-    ucs.sort((a, b) => {
+    const ordered = layout.actors.filter(a => a.side === side).sort((a, bb) => a.y - bb.y);
+    ucs.sort((a, bb) => {
       const ai = ordered.findIndex(act => act.ucIds.includes(a.id));
-      const bi = ordered.findIndex(act => act.ucIds.includes(b.id));
+      const bi = ordered.findIndex(act => act.ucIds.includes(bb.id));
       return (ai < 0 ? 999 : ai) - (bi < 0 ? 999 : bi);
     });
   }
-  sortCol(cols.left, 'left');
+  sortCol(cols.left,  'left');
   sortCol(cols.right, 'right');
 
-  // Step 3: Assign Y positions
-  const bx = layout.boundary.x, bw = layout.boundary.width, by = layout.boundary.y;
+  // Step 3 — Initial Y assignment per column.
   function place(ucs, colX) {
     ucs.forEach((uc, i) => {
-      uc.cy = by + 70 + i * (uc.ry * 2 + pad) + uc.ry;
+      uc.cy = b.y + HEADER_H + UC_PAD + uc.ry + i * (uc.ry * 2 + UC_GAP);
       uc.cx = colX;
+      uc.col = ucSide[uc.id] || 'center';
     });
   }
-  place(cols.left,   bx + bw * 0.28);
-  place(cols.right,  bx + bw * 0.72);
-  place(cols.center, bx + bw * 0.50);
+  place(cols.left,   b.x + b.width * 0.28);
+  place(cols.right,  b.x + b.width * 0.72);
+  place(cols.center, b.x + b.width * 0.50);
+
+  // Step 4 — Clamp and resolve overlaps. Idempotent fixed-point loop.
+  const minX = b.x + UC_PAD;
+  const maxX = b.x + b.width - UC_PAD;
+  const minY = b.y + HEADER_H + UC_PAD;
+  let changed = true, iter = 0;
+  while (changed && iter++ < 40) {
+    changed = false;
+    for (const uc of layout.useCases) {
+      const nx = Math.max(minX + uc.rx, Math.min(maxX - uc.rx, uc.cx));
+      if (nx !== uc.cx) { uc.cx = nx; changed = true; }
+      const ny = Math.max(minY + uc.ry, uc.cy);
+      if (ny !== uc.cy) { uc.cy = ny; changed = true; }
+    }
+    for (const col of Object.values(cols)) {
+      col.sort((a, bb) => a.cy - bb.cy);
+      for (let i = 1; i < col.length; i++) {
+        const prev = col[i - 1], cur = col[i];
+        const needed = prev.cy + prev.ry + UC_GAP + cur.ry;
+        if (cur.cy < needed) { cur.cy = needed; changed = true; }
+      }
+    }
+  }
 
-  // Step 4: Recenter actors on their UC groups
+  // Step 5 — Expand boundary height to fit all UCs.
+  const maxBottom = Math.max(...layout.useCases.map(uc => uc.cy + uc.ry));
+  b.height = Math.max(b.height, maxBottom - b.y + UC_PAD);
+
+  // Step 6 — Re-center actors on their UC group; push bottom actors below boundary.
   layout.actors.forEach(actor => {
     const myUCs = layout.useCases.filter(u => actor.ucIds.includes(u.id));
-    if (myUCs.length) actor.y = myUCs.reduce((s,u) => s + u.cy, 0) / myUCs.length;
+    if (actor.side === 'left' || actor.side === 'right') {
+      if (myUCs.length) actor.y = myUCs.reduce((s, u) => s + u.cy, 0) / myUCs.length;
+      actor.x = actor.side === 'left' ? b.x - ACTOR_PAD : b.x + b.width + ACTOR_PAD;
+    } else if (actor.side === 'bottom') {
+      actor.y = b.y + b.height + ACTOR_PAD;
+    }
   });
 
-  // Step 5: Expand boundary height if needed
-  const maxY = Math.max(...layout.useCases.map(u => u.cy + u.ry));
-  layout.boundary.height = Math.max(layout.boundary.height, maxY - by + 60);
-
-  // Step 6: Apply positions — absolute attributes only, never cumulative
+  // Step 7 — Write UC positions to the SVG (absolute attributes; translate deltas on text).
   layout.useCases.forEach(uc => {
     const g = document.getElementById('uc-group-' + uc.id);
     if (!g) return;
@@ -377,7 +296,7 @@ function fixLayout(layout) {
     if (g) g.setAttribute('transform', `translate(${actor.x},${actor.y})`);
   });
 
-  // Step 7: Recalculate all line endpoints using ellipse-boundary-intersect
+  // Step 8 — Recalculate every connection line endpoint.
   svg.querySelectorAll('[data-conn-from][data-conn-to]').forEach(line => {
     const fId = line.getAttribute('data-conn-from');
     const tId = line.getAttribute('data-conn-to');
@@ -385,23 +304,23 @@ function fixLayout(layout) {
     const fAc = layout.actors.find(a => a.id === fId);
     const tUC = layout.useCases.find(u => u.id === tId);
     const tAc = layout.actors.find(a => a.id === tId);
-    const from = fAc ? {x: fAc.x, y: fAc.y} : fUC ? {x: fUC.cx, y: fUC.cy} : null;
-    const to   = tAc ? {x: tAc.x, y: tAc.y} : tUC ? {x: tUC.cx, y: tUC.cy} : null;
+    const from = fAc ? { x: fAc.x, y: fAc.y } : fUC ? { x: fUC.cx, y: fUC.cy } : null;
+    const to   = tAc ? { x: tAc.x, y: tAc.y } : tUC ? { x: tUC.cx, y: tUC.cy } : null;
     if (!from || !to) return;
     let x1 = from.x, y1 = from.y, x2 = to.x, y2 = to.y;
-    if (fUC) { const a = Math.atan2(to.y-fUC.cy, to.x-fUC.cx); x1=fUC.cx+fUC.rx*Math.cos(a); y1=fUC.cy+fUC.ry*Math.sin(a); }
-    if (tUC) { const a = Math.atan2(from.y-tUC.cy, from.x-tUC.cx); x2=tUC.cx+tUC.rx*Math.cos(a); y2=tUC.cy+tUC.ry*Math.sin(a); }
-    line.setAttribute('x1',x1); line.setAttribute('y1',y1);
-    line.setAttribute('x2',x2); line.setAttribute('y2',y2);
+    if (fUC) { const a = Math.atan2(to.y - fUC.cy, to.x - fUC.cx);   x1 = fUC.cx + fUC.rx * Math.cos(a); y1 = fUC.cy + fUC.ry * Math.sin(a); }
+    if (tUC) { const a = Math.atan2(from.y - tUC.cy, from.x - tUC.cx); x2 = tUC.cx + tUC.rx * Math.cos(a); y2 = tUC.cy + tUC.ry * Math.sin(a); }
+    line.setAttribute('x1', x1); line.setAttribute('y1', y1);
+    line.setAttribute('x2', x2); line.setAttribute('y2', y2);
   });
 
-  // Step 8: Resize boundary rect + viewBox
+  // Step 9 — Resize boundary rect and SVG viewBox.
   const br = svg.querySelector('.system-boundary, rect[rx="12"]');
-  if (br) br.setAttribute('height', layout.boundary.height);
+  if (br) br.setAttribute('height', b.height);
   const vb = svg.getAttribute('viewBox');
   if (vb) {
     const p = vb.split(/\s+/);
-    p[3] = Math.max(parseFloat(p[3]), by + layout.boundary.height + 80);
+    p[3] = Math.max(parseFloat(p[3]), b.y + b.height + 120);
     svg.setAttribute('viewBox', p.join(' '));
   }
 }
@@ -424,9 +343,39 @@ function fixLayout(layout) {
 
 ---
 
-## 9. Clickable Descriptions for UCs and Actors (Always Include)
+## 7. Splitting Into Multiple Diagrams
+
+Split the use case diagram into multiple tabs in one HTML file when **either** trigger fires:
+
+1. **Total UC count > 8.**
+2. **≥2 actor groups each own ≥3 UCs, and those groups share no UCs with each other** (truly disjoint responsibilities — e.g., clinical side vs. admin side).
+
+If neither trigger fires, produce a single tab. Do not split on gut feeling.
+
+### Examples
+
+| Scenario | UC count | Actor groups | Split? | Reason |
+|---|---|---|---|---|
+| Small library system | 5 | 1 (reader) | **No** | Both triggers fail |
+| Coffee shop | 7 | 2 (customer 4 UCs, barista 3 UCs) disjoint | **Yes** | Trigger #2 fires |
+| Hospital clinic | 12 | 1 (doctor) owns most | **Yes** | Trigger #1 fires |
+| Course registration | 8 | 2 (student 5, admin 3) — share "login" only | **Yes** | Trigger #2 fires (login handled via cross-tab stub) |
+
+### Mechanics
+
+- One tab per actor group or per functional area.
+- **Cross-tab connections:** draw the stub on each side with the partner's name and a `(→ Tab N)` label. Do NOT try to route a line across tabs.
+- Each tab has its own complete SVG (its own boundary, actors, ellipses, lines).
+- Each tab has a visible **split-rationale line** below the tab bar. Use whichever trigger actually fired:
+  - `"Split by UC count: 12 UCs > 8 threshold"` or
+  - `"Split by actor groups: [group A] / [group B] — disjoint responsibilities"`.
+- Store all tabs in a `diagramLayouts` array (one entry per tab). Call `fixLayout(diagramLayouts[i])` for every tab on `DOMContentLoaded`. See §11 for the `showDiagram(index)` wiring.
+
+---
+
+## 8. Clickable Descriptions for UCs and Actors (Always Include)
 
-Every UC ellipse **and every actor** must be clickable — click shows a floating panel with name + description. Use a single `showDesc(id, type, event)` function for both.
+Every UC ellipse **and** every actor must be clickable — click shows a floating panel with name + description. One `showDesc(id, type, event)` function handles both.
 
 ```javascript
 const useCaseDescriptions = {
@@ -469,27 +418,26 @@ document.addEventListener('click', e => {
 ```
 
 UC group: `<g id="uc-uc1" data-uc-id="uc1" onclick="showDesc('uc1','uc',event)" style="cursor:pointer">`
-
 Actor group: `<g id="actor-student" data-actor-id="student" onclick="showDesc('student','actor',event)" style="cursor:pointer">`
 
-**Association label (timing/frequency):** When an actor connection has a timing annotation (e.g., "פעם ביום" for a system cron actor), add a `<text>` element with a white `<rect>` behind it at the midpoint of the line. Position the midpoint after `applyLayout` computes the endpoints.
+**Association labels (timing/frequency):** when an actor connection has a timing annotation (e.g., "פעם ביום" for a cron actor), add a `<text>` with a white `<rect>` behind it at the midpoint of the line after `fixLayout` has set the endpoints.
 
 ---
 
-## 10. diagramModel (mandatory)
+## 9. diagramModel (mandatory)
 
-Define this variable in every generated HTML `<script>` block, following the `model-shape.md` spec for `kind: 'use-case'`. Every actor, use case, and relationship must be represented. The VP exporter walks this variable.
+Define this variable in every generated HTML `<script>` block, following the `model-shape.md` spec for `kind: 'use-case'`. Every actor, use case, and relationship must be represented. The Visual Paradigm exporter walks this variable.
 
 ---
 
-## 11. Styling
+## 10. Styling
 
 ```
 Background:         #f8fafc, dot-grid (24px, #cbd5e1, r=0.8)
 System boundary:    fill white, stroke #3b82f6 (2.5px), header fill #1e40af, rx=12
 Ellipse:            fill #d4e9f7, stroke #2980b9 (1.8px), solid
 Ellipse text:       #1a1a2e, 11px, weight 500, text-anchor middle
-Actor stick figure: stroke #334155 (2px), head fill #e0f0ff
+Actor stick figure: stroke #334155 (2px), human head fill #e0f0ff, system head fill #fef3c7
 Actor label:        #1e293b, 11px, weight 600, text-anchor middle
 Association line:   #334155, 1.8px, no arrowhead
 Include/extend:     #7c3aed, 1.6px, dasharray 6 4, open arrowhead, label 9.5px
@@ -500,7 +448,7 @@ Fonts:              'Noto Sans Hebrew' + 'IBM Plex Mono' from Google Fonts
 
 ---
 
-## 12. HTML File Structure
+## 11. HTML File Structure
 
 ```html
 <!DOCTYPE html>
@@ -513,86 +461,84 @@ Fonts:              'Noto Sans Hebrew' + 'IBM Plex Mono' from Google Fonts
 </head>
 <body>
   <!-- Tab bar (only when split) -->
-  <div class="tab-bar">...</div>
+  <div class="tab-bar">
+    <button class="tab active" onclick="showDiagram(0)">[Tab 1 label]</button>
+    <button class="tab"        onclick="showDiagram(1)">[Tab 2 label]</button>
+  </div>
+
+  <!-- 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) -->
   <div style="text-align:center;margin:8px 0;">
-    <button onclick="fixLayout(diagramLayout)" class="fix-btn">Fix Layout</button>
+    <button onclick="fixLayout(currentLayout())" class="fix-btn">Fix Layout</button>
   </div>
 
-  <!-- Split rationale (only when split) -->
-  <div class="split-rationale">Split by actor group: [...] — N UCs > 8 threshold</div>
-
-  <!-- Diagram SVG -->
-  <div id="diagram-0">
-    <svg id="diagram-svg" viewBox="0 0 1100 900" xmlns="http://www.w3.org/2000/svg">
+  <!-- One container per tab; inactive tabs are hidden. -->
+  <div class="diagram-part" id="diagram-0">
+    <svg id="diagram-svg-0" viewBox="0 0 1100 900" xmlns="http://www.w3.org/2000/svg">
       <!-- dot grid, boundary, association lines, include/extend lines,
            generalization lines, UC ellipse groups, actor groups -->
     </svg>
   </div>
+  <div class="diagram-part" id="diagram-1" hidden>
+    <svg id="diagram-svg-1" viewBox="0 0 1100 900" xmlns="http://www.w3.org/2000/svg">...</svg>
+  </div>
 
   <!-- VP export button -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
   <script>
-    const diagramLayout = { ... };              // §8 data structure
-    const useCaseDescriptions = { ... };        // §9
-    const diagramModel = { ... };               // model-shape.md for kind:'use-case'
-    function fixLayout(layout) { ... }          // §8 algorithm
-    function showDescription(id, e) { ... }     // §9
-    function hideDescription() { ... }
-    function xmiBody(elements, rels) { ... }    // export-buttons.md
-    function exportXMI() { ... }
-    function xmlEscape(s) { ... }
-    function downloadFile(...) { ... }
-    // Run layout on page load:
-    document.addEventListener('DOMContentLoaded', () => fixLayout(diagramLayout));
+    const diagramLayouts = [ /* one layout object per tab, per §6 */ ];
+    const useCaseDescriptions = { /* §8 */ };
+    const actorDescriptions   = { /* §8 */ };
+    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 */ }
+    function hideDesc() { /* §8 */ }
+    function xmiBody(elements, rels) { /* export-buttons.md */ }
+    function exportXMI() { /* export-buttons.md */ }
+
+    document.addEventListener('DOMContentLoaded', () => {
+      diagramLayouts.forEach(l => fixLayout(l));
+    });
   </script>
 </body>
 </html>
 ```
 
-For **tabbed layouts**, add the `showDiagram(index)` function and run `fixLayout(diagramLayouts[i])` for each tab index on `DOMContentLoaded`.
+For a single-tab diagram, drop the tab bar, the split-rationale line, and the second `.diagram-part`; keep `diagramLayouts` as a one-element array so `showDiagram` / `fixLayout` wiring stays uniform.
 
 ---
 
-## 13. Output
-
-- Save as `[system_name]_use_case_diagram.html`
-- Briefly state: actor count, use case count, include/extend relationships, whether split (and why)
-
----
+## 12. Output
 
-## 14. Pre-Delivery Checklist
-
-- [ ] Every Hebrew label uses male form — אח not אחות, מזכיר not מזכירה, מטופל not מטופלת
-- [ ] No generic "ניהול הגדרות מערכת" or combined-entity UCs
-- [ ] All ellipses have solid borders (zero dashed ellipses)
-- [ ] Every «include» has ≥2 incoming arrows; included UC has no direct actor association
-- [ ] Every UC has ≥1 association line to an actor (no orphaned ellipses)
-- [ ] Actors ≥200px vertical distance from each other
-- [ ] SVG draw order: boundary → lines → ellipses → actors
-- [ ] `validateLayout()` runs before `applyLayout()` — both on load and on Fix Layout click
-- [ ] No UC overlaps the header bar (uc.cy - uc.ry >= boundary.y + HEADER_H + UC_PAD)
-- [ ] No two UCs in the same column overlap each other (gap >= UC_GAP)
-- [ ] Boundary height auto-expanded if UCs exceed initial height
-- [ ] SVG viewBox large enough to show all actors including bottom actors
-- [ ] Ellipse endpoints computed via `ellipsePt` (not drawn to center)
-- [ ] UC description popups wired to every `data-uc-id` element
-- [ ] Actor description popups wired to every `data-actor-id` element
-- [ ] System actors drawn as stick figures with `«system»` italic label (not rectangles)
-- [ ] Bottom actors (external systems connecting only below) positioned below boundary
-- [ ] If split: each tab has a split-rationale line; layout applied independently per tab
-- [ ] `diagramModel` defined per model-shape.md
-- [ ] VP export button present and wired to `exportXMI()`
+- Save as `[system_name]_use_case_diagram.html`.
+- Briefly state: actor count, use case count, include/extend relationships (with the justification line for each), whether split (and which trigger fired).
 
 ---
 
-## 15. Hebrew Language Guidelines
-
-Always use **male grammatical form** (זכר) for all Hebrew actor and role names.
-
-✅ רופא, אח, מטופל, לקוח, מנהל, עובד, משתמש, סטודנט, מרצה
-❌ אחות, מטופלת, לקוחה, מנהלת, מזכירה, סטודנטית
-
-When in doubt, use the male form.
+## 13. Pre-Delivery Checklist
+
+- [ ] Every «include» and «extend» has a written §4 justification block; any that cannot be filled in has been deleted.
+- [ ] No «include» with exactly one incoming arrow — every include target has ≥2 bases AND zero actor associations.
+- [ ] No generic "ניהול הגדרות מערכת" or combined-entity UCs; each entity has its own UC.
+- [ ] Every UC has ≥1 association line to an actor (no orphaned ellipses).
+- [ ] All ellipses have solid borders (zero dashed ellipses).
+- [ ] SVG draw order: boundary → lines → ellipses → actors.
+- [ ] Ellipse endpoints computed via boundary intersection (not drawn to center).
+- [ ] `fixLayout` runs on `DOMContentLoaded` and on the Fix Layout button; uses named constants (HEADER_H, UC_PAD, UC_GAP, ACTOR_PAD), not magic numbers.
+- [ ] UC and actor description popups wired to every `data-uc-id` / `data-actor-id` element.
+- [ ] System actors drawn as stick figures with `«system»` label (not rectangles).
+- [ ] If split: each tab has a split-rationale line citing the actual trigger that fired (count > 8, or 2+ disjoint actor groups); `showDiagram` and per-tab `fixLayout` wired per §11.
+- [ ] `diagramModel` defined per `model-shape.md`; VP export button present and wired to `exportXMI()`.