sad-mcp 2.2.6 → 2.2.7

package/dist/usecase/validate.js

@@ -17,6 +17,26 @@ const SEND_ONLY_PATTERNS = [
     /^התראה\s/,
     /^הפצת\s/,
 ];
+// Forbidden UC archetypes — always wrong regardless of system domain.
+// Each entry carries the human-readable fix hint surfaced in the error message.
+const FORBIDDEN_UCS = [
+    {
+        rx: /^(login|log[\s-]?in|sign[\s-]?in|logon|log[\s-]?on|authenticate|authentication)\b/i,
+        hint: "Authentication is a precondition, not a UC. Add as a precondition on every UC that requires it.",
+    },
+    {
+        rx: /^(logout|log[\s-]?out|sign[\s-]?out|logoff|log[\s-]?off)\b/i,
+        hint: "Logout is a session-management detail, not a user goal. Omit it.",
+    },
+    {
+        rx: /^(התחברות|כניסה\s+ל|כניסה\s+אל|אימות\s+משתמש)/i,
+        hint: "התחברות היא תנאי מוקדם, לא מקרה שימוש. הוסף כ-precondition לכל מקרה שימוש הדורש זאת.",
+    },
+    {
+        rx: /^(יציאה\s+מ|יציאה\s+מה)/i,
+        hint: "יציאה מהמערכת אינה מקרה שימוש — השמט.",
+    },
+];
 // Physical verbs that describe actions outside the IS. Allowed only when
 // wrapped by a system verb (רישום / הזנה / עדכון / סימון / Record / Enter / ...).
 const PHYSICAL_VERBS = [
@@ -106,6 +126,10 @@ export function validateModel(model) {
         if (!uc.name)
             err("uc-missing-name", path, "useCase is missing a name.");
         if (uc.name && typeof uc.name === "string") {
+            const forbidden = FORBIDDEN_UCS.find(({ rx }) => rx.test(uc.name));
+            if (forbidden) {
+                err("forbidden-uc", `${path}.name`, `UC "${uc.name}" is a forbidden archetype. ${forbidden.hint}`);
+            }
             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.`);
             }

package/package.json

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

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

@@ -32,6 +32,11 @@ The shared files prepended to this prompt define the layout recipes, model shape
 9. **Every system-time / cron actor association MUST carry a timing label** (e.g., "פעם ביום", "כל 5 דקות"). See §2 and §8 for rendering.
 10. **No "send-only" use cases.** If a UC's entire behavior is sending a message / notification / alert / email / SMS, it is not a UC — it is a step inside the UC that *decided* to send it. See §3.
 11. **All narrative UC documentation must be in Hebrew.** Description, preconditions, postconditions, every scenario flow-step text and extension text, user stories (`role` / `want` / `so` fields), assumptions, and open questions must all be written in Hebrew. User stories are rendered as "בתור [role], אני רוצה [want], כדי ש[so]" — write the field values in Hebrew accordingly. Identifier strings (`id`, `primaryActor: 'customer'`) stay ASCII. The validator (§12) rejects narrative fields that contain zero Hebrew characters.
+12. **Forbidden UC archetypes — never draw these, ever:**
+   - **Login / authentication** (`Login`, `Sign in`, `Authenticate`, `התחברות`, `כניסה למערכת`, `אימות משתמש`): Authentication is a precondition, not a user goal. Add it as a precondition on every UC that requires it; do not model it as a UC.
+   - **Logout** (`Logout`, `Sign out`, `יציאה מהמערכת`): Session termination is a system-infrastructure detail, not a user goal. Omit entirely.
+   - **Send mail / send notification** — already covered by CR #10, repeated here for emphasis. `שליחת דוא"ל`, `שליחת SMS`, `שליחת התראה`, `Send email`, `Send notification` are never UCs. These are steps inside the UC that decided to send.
+   The validator (§12) raises an ERROR on any of the above.
 
 ---
 
@@ -80,7 +85,7 @@ The shared files prepended to this prompt define the layout recipes, model shape
 
 **Implied UCs**: every entity the system references needs at least one UC that manages it.
 
-**No "send-only" use cases.** A UC must carry non-trivial behavior (decision, data entry, state change, non-trivial computation). If the only behavior is firing a message, it is not a UC — it is a system step inside the UC that *decided* to send.
+**No login, logout, or send-only use cases.** Login and logout are infrastructure details — never model them as UCs; add authentication as a precondition where needed. A UC must also carry non-trivial behavior (decision, data entry, state change, non-trivial computation). If the only behavior is firing a message, it is not a UC — it is a system step inside the UC that *decided* to send.
 
 - ❌ Wrong UCs: `שליחת התראה`, `שליחת מייל אישור`, `שליחת SMS`, `הודעה למנהל`, `שליחת דוח`.
 - ✅ Fold into the decider: the alert send-step belongs inside `עדכון רמות מלאי` (which *detected* the low stock); the confirmation email belongs inside `אישור הזמנה` (which *decided* to confirm).
@@ -889,6 +894,7 @@ uml_usecase_validate_model(model_json = JSON.stringify(diagramModel))
 The validator runs locally (no API cost) and catches what the §4 and CR gates cannot enforce from prose:
 - Include target with an actor association (CR #4) → ERROR
 - Single-incoming «include» (CR #4) → ERROR
+- Forbidden UC archetypes: login/authenticate, logout, send-mail/notification (CR #10, CR #12) → ERROR
 - Send-only UC names like `Print Shipping Label` / `שליחת X` (CR #10) → ERROR
 - Physical-verb UC names (`Perform X`, `ביצוע X`) not wrapped with a system verb (CR #8) → WARNING
 - Primary actor missing, unknown, or not connected as initiator (§4.1/§4.4) → ERROR

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

@@ -0,0 +1,944 @@
+---
+name: uml-use-case-diagram
+description: >
+  Create UML use case diagrams as interactive HTML files.
+  Trigger when the user asks to draw, create, or generate a use case diagram,
+  system use case model, actor-use case diagram, or functional requirements
+  diagram — including "show me the use cases", "model the system interactions",
+  or when extracting a use case model from a document (exam, spec, requirements).
+---
+
+# UML Use Case Diagram Skill
+
+> **שפת תקשורת:** כל ההסברים, השאלות, והתגובות בשיחה יהיו בעברית. קבצי HTML נוצרים עם תוויות בעברית. English is used only inside code comments and technical identifiers.
+
+> **Canonical authority:** The notation rules in `NOTATION.md` (sibling file) are the ground truth. If any rule below conflicts with `NOTATION.md`, `NOTATION.md` wins.
+
+Produce a single self-contained interactive HTML file with an embedded SVG use case diagram.
+The shared files prepended to this prompt define the layout recipes, model shape, and export button you must use.
+
+---
+
+## CRITICAL RULES — Check Before Every Output
+
+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» 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: 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.
+8. **UC labels describe actions WITH the information system, not physical real-world actions.** See §3 for the full rule and verb list.
+9. **Every system-time / cron actor association MUST carry a timing label** (e.g., "פעם ביום", "כל 5 דקות"). See §2 and §8 for rendering.
+10. **No "send-only" use cases.** If a UC's entire behavior is sending a message / notification / alert / email / SMS, it is not a UC — it is a step inside the UC that *decided* to send it. See §3.
+11. **All narrative UC documentation must be in Hebrew.** Description, preconditions, postconditions, every scenario flow-step text and extension text, user stories (`role` / `want` / `so` fields), assumptions, and open questions must all be written in Hebrew. User stories are rendered as "בתור [role], אני רוצה [want], כדי ש[so]" — write the field values in Hebrew accordingly. Identifier strings (`id`, `primaryActor: 'customer'`) stay ASCII. The validator (§12) rejects narrative fields that contain zero Hebrew characters.
+12. **Forbidden UC archetypes — never draw these, ever:**
+   - **Login / authentication** (`Login`, `Sign in`, `Authenticate`, `התחברות`, `כניסה למערכת`, `אימות משתמש`): Authentication is a precondition, not a user goal. Add it as a precondition on every UC that requires it; do not model it as a UC.
+   - **Logout** (`Logout`, `Sign out`, `יציאה מהמערכת`): Session termination is a system-infrastructure detail, not a user goal. Omit entirely.
+   - **Send mail / send notification** — already covered by CR #10, repeated here for emphasis. `שליחת דוא"ל`, `שליחת SMS`, `שליחת התראה`, `Send email`, `Send notification` are never UCs. These are steps inside the UC that decided to send.
+   The validator (§12) raises an ERROR on any of the above.
+
+---
+
+## 1. Gather Requirements
+
+| Item | Notes |
+|---|---|
+| **System name/boundary** | Names the rectangle |
+| **Human actors** (roles) | External humans who interact with the system |
+| **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 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. 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** — 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).
+
+**System-time / cron actor (שחקן זמן).** Draw as a system-style actor (amber head, `«system»` label). Every association line from a time actor MUST carry a visible timing label at the midpoint (e.g., `פעם ביום`, `כל 5 דקות`, `בסוף חודש`). Without a timing label the trigger frequency is ambiguous and the diagram is incomplete. Rendering: the label is injected as a `<g class="timing-label">` (white `<rect>` + `<text>`) after `fixLayout` sets the endpoint coordinates — see §8.
+
+---
+
+## 3. Use Case Rules
+
+**Granularity**: one complete user goal per UC, achievable in one session.
+
+**Labels describe actions WITH the information system, not physical real-world actions.** A use case is the actor's interaction with the IS; the verb must imply data entry, query, or a system-state change.
+
+- ✅ Preferred verbs: `רישום`, `הזנה`, `עדכון`, `הצגה`, `הפקה` (of a report), `שליחה` (of a notification), `אישור`, `הקצאה`, `חיפוש`, `סגירה`, `פתיחה` (of a record).
+- ❌ Bare physical verbs that describe things happening outside the system: `הכנת משלוח` (physical preparing), `ספירת מלאי` (physical counting), `מסירת חבילה` (physical delivering), `תשלום במזומן` (physical paying).
+- **Fix rule:** when the requirement uses a physical verb, wrap it with a system verb. `הכנת משלוח` → `רישום הכנת משלוח` or `סימון משלוח כמוכן`. `ביצוע ספירת מלאי` → `הזנת תוצאות ספירת מלאי`. `קבלת משלוח` → `קליטת משלוח נכנס` (data entry on arrival).
+
+**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).
+
+**Implied UCs**: every entity the system references needs at least one UC that manages it.
+
+**No "send-only" use cases.** A UC must carry non-trivial behavior (decision, data entry, state change, non-trivial computation). If the only behavior is firing a message, it is not a UC — it is a system step inside the UC that *decided* to send.
+
+- ❌ Wrong UCs: `שליחת התראה`, `שליחת מייל אישור`, `שליחת SMS`, `הודעה למנהל`, `שליחת דוח`.
+- ✅ Fold into the decider: the alert send-step belongs inside `עדכון רמות מלאי` (which *detected* the low stock); the confirmation email belongs inside `אישור הזמנה` (which *decided* to confirm).
+- This rule applies even when the send is triggered by a condition — conditional sending is part of the conditional UC, not its own UC.
+
+---
+
+## 4. Relationship Gates — Mandatory Justifications
+
+Every relationship in the diagram — actor-UC associations, «include», and «extend» — must pass a written justification block BEFORE it is drawn. **If you cannot fill the block in truthfully, the relationship does not exist.** Write these blocks in your planning text (not in the final HTML).
+
+### 4.1 Association justification (actor ↔ UC)
+
+```
+Association: [actor id] ↔ [UC id]
+  Actor role:            initiator / participant / recipient / supplier
+  Does this actor TRIGGER / INITIATE the UC?   yes / no
+  One-line justification: "The actor ___ in order to ___"
+  Description shown on click (Hebrew): ___________________
+
+  → If the actor has no meaningful interaction with the UC → DELETE the association.
+  → Every UC MUST have ≥1 association where "initiates = yes". A UC with no initiator is orphaned — fix it or delete the UC.
+  → A human actor connected only as "recipient" of a notification is usually wrong — the initiator of the notification-sending UC is who you want (see CRITICAL RULE #10, no send-only UCs).
+```
+
+The "Description shown on click" is the text surfaced in the HTML by the `showAssocDesc` popup — see §8. Store it on the connection object under `description`.
+
+### 4.2 «include» justification
+
+**Default to zero.** Treat every «include» as guilty until proven innocent.
+
+```
+«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`.
+
+### 4.3 «extend» justification
+
+```
+«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».
+```
+
+Arrow: dashed, open arrowhead, `Extension UC → Base UC`. Use at most once or twice per diagram.
+
+### 4.4 UC documentation block (mandatory)
+
+**Every UC on the diagram also carries full Visual Paradigm-style documentation.** This is not justification text — it is the data that populates `useCaseDocs[id]` (see §9) and is rendered inside the per-UC modal (see §8). Write one block per UC in your planning before emitting the HTML.
+
+```
+UC documentation: [uc-id]
+  name:            _______
+  primaryActor:    _______   (must be an actor connected to this UC with role: 'initiator' per §4.1)
+  secondaryActors: [...]     (actors with role: 'participant' / 'recipient' / 'supplier')
+  description:     one-sentence summary of what the UC does
+
+  preconditions:
+    - ___________________
+    - ___________________
+  postconditions:
+    - ___________________
+
+  scenarios:
+    - id: sc-happy, name: "מסלול מרכזי"
+      flow:
+        Write 5–10 concrete steps. Actor steps name specific data entered or a specific
+        action taken — never "ממלא טופס" or "שולח בקשה" alone. System steps name the
+        specific validation performed, state change made, or feedback shown — never
+        "מעבד את הבקשה" alone. Each step must be one observable action; split
+        compound actions into separate steps.
+        Examples of sufficient granularity:
+          [actor] מזין מספר סטודנט, שם פרטי, שם משפחה וכתובת דוא"ל
+          [system] מוודא כי מספר הסטודנט אינו קיים במערכת
+          [system] שומר את הרשומה עם סטטוס "ממתין לאישור" ומציג הודעת אישור
+        1. [actor:primaryActor] ___________________
+        2. [system] ___________________
+        3. [include:uc-xxx]    ___________________    (only if §4.2 gate passed)
+        4. [actor:secondary]   ___________________
+      extensions:                                     (error/exception handling — one per step where failure is realistic)
+        2a. אם ___________ — המערכת ___________ (e.g. wrong input, not found, timeout)
+        4a. אם ___________ — המערכת ___________
+
+    Additional scenarios — add one when the SAME GOAL is achieved via a meaningfully different PATH or TRIGGER.
+    Rule: same "what", different "how" or different starting condition → new scenario.
+    Examples: "רישום רגיל" vs "רישום מאוחר עם קנס"; "תשלום בכרטיס" vs "תשלום בקופון".
+    Do NOT add a scenario just for a different error outcome — that belongs in extensions of the main scenario.
+
+    - id: sc-alt-1, name: "מסלול חלופי: ___"
+      flow: ...
+      extensions: ...
+
+  userStories:   (as many as the UC warrants — one per distinct stakeholder need; not a fixed number)
+    - בתור [תפקיד], אני רוצה [מה], כדי ש[למה].
+    - בתור [תפקיד שונה או אותו תפקיד עם מטרה שונה], אני רוצה [...], כדי ש[...].
+    - ... (keep adding until every user-facing goal tied to this UC is represented)
+
+  wireframe?:  (optional — only where the UC benefits from a UI mock; see §WF)
+```
+
+**Gates enforced before publishing:**
+- Exactly one `primaryActor`; the actor exists in `actors[]` AND an association exists with `role: 'initiator'` on this UC (§4.1).
+- At least one scenario with at least one flow step.
+- Every `[actor:id]` in a flow step references a real actor id.
+- Every `[include:id]` in a flow step references a real UC id AND corresponds to an `«include»` relationship that passed §4.2.
+- Every `Na` extension references a valid step number `N` in the same scenario's flow.
+- As many user stories as the UC warrants (minimum one) — cover every distinct user goal / role / scenario that motivates the UC. Do not stop at one.
+
+### 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
+
+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 to 2 lines.
+
+### Ellipse endpoint calculation (mandatory)
+Never draw a line to the ellipse center — it disappears under the fill. Compute the boundary intersection:
+
+```javascript
+// 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) };
+```
+
+### SVG draw order
+1. Background + dot grid
+2. System boundary rectangle
+3. Association lines (solid)
+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.
+
+### «include» / «extend» arrow template
+
+Define markers once in `<defs>` using `<polyline>` (NOT `<polygon>` — polygon closes the triangle, producing a double-headed appearance):
+
+```svg
+<defs>
+  <marker id="arrow-include" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+    <polyline points="0 0, 9 3.5, 0 7" fill="none" stroke="#7c3aed" stroke-width="1.2"/>
+  </marker>
+  <marker id="arrow-extend" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+    <polyline points="0 0, 9 3.5, 0 7" fill="none" stroke="#7c3aed" stroke-width="1.2"/>
+  </marker>
+</defs>
+```
+
+For each «include»/«extend» line, add a `<text>` with `data-label-for="{from-id} {to-id}"` — `fixLayout` reads this and repositions the label to the line midpoint automatically:
+
+```svg
+<line data-conn-from="uc-a" data-conn-to="uc-b"
+      x1="0" y1="0" x2="0" y2="0"
+      stroke="#7c3aed" stroke-width="1.6" stroke-dasharray="6 4"
+      marker-end="url(#arrow-include)"/>
+<text data-label-for="uc-a uc-b" x="0" y="0"
+      text-anchor="middle" font-size="9.5" fill="#7c3aed"
+      font-family="'IBM Plex Mono',monospace">«include»</text>
+```
+
+**Never write `«include target»` or any annotation inside a UC ellipse group.**
+
+---
+
+## 6. Layout
+
+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.
+
+### Data structure
+
+```javascript
+const diagramLayout = {
+  svgId: 'diagram-svg',
+  boundary: { x: 180, y: 60, width: 640, height: 700 },
+  actors: [
+    { id: 'a1', label: 'מטופל', side: 'left',  x: 80,  y: 300, ucIds: ['uc1','uc2','uc3'] },
+    { id: 'a2', label: 'מנהל',  side: 'right', x: 900, y: 350, ucIds: ['uc4','uc5'] }
+  ],
+  useCases: [
+    { id: 'uc1', cx: 320, cy: 200, rx: 90, ry: 28 },
+    { id: 'uc2', cx: 320, cy: 300, rx: 90, ry: 28 }
+    // ... all UCs
+  ],
+  connections: [
+    { from: 'a1',  to: 'uc1', type: 'association' },
+    { from: 'uc1', to: 'uc6', type: 'include' }
+    // ... all connections
+  ]
+};
+```
+
+### SVG element conventions (required)
+
+- 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>`.
+
+### 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
+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 b = layout.boundary;
+
+  // Step 1 — Group UCs by the side of their owning actor.
+  const ucSide = {};
+  layout.actors.forEach(a =>
+    a.ucIds.forEach(uid => {
+      ucSide[uid] = ucSide[uid] && ucSide[uid] !== a.side ? 'center' : a.side;
+    })
+  );
+  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).
+  function sortCol(ucs, side) {
+    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(bb.id));
+      return (ai < 0 ? 999 : ai) - (bi < 0 ? 999 : bi);
+    });
+  }
+  sortCol(cols.left,  'left');
+  sortCol(cols.right, 'right');
+
+  // Step 3 — Adaptive column X positions. Account for actual ellipse widths so
+  // adjacent columns never overlap horizontally. Widen the boundary if needed.
+  const COL_GAP = 30;
+  const maxRx = ucs => (ucs.length ? Math.max(...ucs.map(u => u.rx)) : 0);
+  const lRx = maxRx(cols.left), cRx = maxRx(cols.center), rRx = maxRx(cols.right);
+  const gaps =
+    (cRx ? 2 * COL_GAP : (lRx && rRx ? 2 * COL_GAP : 0));
+  const needed = 2 * UC_PAD + 2 * lRx + 2 * cRx + 2 * rRx + gaps;
+  if (b.width < needed) b.width = needed;
+
+  const leftX   = b.x + UC_PAD + lRx;
+  const rightX  = b.x + b.width - UC_PAD - rRx;
+  const centerX = (leftX + rightX) / 2;
+
+  function place(ucs, colX, colName) {
+    ucs.forEach((uc, i) => {
+      uc.cy = b.y + HEADER_H + UC_PAD + uc.ry + i * (uc.ry * 2 + UC_GAP);
+      uc.cx = colX;
+      uc.col = colName;
+    });
+  }
+  place(cols.left,   leftX,   'left');
+  place(cols.right,  rightX,  'right');
+  place(cols.center, centerX, 'center');
+
+  // 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 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 (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 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;
+    const el = g.querySelector('ellipse');
+    if (!el) return;
+    const dx = uc.cx - parseFloat(el.getAttribute('cx'));
+    const dy = uc.cy - parseFloat(el.getAttribute('cy'));
+    el.setAttribute('cx', uc.cx);
+    el.setAttribute('cy', uc.cy);
+    g.querySelectorAll('text').forEach(t => {
+      t.setAttribute('x', parseFloat(t.getAttribute('x') || 0) + dx);
+      t.setAttribute('y', parseFloat(t.getAttribute('y') || 0) + dy);
+    });
+    g.removeAttribute('transform');
+  });
+  layout.actors.forEach(actor => {
+    const g = document.getElementById('actor-group-' + actor.id);
+    if (g) g.setAttribute('transform', `translate(${actor.x},${actor.y})`);
+  });
+
+  // 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');
+    const fUC = layout.useCases.find(u => u.id === fId);
+    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;
+    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);
+  });
+
+  // Step 9 — Resize boundary rect and SVG viewBox (BOTH width and height).
+  const br = svg.querySelector('.system-boundary, rect[rx="12"]');
+  if (br) { br.setAttribute('width', b.width); br.setAttribute('height', b.height); }
+  const vb = svg.getAttribute('viewBox');
+  if (vb) {
+    const p = vb.split(/\s+/);
+    // Height: fit boundary + any bottom actors.
+    p[3] = Math.max(parseFloat(p[3]), b.y + b.height + 120);
+    // Width: fit the rightmost actor + label margin. Without this, widening the
+    // boundary pushes right-column actors off the visible SVG.
+    const ACTOR_LABEL_MARGIN = 120;  // covers stick figure width + longest label
+    const maxActorX = layout.actors.length
+      ? Math.max(...layout.actors.map(a => a.x))
+      : b.x + b.width;
+    p[2] = Math.max(parseFloat(p[2]), maxActorX + ACTOR_LABEL_MARGIN);
+    svg.setAttribute('viewBox', p.join(' '));
+  }
+
+  // Step 10 — Decorate timed associations (see §8 renderTimingLabels).
+  if (typeof renderTimingLabels === 'function') renderTimingLabels(layout);
+}
+```
+
+### Fix Layout button
+
+```html
+<div style="text-align:center; margin:8px 0;">
+  <button onclick="fixLayout(diagramLayout)" class="fix-btn">Fix Layout</button>
+</div>
+```
+
+---
+
+## 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 — Modal for UCs, Popups for Actors & Associations
+
+v2 splits the click experience in two:
+
+- **UCs → full-screen modal** showing the complete §4.4 documentation (id, name, primary actor, description, scenarios with flow-of-events, pre/post-conditions, user stories, optional wireframe). See §8a.
+- **Actors and association lines → small floating popup** (single-line name + description), unchanged from v1.1.8. See §8b.
+
+One entry point — `showDesc(id, type, event)` — routes to the right UI:
+
+```javascript
+function showDesc(id, type, event) {
+  if (type === 'uc') { openUcModal(id); event.stopPropagation(); return; }
+  // Non-UC types use the small popup (§8b)
+  showPopup(id, type, event);
+}
+```
+
+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 = {
+  'customer': { name: 'לקוח', desc: 'לקוח הרשום במערכת. יוזם הזמנות ועוקב אחר סטטוס.' },
+  // ... one entry per actor
+};
+const assocDescriptions = {
+  // keyed by connection id; name = actor-name ↔ UC-name
+  'a1': { name: 'לקוח ↔ פתיחת הזמנה', desc: 'הלקוח יוזם את פתיחת ההזמנה. תפקיד: Initiator.' },
+  // ... one entry per association line you want described
+};
+```
+
+### 8a. useCaseDocs data object (inline in the HTML `<script>` block)
+
+`openUcModal(id)` reads `useCaseDocs[id]` and renders a full-screen modal with
+the complete UC spec. Populate one entry per UC:
+
+```javascript
+const useCaseDocs = {
+  'uc-place-order': {
+    id: 'uc-place-order',
+    name: 'פתיחת הזמנה',
+    primaryActor: 'customer',
+    secondaryActors: ['inventory'],
+    description: 'הלקוח פותח הזמנה חדשה ומציין פריטים.',
+    preconditions:  ['הלקוח מחובר למערכת.'],
+    postconditions: ['ההזמנה נשמרה עם סטטוס "ממתינה".'],
+    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: 'מאשר את ההזמנה' }
+        ],
+        extensions: [
+          { at: 1, text: 'אם הפריט אזל במלאי — מציג הודעה וחוזר לשלב 1.' }
+        ]
+      }
+    ],
+    userStories: [
+      { role: 'לקוח', want: 'להזמין מוצר במהירות', so: 'שאקבל אותו תוך 48 שעות' }
+    ],    // rendered as: "בתור לקוח, אני רוצה להזמין מוצר במהירות, כדי ששאקבל אותו תוך 48 שעות"
+    wireframe: ''   // optional per §WF
+  }
+  // ... one entry per UC
+};
+```
+
+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">`
+
+### Clickable association lines (required)
+
+A 1.8px line is nearly impossible to click. Every associatable line gets **two** line elements: a visible thin line (the one `fixLayout` already updates via `data-conn-from` / `data-conn-to`) and a transparent thick hitbox on top.
+
+```html
+<!-- Visible line — fixLayout writes x1/y1/x2/y2 here -->
+<line data-conn-from="worker" data-conn-to="uc-receive"
+      x1="0" y1="0" x2="0" y2="0"
+      stroke="#334155" stroke-width="1.8"/>
+
+<!-- Click hitbox — invisible, tracks the same endpoints, carries the id -->
+<line class="conn-hitbox" data-conn-id="a1"
+      data-hitbox-from="worker" data-hitbox-to="uc-receive"
+      x1="0" y1="0" x2="0" y2="0"
+      stroke="transparent" stroke-width="14"
+      style="cursor:pointer"
+      onclick="showDesc('a1','assoc',event)"/>
+```
+
+Inside `fixLayout` Step 8, copy the endpoints from each visible line to its matching hitbox so the clickable region tracks the visible line exactly:
+
+```javascript
+// After writing x1/y1/x2/y2 on the visible line:
+const hitbox = svg.querySelector(
+  `.conn-hitbox[data-hitbox-from="${fId}"][data-hitbox-to="${tId}"]`);
+if (hitbox) {
+  hitbox.setAttribute('x1', x1); hitbox.setAttribute('y1', y1);
+  hitbox.setAttribute('x2', x2); hitbox.setAttribute('y2', y2);
+}
+```
+
+Draw order: visible line first, hitbox second, ellipses/actors last. The hitbox stays under the ellipses and actors but above the thin visible line so clicks on or near the line hit it.
+
+Associations without a meaningful description (e.g., auto-generated from trivially obvious actor-UC pairs) may omit the hitbox and the `assocDescriptions` entry, but they still need to pass the §4.1 justification gate.
+
+### Timing labels on cron/time-actor associations (required)
+
+`renderTimingLabels(layout)` is provided by `uc-diagram-common.js` — do not inline it.
+It is called automatically at the end of every `fixLayout` invocation.
+
+Every connection from a system-time actor MUST carry a `timing` field:
+
+```javascript
+{ from: 'cron', to: 'uc-daily-reconcile', type: 'association', timing: 'פעם ביום' }
+```
+
+---
+
+## §WF. Wireframe Authoring (Opt-In)
+
+**Wireframes are generated only when the user explicitly requests them** (e.g., "add wireframes", "include UI mocks"). Do not generate wireframes unless asked — they significantly increase generation time.
+
+When wireframes are requested, generate them only for UCs whose `primaryActor.actorType === 'human'`. Skip wireframes for:
+- UCs whose primary actor is a system or cron (`actorType: 'system'`) — no human sees a screen.
+- Pure include-target UCs (sub-behaviors with no actor association).
+
+When generated, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
+
+Claude authors the wireframe using its own UI-generation judgment — there is no DSL. But the skill enforces a consistent look and safe sandbox via a scoped CSS theme and a set of forbidden patterns.
+
+### Root element
+
+```html
+<div class="wf-screen">
+  <!-- optional header -->
+  <h3 class="wf-heading">כותרת המסך</h3>
+
+  <!-- form rows -->
+  <div class="wf-row">
+    <label class="wf-label">שם משתמש</label>
+    <input class="wf-input" disabled placeholder="" />
+  </div>
+  <div class="wf-row">
+    <label class="wf-label">סיסמה</label>
+    <input class="wf-input" disabled placeholder="" />
+  </div>
+
+  <!-- a table mock -->
+  <table class="wf-table">
+    <thead><tr><th>פריט</th><th>כמות</th><th>מחיר</th></tr></thead>
+    <tbody>
+      <tr><td>...</td><td>...</td><td>...</td></tr>
+    </tbody>
+  </table>
+
+  <!-- an image placeholder -->
+  <div class="wf-image-box">[לוגו / תמונה]</div>
+
+  <!-- buttons are inert visual placeholders only -->
+  <div class="wf-actions">
+    <button class="wf-button wf-primary">אישור</button>
+    <button class="wf-button">ביטול</button>
+  </div>
+
+  <!-- free-text hints / callouts -->
+  <p class="wf-hint">לחיצה על "אישור" שולחת את הטופס ועוברת למסך הסיכום.</p>
+</div>
+```
+
+### Allowed CSS classes
+
+Use only `wf-*` classes. The skill ships a scoped theme (§10) covering: `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`.
+
+### Hard forbidden patterns
+
+The `wireframeSafe()` regex rejects any of the following. A failing wireframe renders a placeholder and logs a warning — it is NEVER injected.
+
+| Forbidden | Why |
+|---|---|
+| `<script>` | Can execute arbitrary JS in the host page. |
+| `on*=` attributes (`onclick`, `onerror`, …) | Same. |
+| `<iframe>` | Can load arbitrary content. |
+| `src="http…"` / `href="http…"` | No external fetches — the HTML must remain self-contained. |
+| `@import` | Same reason. |
+| `<style>` block inside the wireframe | Styles come from the skill's `.wf-*` theme only, to keep wireframes visually consistent across UCs. |
+
+### Size and scope
+
+- Keep each wireframe under ~200 lines of HTML. If the UC really needs more, split by scenario with `<h3 class="wf-heading">` dividers inside one `.wf-screen`.
+- Wireframes are static visual mocks. Form fields use `disabled` so the cursor shows they are illustrative.
+- Buttons are not wired to anything — `onclick` is forbidden. They communicate affordance, not behavior.
+- **Visible text is Hebrew (CR #11).** Every heading, label, button, table header, and hint the user sees must be in Hebrew — the product is Hebrew. Class names (`wf-*`) and identifiers stay ASCII. RTL is inherited from `<body dir="rtl">`; do not override `direction`. The validator rejects a wireframe containing zero Hebrew characters (`wireframe-non-hebrew` error).
+
+### When NOT to include a wireframe
+
+- Primary actor is a system / cron (`actorType: 'system'`) — e.g., a back-end reconciliation triggered by the clock.
+- The UC is purely an `«include»` target (a sub-behavior, not a user-visible goal).
+
+**"The UI is trivial" is not a valid reason to skip.** A single approval prompt still deserves a mock — it shows the reader what the button says, what data is visible on the screen, and what confirmation text appears. If you genuinely cannot author the wireframe because the spec is silent, record the gap in `diagramModel.openQuestions` AND still emit a placeholder wireframe with the questions visible inside it.
+
+---
+
+## 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 Visual Paradigm exporter walks this variable.
+
+**v2 note:** each `kind: 'useCase'` element now carries the full documentation (`primaryActor`, `preconditions`, `postconditions`, `scenarios`, `userStories`, optional `wireframe`). `useCaseDocs` in §8a is the in-HTML runtime index keyed by UC id — it can be derived from `diagramModel.parts[*].elements.filter(e => e.kind === 'useCase')` during initialization, or emitted as a pre-built literal. Either way, each UC entry must satisfy the §4.4 gate.
+
+### Assumptions and open questions
+
+Both `diagramModel` and `diagramLayout` carry two parallel string arrays, matching the BPMN skill's shape:
+
+```javascript
+{
+  // ...
+  assumptions:   [ 'המערכת מזהה כל עובד מחסן דרך מזהה משתמש יחיד.',
+                   'ייבוא נתונים מה-ERP של הספק מתבצע באמצעות API ולא קובץ.' ],
+  openQuestions: [ 'האם נדרש אישור נוסף על ידי מנהל לכל שינוי רמות מלאי?' ]
+}
+```
+
+Render them in a panel at the bottom of the page — see §11. Only render if at least one of the arrays is non-empty. Do NOT hide the panel; a reader reviewing the diagram needs to see which statements in the diagram rest on assumptions.
+
+---
+
+## 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), human head fill #e0f0ff, system head fill #fef3c7
+Actor label:        #1e293b, 11px, weight 600, text-anchor middle
+
+Actor SVG template — EXACT coordinates, do not deviate (fixLayout centers on the group origin):
+  <circle cx="0" cy="-60" r="14" fill="#e0f0ff" stroke="#334155" stroke-width="2"/>
+  <line x1="0" y1="-46" x2="0" y2="-10" stroke="#334155" stroke-width="2"/>
+  <line x1="-18" y1="-36" x2="18" y2="-36" stroke="#334155" stroke-width="2"/>
+  <line x1="0" y1="-10" x2="-14" y2="14" stroke="#334155" stroke-width="2"/>
+  <line x1="0" y1="-10" x2="14" y2="14" stroke="#334155" stroke-width="2"/>
+  <text x="0" y="30" text-anchor="middle" font-size="11" font-weight="600" fill="#1e293b"
+        font-family="'Noto Sans Hebrew',sans-serif">[Actor label]</text>
+  (For system actors: same but head fill #fef3c7, add «system» label at y="44" in IBM Plex Mono 9px #64748b)
+Association line:   #334155, 1.8px, no arrowhead
+Include/extend:     #7c3aed, 1.6px, dasharray 6 4, open arrowhead, label 9.5px
+Generalization:     #334155, 1.8px, hollow triangle (fill white)
+System title:       white on #1e40af, 14px bold
+Assumptions panel:  white bg, border #cbd5e1 (1px), rx=8, padding 16px, margin-top 20px
+Assumptions h3:     #1e40af, 13px, weight 600, margin-bottom 6px
+Assumptions li:     #334155, 12px, line-height 1.6, list-style disc inside
+Fonts:              'Noto Sans Hebrew' + 'IBM Plex Mono' from Google Fonts
+```
+
+All styles are in `https://themathbible.com/sad-mcp/uc-diagram-common.css` — **do not add a `<style>` block**. Do not inline any CSS.
+
+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`.
+
+---
+
+## 11. HTML File Structure
+
+```html
+<!DOCTYPE html>
+<html lang="he" dir="rtl">
+<head>
+  <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">
+  <link href="https://themathbible.com/sad-mcp/uc-diagram-common.css" rel="stylesheet">
+  <!-- REQUIRED: uc-diagram-common.css sets display:flex on .diagram-part, which overrides
+       the browser's [hidden]{display:none}. This one-liner restores correct tab switching. -->
+  <style>[hidden] { display: none !important; }</style>
+</head>
+<body>
+  <!-- Tab bar (only when split) -->
+  <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 -->
+  <div style="text-align:center;margin:8px 0;">
+    <button onclick="fixLayout(currentLayout())" class="fix-btn">Fix Layout</button>
+  </div>
+
+  <!-- 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>
+
+  <!-- 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>
+    </div>
+    <div class="assumptions-col" id="open-questions-col">
+      <h3>שאלות פתוחות</h3><ul id="open-questions-list"></ul>
+    </div>
+  </div>
+
+  <!-- User stories summary — populated automatically by renderUserStoriesSummary()
+       in common.js, which deduplicates across all UCs. Do not populate inline. -->
+  <div id="user-stories-panel" class="user-stories-panel" hidden>
+    <h3>סיפורי משתמש</h3>
+    <ul id="user-stories-list"></ul>
+  </div>
+
+  <!-- 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"></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.
+       Use var (NOT const/let) so these become window properties accessible from the external script.
+       Do NOT add activeTab, currentLayout, showDiagram, exportXMI, xmlEscape, downloadFile,
+       or any DOMContentLoaded handler here — they all live in uc-diagram-common.js.
+       Adding let/const variables with the same names as any variable in the external script
+       causes a SyntaxError that silently kills the entire external script. -->
+  <script>
+    var diagramLayouts      = [ /* one layout object per tab, per §6 */ ];
+    var actorDescriptions   = { /* §8b — one entry per actor */ };
+    var assocDescriptions   = { /* §8b — one entry per association line */ };
+    var useCaseDocs         = { /* §8a — full per-UC documentation */ };
+    var diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
+  </script>
+  <script src="https://themathbible.com/sad-mcp/uc-diagram-common.js"></script>
+</body>
+</html>
+```
+
+**Single-tab diagrams still define the full script.** Always emit all five `var` data globals; the tab bar HTML and second `.diagram-part` are the only things conditional on splitting. `showDiagram`, `currentLayout`, `activeTab`, `fixLayout`, `exportXMI` and all other functions live exclusively in `uc-diagram-common.js` — never re-declare them inline.
+
+---
+
+## 12. Output
+
+**Mandatory validator step — call before writing the HTML.**
+
+After assembling `diagramModel` and before generating any HTML, serialize it to JSON and call the MCP tool `uml_usecase_validate_model`:
+
+```
+uml_usecase_validate_model(model_json = JSON.stringify(diagramModel))
+```
+
+The validator runs locally (no API cost) and catches what the §4 and CR gates cannot enforce from prose:
+- Include target with an actor association (CR #4) → ERROR
+- Single-incoming «include» (CR #4) → ERROR
+- Send-only UC names like `Print Shipping Label` / `שליחת X` (CR #10) → ERROR
+- Physical-verb UC names (`Perform X`, `ביצוע X`) not wrapped with a system verb (CR #8) → WARNING
+- Primary actor missing, unknown, or not connected as initiator (§4.1/§4.4) → ERROR
+- Flow step references to unknown actor/UC ids, or `«include»` steps without a matching `include` relationship → ERROR
+- 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, 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`.**
+
+After the validator passes, save the HTML as `[system_name]_use_case_diagram.html`.
+Briefly report: actor count, use case count, include/extend count, whether split, and any warnings the validator surfaced.
+
+---
+
+## 13. Pre-Delivery Checklist
+
+- [ ] `uml_usecase_validate_model` was called and returned `✓ Model valid` on the final model (§12). Warnings may remain but every ERROR is fixed.
+- [ ] All narrative UC documentation (description, preconditions, postconditions, flow-step text, extension text, user stories, assumptions, open questions) is in Hebrew (CR #11). Identifier strings remain ASCII.
+- [ ] User stories cover every distinct stakeholder goal behind the UC — not a single token story. If the UC serves multiple roles or scenarios, each gets its own story.
+- [ ] Every UC has a filled §4.4 documentation block AND a matching `useCaseDocs[id]` entry with `primaryActor`, ≥1 scenario, ≥1 flow step, `preconditions`, `postconditions`, and `userStories`.
+- [ ] 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.
+- [ ] Wireframes generated only if the user explicitly requested them (§WF). If generated, only for human-initiated UCs; system/cron and include-targets omitted.
+- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only; visible text is in Hebrew.
+- [ ] Every actor-UC association has a written §4.1 justification block (role, initiates? one-line "why"); every UC has ≥1 association with `initiates = yes`.
+- [ ] Every association line carries a transparent click-hitbox (stroke-width ≥12, `data-conn-id`) wired to `showDesc(id,'assoc',event)`; `assocDescriptions` entry exists for each id.
+- [ ] `assumptions` and `openQuestions` arrays are present in `diagramModel`; the HTML renders the bottom panel whenever either is non-empty.
+- [ ] `#user-stories-panel` / `#user-stories-list` elements are present in the HTML; `renderUserStoriesSummary()` (called automatically) will populate them with a deduplicated list of all user stories across all UCs. Do not manually populate this list.
+- [ ] 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).
+- [ ] Every UC label describes an action WITH the information system (data entry, query, state change) — no bare physical verbs (`הכנת X`, `ספירת X`, `מסירת X`, `תשלום במזומן`). Physical verbs are wrapped with a system verb (`רישום`, `הזנה`, `עדכון`, `סימון`, etc.).
+- [ ] Every system-time / cron actor association has a `timing` field (and the rendered diagram shows a visible label at the line midpoint) — no unlabeled cron connections.
+- [ ] No "send-only" UCs (no bare `שליחת X` / `הודעה ל-X`); message-sends are folded into the UC that decided to send.
+- [ ] `showDiagram(index)` is defined in every generated file, even single-tab diagrams (so tab switching is wired if splitting is ever added).
+- [ ] `fixLayout` uses adaptive column X (widens boundary if needed so left/center/right ellipses never overlap horizontally) AND expands viewBox width so right-side actors are not clipped.
+- [ ] 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()`.