sad-mcp 1.1.8 → 2.1.0

package/dist/tools.js

@@ -8,6 +8,7 @@ import { extractText, isExtractable } from "./text-extract.js";
 import { loadTextCache, saveTextEntry } from "./text-cache.js";
 import { trackToolCall } from "./tracking.js";
 import { renderBPMN, parseAndValidate, formatIssues, } from "./bpmn/index.js";
+import { parseAndValidate as ucParseAndValidate, formatIssues as ucFormatIssues, } from "./usecase/index.js";
 const __tools_filename = fileURLToPath(import.meta.url);
 const __tools_dirname = dirname(__tools_filename);
 const PKG = JSON.parse(readFileSync(join(__tools_dirname, "..", "package.json"), "utf-8"));
@@ -363,6 +364,20 @@ export function registerToolHandlers(server) {
                     properties: {},
                 },
             },
+            {
+                name: "uml_usecase_validate_model",
+                description: "Validate a use-case diagramModel JSON BEFORE generating the HTML file. Catches the §4/§4.4/CR violations the prompt cannot fully enforce: include target with actor association (CR #4), single-incoming include (CR #4), send-only UC names (CR #10), physical-verb names (CR #8), missing primary actor (§4.4), broken references in scenario flow steps, orphaned UCs, and unsafe wireframe HTML. Returns either 'Model valid' (optionally with warnings) or a list of specific errors to fix. Call iteratively — fix errors, call again — until valid. This check runs locally; no API cost.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        model_json: {
+                            type: "string",
+                            description: "The diagramModel JSON as a string (the same object assigned to `diagramModel` in the generated HTML). See skills/_shared/model-shape.md for the required shape.",
+                        },
+                    },
+                    required: ["model_json"],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -689,6 +704,27 @@ export function registerToolHandlers(server) {
             trackToolCall(name, toolArgs, { success: true, responseChars: text.length }, Date.now() - startTime);
             return { content: [{ type: "text", text }] };
         }
+        if (name === "uml_usecase_validate_model") {
+            const modelJson = args?.model_json;
+            if (typeof modelJson !== "string" || modelJson.trim() === "") {
+                const text = "Error: model_json is required and must be a JSON string.";
+                trackToolCall(name, toolArgs, { success: false, responseChars: text.length }, Date.now() - startTime);
+                return { content: [{ type: "text", text }] };
+            }
+            const vr = ucParseAndValidate(modelJson);
+            if (vr.ok) {
+                const warnPart = vr.warnings.length > 0
+                    ? `\n\nWarnings (non-blocking):\n${ucFormatIssues(vr.warnings)}`
+                    : "";
+                const text = `✓ Model valid.${warnPart}\n\nYou may proceed to generate the HTML file (see skills/uml-use-case-diagram/SKILL.md §11).`;
+                trackToolCall(name, toolArgs, { success: true, responseChars: text.length }, Date.now() - startTime);
+                return { content: [{ type: "text", text }] };
+            }
+            const allWarnings = vr.warnings.length > 0 ? `\n\nWarnings (non-blocking):\n${ucFormatIssues(vr.warnings)}` : "";
+            const text = `✗ Model invalid — fix the following errors and call uml_usecase_validate_model again:\n\n${ucFormatIssues(vr.issues)}${allWarnings}`;
+            trackToolCall(name, toolArgs, { success: false, responseChars: text.length }, Date.now() - startTime);
+            return { content: [{ type: "text", text }] };
+        }
         throw new Error(`Unknown tool: ${name}`);
     });
 }

package/dist/usecase/index.d.ts

@@ -0,0 +1,2 @@
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";
+export type { ValidateResult, ValidationIssue } from "./validate.js";

package/dist/usecase/index.js

@@ -0,0 +1 @@
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";

package/dist/usecase/validate.d.ts

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

package/dist/usecase/validate.js

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

package/package.json

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

package/skills/_shared/export-buttons.md

@@ -134,12 +134,63 @@ function xmiBody(elements, rels) {
 ```
 
 ### Use-case xmiBody
+
+v2 emits the rich per-UC documentation (preconditions, postconditions, flow of events) as nested UML elements so Visual Paradigm's Specification pane populates on import.
+
 ```javascript
 function xmiBody(elements, rels) {
   const lines = [];
+
+  // Helper: serialize scenarios to a numbered plain-text body for OpaqueBehavior.
+  function flowText(uc) {
+    const actorName = id => (elements.find(e => e.kind === 'actor' && e.id === id) || {}).name || id;
+    const ucName    = id => (elements.find(e => e.kind === 'useCase' && e.id === id) || {}).name || id;
+    const lines = [];
+    (uc.scenarios || []).forEach(sc => {
+      lines.push((sc.name || sc.id) + ':');
+      (sc.flow || []).forEach((step, i) => {
+        const n = i + 1;
+        if (step.kind === 'actor')     lines.push(`  ${n}. ${actorName(step.actor)}: ${step.text}`);
+        else if (step.kind === 'system')    lines.push(`  ${n}. System: ${step.text}`);
+        else if (step.kind === 'include')   lines.push(`  ${n}. «include» ${ucName(step.uc)}${step.text ? ' — ' + step.text : ''}`);
+        else if (step.kind === 'extension') lines.push(`  ${n}a. ${step.text}`);
+        (sc.extensions || []).filter(e => e.at === n).forEach((e, j) => {
+          const letter = String.fromCharCode(97 + j);
+          lines.push(`  ${n}${letter}. ${e.text}`);
+        });
+      });
+    });
+    return lines.join('\n');
+  }
+
   for (const el of elements) {
-    if (el.kind === 'useCase')
-      lines.push(`    <packagedElement xmi:type="uml:UseCase" xmi:id="${el.id}" name="${xmlEscape(el.name)}"/>`);
+    if (el.kind === 'useCase') {
+      const hasDocs = (el.preconditions && el.preconditions.length)
+                   || (el.postconditions && el.postconditions.length)
+                   || (el.scenarios && el.scenarios.length);
+      if (!hasDocs) {
+        lines.push(`    <packagedElement xmi:type="uml:UseCase" xmi:id="${el.id}" name="${xmlEscape(el.name)}"/>`);
+      } else {
+        lines.push(`    <packagedElement xmi:type="uml:UseCase" xmi:id="${el.id}" name="${xmlEscape(el.name)}">`);
+        (el.preconditions || []).forEach((p, i) => {
+          lines.push(`      <precondition xmi:type="uml:Constraint" xmi:id="${el.id}-pre-${i+1}" name="pre-${i+1}">`);
+          lines.push(`        <specification xmi:type="uml:OpaqueExpression" xmi:id="${el.id}-pre-${i+1}-s"><body>${xmlEscape(p)}</body></specification>`);
+          lines.push(`      </precondition>`);
+        });
+        (el.postconditions || []).forEach((p, i) => {
+          lines.push(`      <postcondition xmi:type="uml:Constraint" xmi:id="${el.id}-post-${i+1}" name="post-${i+1}">`);
+          lines.push(`        <specification xmi:type="uml:OpaqueExpression" xmi:id="${el.id}-post-${i+1}-s"><body>${xmlEscape(p)}</body></specification>`);
+          lines.push(`      </postcondition>`);
+        });
+        if (el.scenarios && el.scenarios.length) {
+          const body = flowText(el);
+          lines.push(`      <ownedBehavior xmi:type="uml:OpaqueBehavior" xmi:id="${el.id}-flow" name="Flow of Events">`);
+          lines.push(`        <body>${xmlEscape(body)}</body>`);
+          lines.push(`      </ownedBehavior>`);
+        }
+        lines.push(`    </packagedElement>`);
+      }
+    }
     if (el.kind === 'actor')
       lines.push(`    <packagedElement xmi:type="uml:Actor" xmi:id="${el.id}" name="${xmlEscape(el.name)}"/>`);
   }

package/skills/_shared/model-shape.md

@@ -63,6 +63,8 @@ const diagramModel = {
 
 ### Use-case diagram elements
 
+**v2 schema** — every UC carries full Visual Paradigm-style documentation (primary actor, scenarios with flow-of-events, pre/post-conditions, user stories, optional wireframe). The doc fields populate the per-UC modal and the XMI export. Required: `primaryActor`, `scenarios` (≥1 with ≥1 flow step), `preconditions`, `postconditions`, `userStories`. Optional: `secondaryActors`, `wireframe`.
+
 ```javascript
 // Element subtypes for kind: 'use-case'
 { kind: 'actor', id, name,
@@ -70,13 +72,43 @@ const diagramModel = {
   side: 'left' | 'right',
   x, y }
 
-{ kind: 'useCase', id, name, description: '',
-  x, y, rx, ry }    // rx/ry = ellipse radii
+{ kind: 'useCase', id, name,
+  description: '',               // short summary
+
+  // v2 documentation fields:
+  primaryActor: 'actorId',       // exactly one, must exist in elements
+  secondaryActors: [],           // optional actor ids
+  preconditions:  [ 'string' ],
+  postconditions: [ 'string' ],
+
+  scenarios: [                   // ≥1 scenario required
+    { id, name,
+      flow: [                    // ≥1 step required
+        { kind: 'actor',     actor: 'actorId', text: '' },
+        { kind: 'system',                       text: '' },
+        { kind: 'include',   uc:    'ucId',    text: '' },
+        { kind: 'extension', at:    2,          text: '' }   // at = step number extended
+      ],
+      extensions: [              // optional, alternative to inline extension steps
+        { at: 2, text: '' }
+      ]
+    }
+  ],
+
+  userStories: [
+    { role: '', want: '', so: '' }
+  ],
+
+  wireframe: '',                 // optional inline HTML fragment, see SKILL.md §WF
+
+  x, y, rx, ry }                 // rx/ry = ellipse radii (diagram layout)
 
 { kind: 'system', id, name, x, y, w, h }   // system boundary rectangle
 
 // Relationship subtypes
-{ kind: 'actorAssoc',    id, actorId, ucId }
+{ kind: 'actorAssoc',    id, actorId, ucId,
+  role: 'initiator' | 'participant' | 'recipient' | 'supplier',
+  description: '' }                         // click-popup text
 { kind: 'include',       id, from, to }     // from = including UC, to = included
 { kind: 'extend',        id, from, to, extensionPoint: '' }
 { kind: 'generalization',id, from, to }     // actors or UCs; from = child, to = parent

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

@@ -206,6 +206,35 @@ Reason: Critical for consistency in distributed/international teams
 
 ---
 
+## 11a. UC Documentation (Visual Paradigm convention)
+
+Beyond the diagram shapes, each use case carries a **written specification** — this is what Visual Paradigm stores in the UC's "Specification" pane and what students include in exam answers. The skill's §4.4 block captures the same structure:
+
+| Field | VP name | Convention |
+|---|---|---|
+| Primary actor | Primary actor | The actor who **initiates** the UC (single). Secondary actors listed separately. |
+| Description | Description | One-sentence summary of the goal. |
+| Preconditions | Preconditions | Bulleted list — must hold BEFORE the UC starts. |
+| Postconditions | Postconditions | Bulleted list — must hold AFTER the UC completes successfully. |
+| Flow of events | Flow of Events / Basic Flow | Numbered steps. Each step names who does what. Actor references and include/extend cross-references are explicit, like pseudo-code. |
+| Extensions | Extensions / Alternative Flows | Sub-steps labelled `Na`, `Nb`, … under the step they branch from. |
+| User stories | (project-level, not per-UC in VP) | Added by the skill so students can trace each UC back to its requirement. |
+
+**Flow-of-events step style** — taught by the professor (Lecture 4, slides 210-215, coffee shop example):
+
+```
+1. Customer selects a product from the catalog.
+2. System adds the product to the cart.
+3. «include» Authenticate Customer.
+4. Customer confirms the order.
+   4a. If payment method is rejected — notify customer and end in "Not Completed" status.
+5. System saves the order and returns an order ID.
+```
+
+The in-HTML modal (§8a of the SKILL) renders this style verbatim.
+
+---
+
 ## 11. SUMMARY
 
 Professor teaches UML use case notation through:

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

@@ -31,6 +31,7 @@ The shared files prepended to this prompt define the layout recipes, model shape
 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), assumptions, and open questions must all contain Hebrew. Identifier strings (`id`, `primaryActor: 'customer'`) stay ASCII. The validator (§12) rejects narrative fields that contain zero Hebrew characters.
 
 ---
 
@@ -143,6 +144,51 @@ Arrow: dashed, open arrowhead, `Base UC → Included UC`.
 
 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: "מסלול מרכזי (Happy Path)"
+      flow:
+        1. [actor:primaryActor] ___________________
+        2. [system] ___________________
+        3. [include:uc-xxx]    ___________________    (only if §4.2 gate passed)
+        4. [actor:secondary]   ___________________
+      extensions:
+        2a. if ___________ then ___________
+        4a. if ___________ then ___________
+    - id: sc-alt-1, name: "מסלול חלופי: ___" (optional additional scenarios)
+
+  userStories:   (as many as the UC warrants — one per distinct stakeholder need; not a fixed number)
+    - As a [role], I want [want], so that [benefit].
+    - As a [different role OR same role different goal], I want [...], so that [...].
+    - ... (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.
@@ -432,15 +478,26 @@ If neither trigger fires, produce a single tab. Do not split on gut feeling.
 
 ---
 
-## 8. Clickable Descriptions for UCs, Actors, and Associations (Always Include)
+## 8. Clickable Descriptions — Modal for UCs, Popups for Actors & Associations
 
-Every UC ellipse, every actor, **and every association line** must be clickable — click shows a floating panel with name + description. One `showDesc(id, type, event)` function handles all three.
+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);
+}
+```
+
+### 8b. Small popup for actors and associations
 
 ```javascript
-const useCaseDescriptions = {
-  'uc1': { name: 'פתיחת הזמנה', desc: 'המשתמש פותח הזמנה חדשה ומציין פרטי המוצרים הנדרשים.' },
-  // ... one entry per UC
-};
 const actorDescriptions = {
   'customer': { name: 'לקוח', desc: 'לקוח הרשום במערכת. יוזם הזמנות ועוקב אחר סטטוס.' },
   // ... one entry per actor
@@ -451,10 +508,9 @@ const assocDescriptions = {
   // ... one entry per association line you want described
 };
 
-function showDesc(id, type, event) {
+function showPopup(id, type, event) {
   hideDesc();
-  const data = type === 'uc'    ? useCaseDescriptions[id]
-             : type === 'actor' ? actorDescriptions[id]
+  const data = type === 'actor' ? actorDescriptions[id]
              : type === 'assoc' ? assocDescriptions[id]
              : null;
   if (!data) return;
@@ -486,6 +542,166 @@ document.addEventListener('click', e => {
 });
 ```
 
+### 8a. Full-screen modal for UCs
+
+Every UC ellipse's click routes to `openUcModal(id)`, which reads `useCaseDocs[id]` (populated from the §4.4 documentation blocks) and renders a full-screen modal with the complete UC spec. The modal has sections for: header (id + name + primary actor link), description, scenarios (numbered flow with typed steps + extensions), a row with preconditions / postconditions / user stories, and an optional wireframe.
+
+```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 שעות.' }
+    ],
+    wireframe: ''   // optional per §WF
+  }
+  // ... one entry per UC
+};
+
+function openUcModal(id) {
+  const doc = useCaseDocs[id];
+  if (!doc) return;
+  const actorName = aid => (actorDescriptions[aid]?.name) || aid;
+  const ucName    = uid => (useCaseDocs[uid]?.name) || uid;
+  const modal = document.getElementById('uc-modal');
+  modal.querySelector('.uc-id').textContent       = doc.id;
+  modal.querySelector('.uc-name').textContent     = doc.name;
+  const paLink = modal.querySelector('.uc-primary-link');
+  paLink.textContent  = actorName(doc.primaryActor);
+  paLink.dataset.actorId = doc.primaryActor;
+  paLink.onclick = () => { closeUcModal(); pulseActor(doc.primaryActor); };
+
+  modal.querySelector('.uc-description').textContent = doc.description || '';
+
+  // Scenarios
+  const sc = modal.querySelector('.uc-scenarios');
+  sc.innerHTML = '';
+  (doc.scenarios || []).forEach(sce => {
+    const h = document.createElement('h3'); h.textContent = sce.name || sce.id; sc.appendChild(h);
+    const ol = document.createElement('ol');
+    (sce.flow || []).forEach((step, i) => {
+      const li = document.createElement('li');
+      if (step.kind === 'actor') {
+        const strong = document.createElement('strong');
+        strong.className = 'step-actor';
+        strong.dataset.actorId = step.actor;
+        strong.textContent = actorName(step.actor);
+        strong.onclick = () => { closeUcModal(); pulseActor(step.actor); };
+        li.appendChild(strong);
+        li.appendChild(document.createTextNode(': ' + (step.text || '')));
+      } else if (step.kind === 'system') {
+        const em = document.createElement('em');
+        em.className = 'step-system'; em.textContent = 'המערכת';
+        li.appendChild(em);
+        li.appendChild(document.createTextNode(': ' + (step.text || '')));
+      } else if (step.kind === 'include') {
+        const span = document.createElement('span');
+        span.className = 'step-include'; span.textContent = '«include» ';
+        const a = document.createElement('a');
+        a.className = 'step-uc-ref'; a.textContent = ucName(step.uc);
+        a.onclick = () => openUcModal(step.uc);
+        li.appendChild(span); li.appendChild(a);
+        if (step.text) li.appendChild(document.createTextNode(' — ' + step.text));
+      } else if (step.kind === 'extension') {
+        li.className = 'ext-inline';
+        li.textContent = (step.at ? step.at + 'a. ' : '') + (step.text || '');
+      }
+      ol.appendChild(li);
+      // Inline extensions defined in sce.extensions anchored to this step number:
+      (sce.extensions || []).filter(e => e.at === i + 1).forEach((ext, j) => {
+        const sub = document.createElement('li');
+        sub.className = 'ext-sub';
+        const letter = String.fromCharCode(97 + j);  // a, b, c, ...
+        sub.textContent = (i + 1) + letter + '. ' + ext.text;
+        ol.appendChild(sub);
+      });
+    });
+    sc.appendChild(ol);
+  });
+
+  const fillList = (selector, items) => {
+    const el = modal.querySelector(selector);
+    el.innerHTML = '';
+    (items || []).forEach(s => { const li = document.createElement('li'); li.textContent = s; el.appendChild(li); });
+  };
+  fillList('.uc-pre ul',    doc.preconditions);
+  fillList('.uc-post ul',   doc.postconditions);
+  const usList = modal.querySelector('.uc-stories ul');
+  usList.innerHTML = '';
+  (doc.userStories || []).forEach(us => {
+    const li = document.createElement('li');
+    li.textContent = `As a ${us.role}, I want ${us.want}, so that ${us.so}`;
+    usList.appendChild(li);
+  });
+
+  // Wireframe — safety-checked before insertion
+  const wf = modal.querySelector('.uc-wireframe');
+  wf.innerHTML = '';
+  if (doc.wireframe && wireframeSafe(doc.wireframe)) {
+    wf.innerHTML = doc.wireframe;
+    wf.hidden = false;
+  } else {
+    wf.hidden = true;
+    if (doc.wireframe) console.warn(`Wireframe for ${id} failed safety check.`);
+  }
+
+  modal.hidden = false;
+  document.body.classList.add('uc-modal-open');
+}
+
+function closeUcModal() {
+  const modal = document.getElementById('uc-modal');
+  modal.hidden = true;
+  document.body.classList.remove('uc-modal-open');
+}
+
+// Esc closes the modal.
+document.addEventListener('keydown', e => {
+  if (e.key === 'Escape') closeUcModal();
+});
+
+// Highlight an actor on the diagram for ~2s.
+function pulseActor(actorId) {
+  const g = document.getElementById('actor-group-' + actorId);
+  if (!g) return;
+  g.classList.add('actor-pulse');
+  setTimeout(() => g.classList.remove('actor-pulse'), 2000);
+}
+
+// Wireframe sanity check — see §WF. Rejects scripts, event handlers, external URLs.
+function wireframeSafe(html) {
+  const forbidden = [
+    /<script\b/i,
+    /\son\w+\s*=/i,
+    /<iframe\b/i,
+    /src\s*=\s*["']https?:/i,
+    /href\s*=\s*["']https?:/i,
+    /@import\b/i,
+    /<style\b/i
+  ];
+  return !forbidden.some(rx => rx.test(html));
+}
+```
+
 UC group: `<g id="uc-uc1" data-uc-id="uc1" onclick="showDesc('uc1','uc',event)" style="cursor:pointer">`
 Actor group: `<g id="actor-student" data-actor-id="student" onclick="showDesc('student','actor',event)" style="cursor:pointer">`
 
@@ -573,10 +789,89 @@ The `connections` entry for a timed link looks like:
 
 ---
 
+## §WF. Wireframe Authoring (Per-UC, Optional)
+
+Where a UC benefits from a visual mock of the UI the user sees, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
+
+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
+
+- The UC has no user-facing screen (e.g., a back-end cron job, an automated reconciliation).
+- The UI is trivial (e.g., a single "Approve" confirmation prompt) — prose in the scenario flow is enough.
+- You cannot author the wireframe without making up details the spec does not support — put those in `diagramModel.openQuestions` instead.
+
+---
+
 ## 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:
@@ -626,6 +921,95 @@ The assumptions panel CSS must be included in the HTML `<style>` block:
 .assumptions-col li { color: #334155; font-size: 12px; line-height: 1.6; }
 ```
 
+### v2 — UC modal styling
+
+```css
+/* Lock body scroll while the modal is open */
+body.uc-modal-open { overflow: hidden; }
+
+.uc-modal { position: fixed; inset: 0; z-index: 2000; display: flex;
+  align-items: flex-start; justify-content: center; padding: 40px 20px;
+  overflow-y: auto; direction: rtl;
+  font-family: 'Noto Sans Hebrew', sans-serif; }
+.uc-modal-backdrop { position: absolute; inset: 0; background: rgba(15, 23, 42, 0.55); }
+.uc-modal-body { position: relative; z-index: 1; width: 100%; max-width: 960px;
+  background: #fff; border-radius: 12px; box-shadow: 0 10px 40px rgba(0,0,0,.25);
+  padding: 28px 32px 32px; color: #1e293b; }
+.uc-modal-close { position: absolute; top: 10px; left: 14px; background: none;
+  border: none; font-size: 24px; color: #64748b; cursor: pointer; }
+.uc-modal-body header { border-bottom: 1px solid #e2e8f0; padding-bottom: 12px;
+  margin-bottom: 18px; }
+.uc-modal-body .uc-id { display: inline-block; font-family: 'IBM Plex Mono',monospace;
+  font-size: 11px; color: #64748b; background: #f1f5f9; padding: 2px 8px;
+  border-radius: 4px; margin-bottom: 6px; }
+.uc-modal-body .uc-name { margin: 0 0 4px; font-size: 20px; color: #1e40af; font-weight: 700; }
+.uc-modal-body .uc-primary { font-size: 13px; color: #334155; }
+.uc-modal-body .uc-primary-label { color: #64748b; margin-left: 6px; }
+.uc-modal-body .uc-primary-link { color: #1e40af; cursor: pointer; font-weight: 600;
+  text-decoration: underline dotted; }
+.uc-description { margin-bottom: 20px; font-size: 14px; line-height: 1.7; color: #334155; }
+
+.uc-scenarios h3 { font-size: 14px; color: #1e40af; margin: 18px 0 6px;
+  border-right: 3px solid #3b82f6; padding-right: 10px; }
+.uc-scenarios ol { margin: 0 0 14px; padding-right: 22px; }
+.uc-scenarios ol li { color: #1e293b; font-size: 13px; line-height: 1.9; }
+.step-actor { color: #1e40af; font-weight: 600; cursor: pointer; text-decoration: underline dotted; }
+.step-system { color: #475569; font-style: italic; }
+.step-include { color: #7c3aed; font-family: 'IBM Plex Mono', monospace; font-size: 11px; }
+.step-uc-ref { color: #7c3aed; cursor: pointer; text-decoration: underline; }
+.ext-inline, .ext-sub { list-style: none; color: #64748b; font-size: 12px;
+  padding-right: 24px; line-height: 1.7; }
+
+.uc-prepostuser { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 18px;
+  margin: 18px 0 20px; }
+.uc-prepostuser > div { background: #f8fafc; border: 1px solid #e2e8f0;
+  border-radius: 8px; padding: 12px 14px; }
+.uc-prepostuser h4 { margin: 0 0 6px; font-size: 12px; color: #1e40af; font-weight: 600; }
+.uc-prepostuser ul { margin: 0; padding-right: 18px; font-size: 12px;
+  color: #334155; line-height: 1.7; }
+
+.uc-wireframe { border-top: 1px dashed #cbd5e1; padding-top: 16px; margin-top: 6px; }
+.uc-wireframe:empty, .uc-wireframe[hidden] { display: none; }
+
+/* Actor pulse animation used by pulseActor() */
+.actor-pulse { animation: actor-pulse 0.6s ease-in-out 3; }
+@keyframes actor-pulse {
+  0%, 100% { filter: none; }
+  50%      { filter: drop-shadow(0 0 8px #3b82f6); }
+}
+```
+
+### v2 — Wireframe scoped theme
+
+```css
+.wf-screen { background: #f8fafc; border: 1px solid #cbd5e1; border-radius: 8px;
+  padding: 18px 20px; font-family: 'Noto Sans Hebrew', sans-serif;
+  color: #1e293b; direction: rtl; max-width: 760px; margin: 0 auto; }
+.wf-heading { margin: 0 0 14px; font-size: 15px; color: #1e40af; font-weight: 700;
+  border-bottom: 1px solid #e2e8f0; padding-bottom: 6px; }
+.wf-section { margin: 14px 0; }
+.wf-row { display: flex; gap: 10px; align-items: center; margin: 6px 0; }
+.wf-label { font-size: 12px; color: #475569; min-width: 120px; }
+.wf-input, .wf-textarea, .wf-select { flex: 1; background: #fff;
+  border: 1px solid #cbd5e1; border-radius: 4px; padding: 6px 8px;
+  font-size: 12px; color: #334155; }
+.wf-textarea { min-height: 60px; }
+.wf-table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 12px; }
+.wf-table th, .wf-table td { border: 1px solid #cbd5e1; padding: 6px 8px;
+  text-align: right; }
+.wf-table th { background: #e2e8f0; color: #1e40af; font-weight: 600; }
+.wf-actions { display: flex; gap: 8px; margin-top: 12px; justify-content: flex-start; }
+.wf-button { background: #fff; border: 1px solid #64748b; border-radius: 4px;
+  padding: 6px 14px; font-size: 12px; color: #334155; cursor: default; }
+.wf-primary { background: #1e40af; color: #fff; border-color: #1e40af; }
+.wf-image-box { border: 1px dashed #94a3b8; background: #f1f5f9; color: #64748b;
+  text-align: center; padding: 24px; border-radius: 4px; font-size: 12px;
+  margin: 10px 0; }
+.wf-hint { font-size: 11px; color: #64748b; font-style: italic; margin: 6px 0; }
+.wf-badge { display: inline-block; background: #e0f2fe; color: #0369a1;
+  padding: 2px 8px; border-radius: 999px; font-size: 10px; font-weight: 600; }
+```
+
 ---
 
 ## 11. HTML File Structure
@@ -677,13 +1061,38 @@ The assumptions panel CSS must be included in the HTML `<style>` block:
     </div>
   </div>
 
+  <!-- v2 — UC modal (populated by openUcModal; hidden by default) -->
+  <div id="uc-modal" class="uc-modal" hidden role="dialog" aria-modal="true">
+    <div class="uc-modal-backdrop" onclick="closeUcModal()"></div>
+    <div class="uc-modal-body">
+      <button class="uc-modal-close" onclick="closeUcModal()" aria-label="Close">×</button>
+      <header>
+        <span class="uc-id"></span>
+        <h2 class="uc-name"></h2>
+        <div class="uc-primary">
+          <span class="uc-primary-label">שחקן ראשי:</span>
+          <a class="uc-primary-link"></a>
+        </div>
+      </header>
+      <section class="uc-description"></section>
+      <section class="uc-scenarios"></section>
+      <section class="uc-prepostuser">
+        <div class="uc-pre"><h4>תנאים מוקדמים</h4><ul></ul></div>
+        <div class="uc-post"><h4>תנאים סופיים</h4><ul></ul></div>
+        <div class="uc-stories"><h4>סיפורי משתמש</h4><ul></ul></div>
+      </section>
+      <section class="uc-wireframe" hidden></section>
+    </div>
+  </div>
+
   <!-- VP export button -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
   <script>
     const diagramLayouts = [ /* one layout object per tab, per §6 */ ];
-    const useCaseDescriptions = { /* §8 */ };
-    const actorDescriptions   = { /* §8 */ };
+    const actorDescriptions   = { /* §8b */ };
+    const assocDescriptions   = { /* §8b */ };
+    const useCaseDocs         = { /* §8a — full v2 per-UC documentation */ };
     const diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
 
     let activeTab = 0;
@@ -695,11 +1104,16 @@ The assumptions panel CSS must be included in the HTML `<style>` block:
       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 */ }
+    function fixLayout(layout)        { /* §6 */ }
+    function showDesc(id, type, event){ /* §8: routes to openUcModal for UCs, showPopup otherwise */ }
+    function showPopup(id, type, event){ /* §8b */ }
+    function hideDesc()               { /* §8b */ }
+    function openUcModal(id)          { /* §8a */ }
+    function closeUcModal()           { /* §8a */ }
+    function pulseActor(actorId)      { /* §8a */ }
+    function wireframeSafe(html)      { /* §8a / §WF */ }
+    function xmiBody(elements, rels)  { /* export-buttons.md — v2 emits preconditions/postconditions/ownedBehavior */ }
+    function exportXMI()              { /* export-buttons.md */ }
 
     function renderAssumptions() {
       const a = (diagramModel && diagramModel.assumptions)   || [];
@@ -738,13 +1152,43 @@ The assumptions panel CSS must be included in the HTML `<style>` block:
 
 ## 12. Output
 
-- 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).
+**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
+
+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.
+- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only.
 - [ ] 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.