sad-mcp 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,85 @@
+# sad-mcp
+
+MCP server that gives students access to **Software Analysis and Design** course materials through Claude Desktop. Materials are served from a shared Google Drive folder.
+
+## What it does
+
+- Exposes course materials (lectures, transcripts, exams) as MCP **resources**
+- Provides `search_materials` and `list_materials` **tools** for Claude to query course content
+- Extracts text from PPTX, PDF, DOCX, XLSX, and plain text files
+- Caches files locally to avoid repeated downloads
+- Tracks anonymous usage for research purposes
+
+## Student setup
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "sad-course": {
+      "command": "npx",
+      "args": ["-y", "sad-mcp@latest"]
+    }
+  }
+}
+```
+
+On Windows, use the full path to `npx.cmd`:
+
+```json
+{
+  "mcpServers": {
+    "sad-course": {
+      "command": "C:\\Program Files\\nodejs\\npx.cmd",
+      "args": ["-y", "sad-mcp@latest"]
+    }
+  }
+}
+```
+
+On first run, a browser window will open for Google authentication. Sign in with your **@post.bgu.ac.il** account. After that, the server connects automatically.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_materials(query)` | Full-text search across all course materials |
+| `list_materials(category?)` | List available materials, optionally filtered by `lectures`, `transcripts`, `exams`, or `all` |
+
+## Resources
+
+All extractable files from the course Google Drive folder are exposed as MCP resources with URIs like `sad://lectures/filename.pptx` or `sad://transcripts/filename.txt`. Claude can read these directly.
+
+## Local data
+
+The server stores data in `~/.sad-mcp/`:
+
+| File | Purpose |
+|------|---------|
+| `tokens.json` | Google OAuth refresh token |
+| `anonymous-id.txt` | Random UUID for usage tracking |
+| `usage-log.jsonl` | Local usage event log |
+| `cache/` | Downloaded file cache (1-hour TTL) |
+| `cache-index.json` | Cache metadata |
+
+## Development
+
+```bash
+npm install
+npm run build    # compile TypeScript
+npm run dev      # watch mode
+```
+
+## Publishing
+
+```bash
+# bump version in package.json
+npm publish
+```
+
+Students get the latest version automatically via `npx -y sad-mcp@latest`.
+
+## License
+
+MIT

package/dist/index.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerResourceHandlers } from "./resources.js";
 import { registerToolHandlers } from "./tools.js";
+import { registerPromptHandlers } from "./prompts.js";
 import { trackServerStart } from "./tracking.js";
 async function main() {
     // Connect to Claude Desktop IMMEDIATELY — no blocking auth here
     // Auth happens lazily on first Drive API call
-    const server = new Server({ name: "sad-mcp", version: "0.1.3" }, {
+    const server = new Server({ name: "sad-mcp", version: "0.1.4" }, {
         capabilities: {
-            resources: {},
             tools: {},
+            prompts: {},
         },
     });
-    registerResourceHandlers(server);
     registerToolHandlers(server);
+    registerPromptHandlers(server);
     trackServerStart();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function registerPromptHandlers(server: Server): void;

package/dist/prompts.js

@@ -0,0 +1,56 @@
+import { ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILLS = [
+    {
+        id: "uml-class-diagram",
+        name: "UML Class Diagram",
+        description: "Create professional UML class diagrams as interactive HTML/SVG files",
+    },
+    {
+        id: "uml-state-diagram",
+        name: "UML State Diagram",
+        description: "Create professional UML state/statechart diagrams as interactive HTML/SVG files",
+    },
+    {
+        id: "uml-use-case-diagram",
+        name: "UML Use Case Diagram",
+        description: "Create professional UML use case diagrams as interactive HTML/SVG files",
+    },
+    {
+        id: "bpmn-diagram",
+        name: "BPMN Diagram",
+        description: "Create BPMN business process diagrams as interactive HTML/SVG files",
+    },
+];
+function loadSkill(skillId) {
+    const skillsDir = join(__dirname, "..", "skills");
+    return readFileSync(join(skillsDir, skillId, "SKILL.md"), "utf-8");
+}
+export function registerPromptHandlers(server) {
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: SKILLS.map((skill) => ({
+            name: skill.id,
+            description: skill.description,
+        })),
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const skill = SKILLS.find((s) => s.id === request.params.name);
+        if (!skill) {
+            throw new Error(`Unknown skill: ${request.params.name}`);
+        }
+        const content = loadSkill(skill.id);
+        return {
+            description: skill.description,
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: content },
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "sad-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {
     "sad-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",

package/skills/bpmn-diagram/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: bpmn-diagram
+description: Create BPMN (Business Process Model and Notation) diagrams as interactive HTML/SVG files. Use this skill when the user asks to create, model, or visualize a business process, workflow diagram, BPMN diagram, or process map. Handles Hebrew RTL processes, swim lanes, pools, gateways, data objects, data stores, message flows, and intermediate events. Outputs a single self-contained HTML file with embedded SVG.
+---
+
+# BPMN Diagram Creation Skill
+
+This skill creates professional, standards-compliant BPMN diagrams rendered as interactive HTML files with embedded SVG. The diagrams support Hebrew (RTL) and English text, and follow BPMN 2.0 notation with BPMN 1.1-style intermediate events (plain double circles without internal icons).
+
+## When to Use
+
+- User asks to create a BPMN diagram, process model, or workflow diagram
+- User describes a business process and wants it visualized
+- User provides a process narrative in any language and wants a BPMN representation
+- User asks to model a process with swim lanes, pools, gateways, or data flows
+
+## Process Analysis — Before Drawing
+
+Before writing any SVG code, analyze the process description to identify:
+
+1. **Participants**: Who are the actors? Determine if they are internal (lanes in the same pool) or external (separate pools)
+   - External participants (customers, patients, citizens) → **separate pool** with message flows
+   - Internal roles within the same organization → **lanes** within one pool
+2. **Activities/Tasks**: List every action/task mentioned
+3. **Decision Points**: Identify every conditional branch (if/else, exists/doesn't exist)
+4. **Data**: What information is created, read, updated, or stored?
+5. **Handoffs**: Where does work pass between participants? These become message flows between pools or sequence flows between lanes
+6. **Waiting Points**: Is any participant passively waiting? Use intermediate events, not regular tasks
+7. **Data Persistence**: If the process description mentions a "system" or implies that data is stored, read, or updated across multiple steps or participants — model a Data Store (DB). Connect it with data associations to every task that reads from or writes to it. Do NOT substitute a lightweight Data Object when persistent shared storage is implied. A system = a data store.
+8. **Complete Each Participant's Flow**: Every pool must have its own complete internal sequence flow (start → tasks → end), even for external parties. If the description says "Company X will handle the complaint," model the full handling sequence inside that pool (receive → process → respond → close), not just the first step. Never collapse an external participant's process into a single task or annotation.
+9. **Bidirectional Communication**: When one participant sends something to another, check: does the receiver send something back? Every message flow that triggers a response must have a corresponding return message flow. Model both directions explicitly. Common pairs: request→acknowledgment, notification→confirmation, complaint→response.
+10. **Implied Activities**: Read the description for activities that are described but not explicitly named as "tasks." Phrases like "she can and is expected to be in phone contact" or "will coordinate directly" describe real activities that should be modeled as tasks, NOT as text annotations. Annotations are only for meta-information that clarifies context but isn't an executable step.
+
+## Architecture & Layout Rules
+
+### Pools and Lanes
+
+- **External participants** (e.g., patient, customer, citizen) get their own **pool** at the top of the diagram
+  - Use a distinct color scheme for the external pool header (e.g., brown) to differentiate from the organization pool (dark gray)
+  - External pool tasks use a warm color (e.g., orange `#fff3e0` fill, `#e65100` stroke)
+- **Internal roles** within the organization are modeled as **lanes** within the organization pool
+  - Each lane gets a labeled sidebar and a subtle background tint
+  - Separate lanes with dashed divider lines
+- Pool headers are vertical text bars on the left side of the pool
+
+### Color Scheme by Participant Type
+
+| Element | Fill | Stroke |
+|---------|------|--------|
+| External participant tasks | `#fff3e0` | `#e65100` |
+| Reception/admin tasks | `#e3f2fd` | `#1976d2` |
+| Clinical/operational tasks | `#f3e5f5` | `#7b1fa2` |
+| XOR Gateways | `#fff8e1` | `#f9a825` |
+| Start event | `#e8f5e9` | `#2e7d32` |
+| End event | `#ffebee` | `#c62828` |
+| Data objects | `#fff` | `#1565c0` |
+| Data stores | `#fff` | `#2e7d32` |
+
+### Pool Ordering — Optimal Layout
+
+When multiple external pools exist, order pools to **minimize message flow crossing distance**:
+
+- Place the **primary actor** (the one who initiates and interacts with multiple parties) in the **middle**, not at the top
+- Place pools they interact with **above and below** so message flows go in both directions naturally
+- Rule of thumb: Count message flows between each pair of pools. Adjacent pools should be the pairs with the most message flows between them
+
+Example: If a Resident interacts with both a Delivery Company and a Development Company → place Delivery Company on top, Resident in the middle, Development Company on the bottom.
+
+### Flow Types
+
+- **Sequence flows** (within a pool): Solid lines with filled arrowheads (`#546e7a`)
+- **Message flows** (between pools): Dashed lines (`stroke-dasharray: 10 5`) with open circle at source and filled arrow at target (`#37474f`)
+- **Data associations**: Dashed lines (`stroke-dasharray: 4 3`) with small arrowheads, colored by type:
+  - Data object associations: `#7986cb`
+  - Data store associations: `#4caf50`
+
+## BPMN Element Standards
+
+### Gateways — CRITICAL RULE
+
+**Every gateway — both split AND merge/join — MUST display the X marker (for XOR) or + marker (for AND/parallel).** Merge gateways are never left as blank diamonds. This is a non-negotiable requirement.
+
+```svg
+<!-- XOR Gateway template (both split and merge) -->
+<rect x="X" y="Y" width="34" height="34" class="gateway" transform="rotate(45, CX, CY)"/>
+<line x1="CX-7" y1="CY-10" x2="CX+7" y2="CY+10" class="gateway-x"/>
+<line x1="CX+7" y1="CY-10" x2="CX-7" y2="CY+10" class="gateway-x"/>
+```
+
+### Intermediate Events (Waiting/Catching)
+
+Use **BPMN 1.1 style**: plain double circle with NO icon inside. Just two concentric circles.
+
+```svg
+<!-- Intermediate event — plain double circle -->
+<circle cx="X" cy="Y" r="16" fill="#fff" stroke="#1565c0" stroke-width="2"/>
+<circle cx="X" cy="Y" r="12" fill="none" stroke="#1565c0" stroke-width="1.2"/>
+```
+
+Use intermediate events (not tasks) when a participant is passively waiting for a signal, message, or trigger from another participant.
+
+### Data Objects vs Data Stores — MUST DISTINGUISH
+
+These are two different BPMN artifacts and must be visually distinct:
+
+**Data Objects** (folded-corner document icon, blue):
+- Represent a specific piece of data flowing through the process (e.g., "פרטי תינוק", "סיכום ביקור", "הערת מעקב")
+- Drawn as a rectangle with a folded top-right corner
+
+```svg
+<!-- Data Object template (w≈34, h≈38) -->
+<path d="M X,Y L X+26,Y L X+34,Y+8 L X+34,Y+38 L X,Y+38 Z" class="data-object-shape"/>
+<path d="M X+26,Y L X+26,Y+8 L X+34,Y+8" class="data-object-fold"/>
+```
+
+**Data Stores** (cylinder icon, green):
+- Represent persistent storage / databases (e.g., "מאגר כרטיסי תינוקות", "מאגר מדדים")
+- Drawn as a cylinder (two ellipses connected by vertical lines)
+
+```svg
+<!-- Data Store template -->
+<ellipse cx="CX" cy="TOP" rx="28" ry="8" class="data-store-body"/>
+<path d="M CX-28,TOP L CX-28,BOTTOM" fill="none" stroke="#2e7d32" stroke-width="1.3"/>
+<path d="M CX+28,TOP L CX+28,BOTTOM" fill="none" stroke="#2e7d32" stroke-width="1.3"/>
+<ellipse cx="CX" cy="BOTTOM" rx="28" ry="8" class="data-store-body"/>
+```
+
+### Data Artifact Placement
+
+- Place data objects **above** or **below** their associated task, never overlapping flow lines
+- Place data objects to the **left** of a task if vertical placement would cross flow paths
+- Data stores typically go below their associated tasks
+- **Never** place data artifacts in a location where their association lines cross or overlap with sequence flow arrows
+
+## Arrow Routing — CRITICAL
+
+The most important visual quality rule: **arrows must never be ambiguous**.
+
+### Split-Merge Pattern (Two Outcome Paths)
+
+When a gateway splits into two paths (e.g., "תקין" vs "דורש מעקב") and then merges:
+
+1. Place the **YES task** above the gateway's horizontal center line
+2. Place the **NO task** below the gateway's horizontal center line
+3. Place the **merge gateway** clearly to the right of BOTH tasks
+4. Route the YES path: task → **right** → **down** into merge gateway (entering from top)
+5. Route the NO path: task → **right** → **up** into merge gateway (entering from bottom)
+6. From the merge gateway, route a **single clean vertical line down** to the next task
+
+**The merge area must have clear visual separation between all paths. No path should overlap another.**
+
+### General Routing Rules
+
+- Prefer orthogonal (right-angle) routing over diagonal lines
+- Leave at least 30px spacing between parallel flow lines
+- When routing a flow from one lane to another, use a clear vertical drop/rise
+- Label YES/NO (כן/לא) near the gateway, not at the end of the path
+- Flow labels should not overlap with other elements
+
+## Modeling Rejection/Retry Loops
+
+When a process includes an approval step where the participant can reject:
+
+1. Model the **rejection action** as an explicit task in the rejecting participant's pool (e.g., "שליחת ביטול סגירה"), not just a gateway output
+2. After rejection, model what the rejecting participant **does next** — typically a waiting intermediate event (e.g., waiting for follow-up contact)
+3. In the receiving pool, model the **response to rejection** as a concrete task sequence (e.g., "contact customer" → "decide next step")
+4. Loop-back arrows should return to the earliest meaningful re-entry point in the process, not to an arbitrary task
+
+## Typography & Hebrew Support
+
+- Use `Noto Sans Hebrew` (imported from Google Fonts) for all text
+- Set `lang="he"` and `dir="rtl"` on the HTML element
+- Task text: 11.5px, font-weight 500, centered in the task box
+- Gateway labels: 10.5px, font-weight 400, positioned above the diamond
+- Data labels: 9.5px, font-weight 500
+- Flow labels (כן/לא): 10px
+
+## File Structure
+
+Output a single self-contained HTML file with:
+
+1. **Header bar**: Gradient background with process title in Hebrew + English subtitle
+2. **Legend**: Horizontal bar showing all BPMN symbols used in the diagram (start, end, task, XOR gateway, intermediate event, data object, data store, message flow)
+3. **SVG canvas**: The full BPMN diagram in a scrollable wrapper
+4. **SVG definitions**: Drop shadow filters, arrow markers (sequence, message, data association)
+
+### SVG Sizing
+
+- Width: 1700–1800px typical (allow overflow scroll)
+- Height: Scale based on number of pools and lanes (~130px per external pool, ~250px per lane, plus spacing for data artifacts)
+- Use `viewBox` matching width/height for proper scaling
+
+## Iterative Refinement Checklist
+
+After generating the initial diagram, verify:
+
+- [ ] Every gateway (split AND merge) has an X or + symbol
+- [ ] No arrow paths overlap or cross ambiguously
+- [ ] Data objects (📄) and data stores (🗄️) use different icons
+- [ ] External participants are in separate pools with message flows
+- [ ] Passive waiting uses intermediate events, not regular tasks
+- [ ] Flow labels (כן/לא) are clearly positioned near their gateway
+- [ ] The legend includes every symbol type used in the diagram
+- [ ] Data artifacts don't overlap with sequence flow paths
+- [ ] Every pool has a complete internal flow (start → ... → end), not just a single task
+- [ ] A Data Store is modeled if the process mentions a "system" or database
+- [ ] Every message flow that expects a response has a return message flow
+- [ ] Phone calls, emails, and direct contacts mentioned in the description are modeled as tasks, not annotations
+- [ ] After a rejection/refusal gateway, the rejecting participant's subsequent state (waiting/action) is explicitly modeled
+- [ ] Pool ordering minimizes message flow crossing distance
+
+## Example Process Categories
+
+This skill handles processes such as:
+- Healthcare workflows (e.g., Tipat Halav clinic visits, hospital admissions)
+- Government/municipal service processes
+- Customer service and support flows
+- Order fulfillment and logistics
+- Employee onboarding
+- Academic/educational administration processes
+
+The skill works for any domain — adapt the color scheme and terminology to match the context.
+
+## Hebrew Language Guidelines (שפה מגדרית נייטרלית)
+
+When labels, names, actors, roles, or any text in the diagram are written in Hebrew, follow these rules:
+
+### Use Male Form as Default
+Always use the **male grammatical form** (זכר) when referring to people, roles, actors, classes, or participants — even when the role is traditionally associated with a specific gender.
+
+**Examples of correct usage:**
+- ✅ רופא (not אחות for a nurse role — use אח)
+- ✅ אח (nurse, male form)
+- ✅ מטופל (not מטופלת)
+- ✅ לקוח (not לקוחה)
+- ✅ מנהל (not מנהלת)
+- ✅ עובד (not עובדת)
+- ✅ משתמש (not משתמשת)
+- ✅ סטודנט (not סטודנטית)
+
+**Examples of stereotypic writing to avoid:**
+- ❌ רופא ואחות — implies doctor=male, nurse=female
+- ❌ מזכירה — use מזכיר instead
+- ❌ אחות — use אח instead
+
+### Rule Summary
+> When in doubt, use the male form. This ensures gender neutrality and avoids reinforcing occupational gender stereotypes in diagram content.

package/skills/uml-class-diagram/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: uml-class-diagram
+description: >
+  Create professional UML 1.1 class diagrams as interactive HTML/SVG files.
+  Use this skill whenever the user asks to draw, create, design, or generate a
+  class diagram, UML diagram, object model, or domain model — even if they just
+  say "model these classes" or "show me the relationships between these entities".
+  Also trigger when the user uploads a document (exam, spec, requirements) and
+  asks to extract or design a class diagram from it. Always produces a
+  self-contained HTML file with embedded SVG, clean two-color styling, and an
+  optional interactive composition toggle panel.
+---
+
+# UML 1.1 Class Diagram Skill
+
+Produce a clean, exam-ready UML 1.1 class diagram as a single self-contained HTML file with embedded SVG.
+
+---
+
+## 1. Gather Requirements First
+
+Before drawing, extract or confirm:
+
+| Question | Why it matters |
+|---|---|
+| What are the core **entities/classes**? | Determines layout |
+| What **attributes** does each class have (name, type)? | Fills compartments |
+| What **methods** does each class have? | Third compartment |
+| What **enumerations** exist? | Grouped separately |
+| What are the **relationships** and their **multiplicities**? | Association lines |
+| Is the diagram for **teaching** (simplified) or production? | Affects notation choices |
+| Should the user be able to **toggle compositions** interactively? | Adds control panel |
+| **Should roles use enumerations or inheritance?** | Prefer enum; document reasoning if abstract classes are used |
+
+If the user provides a document (PDF, image, exam question), read it carefully and extract all of the above before drawing.
+
+---
+
+## 2. Notation Rules (UML 1.1 Style)
+
+### Classes
+- Three compartments: **Name** (blue header), **Attributes**, **Methods** (italic)
+- Attribute format: `+ name : Type` or `+ name : Type[ ]` for arrays
+- Method format (italic, blue): `+ methodName(param : Type) : ReturnType`
+- **Stereotype handling**: When a class has a stereotype (e.g., `«association class»`), increase the header height to at least 38px (from default 32px) so that BOTH the stereotype text AND the class name are fully readable. The stereotype goes on the first line (smaller font, ~9px), the class name on the second line (bold, normal size).
+
+### Enumerations
+- Stereotype header: `«enumeration»`
+- Gray dashed border, gray header — visually distinct from classes
+- List values only (no attributes/methods)
+- Group all enumerations on the **right side** of the diagram, separated by a vertical dashed line
+- **NO dependency lines from enums to classes** — do NOT draw dashed `«uses»` arrows connecting enumerations to the classes that reference them. The enum zone grouping is sufficient; dependency lines add clutter without information.
+
+### Association Lines
+- **Default: plain lines, no arrowheads, no diamonds** — this is the recommended starting point for teaching contexts
+- Multiplicity at **both ends**: `1`, `0..*`, `1..*`, `0..1`
+- Role label mid-line (rotated if diagonal)
+- **Composition diamonds** (◆, filled, at the "whole" end): only add when explicitly requested or via the interactive toggle panel
+
+### Association Classes
+- Mark with `«association class»` stereotype when a relationship itself has attributes
+- **CRITICAL**: An association class is drawn as a regular class box connected by a **dashed line to the midpoint of the association line** it describes. NEVER draw it as a standalone class connected by a regular dependency arrow — that is incorrect UML notation.
+- The dashed line should be perpendicular to the association line where possible, connecting from the center of the association to the top or bottom of the association class box.
+
+---
+
+## 3. Abstraction vs. Role Enum Decision
+
+When modeling roles (e.g., different user types, participant types, staff types):
+
+### Default: Use a Role Enumeration
+- Create a single class with a `role: RoleType` attribute
+- Add a `«enumeration» RoleType` with the possible roles
+- This is simpler, avoids inheritance, and matches how most systems store data
+
+### When Abstract Classes ARE Justified
+Use inheritance ONLY when subtypes have **genuinely different attributes or methods** — not just different role labels. For example:
+- ✅ `Vehicle` → `Car` (has: numDoors) vs `Truck` (has: payloadCapacity) — different attributes
+- ❌ `Person` → `Doctor` vs `Nurse` — same attributes, different role — use enum instead
+
+### "Why Abstraction?" Explanation Panel
+If abstract classes or inheritance ARE used in a diagram, add a small explanation panel (bottom-left of SVG, light yellow background) titled **"Why Abstraction?"** that lists:
+- Which classes use inheritance and why
+- What distinct attributes/methods each subclass adds
+- This helps students understand the design decision
+
+---
+
+## 4. Layout Strategy
+LEFT ZONE          CENTER ZONE         RIGHT ZONE
+─────────────      ────────────        ──────────────
+Secondary/        Core domain          ENUMERATIONS
+supporting        classes              (gray, dashed)
+classes           (main flow)
+
+**Routing rules to avoid line crossings:**
+- Run long associations along a fixed Y above all classes (horizontal routing)
+- Use L-shaped polylines for crossing-prone vertical connections
+- Diagonal lines only for clean point-to-point connections
+- Always verify coordinate math before finalizing paths
+- **Line-through-class-body prevention**: After placing all classes, verify that EVERY association line segment's coordinates do not pass through any class rectangle's bounding box (x, y, x+width, y+height). If a segment overlaps a class body, re-route to a different entry edge (e.g., right side instead of top) or detour around the outside. Never allow a line to visually cross through a class rectangle.
+
+---
+
+## 5. Styling Specification
+Background:       #f8fafc with dot-grid pattern (24px, #cbd5e1 dots r=0.8)
+Class fill:       white, border #3b82f6 (2px), header #1e40af
+Enum fill:        #f8fafc, border #94a3b8 dashed (5,3), header #475569
+Attribute text:   #1e293b, 10.5px
+Method text:      #2563eb, 10.5px, italic
+Label text:       #64748b, 9.5px
+Multiplicity:     #334155, 10px
+Association line: #334155, 1.8px
+Diamond fill:     #1e40af (same as class header)
+Font:             'IBM Plex Mono', monospace (load from Google Fonts)
+
+---
+
+## 6. Interactive Composition Toggle (when requested)
+
+Add a **left-side control panel** alongside the diagram when the user wants interactive composition selection.
+
+### Panel structure
+- Title: "Composition Toggle"
+- One card per candidate composition relationship
+- Each card includes:
+  - Toggle switch (CSS-animated, blue when active)
+  - Label: `WholeClass ◆── PartClass`
+  - Plain-language explanation of why it qualifies
+  - Strength badge: **Strong** (green) or **Moderate** (yellow)
+- "All ◆" and "Clear" buttons at the bottom
+
+### Composition strength criteria
+| Strength | Condition |
+|---|---|
+| **Strong** | Part has no identity or meaning without the whole; should be deleted with it |
+| **Moderate** | Part is created per-whole but references independent entities; borderline |
+
+### Diamond rendering
+- The diamond polygon sits **at the class boundary** (whole end), not floating on the line
+- Diamond points: `(x,y) (x-8, y-4.5) (x-16, y) (x-8, y+4.5)` — adjust for line direction
+- Use CSS `transition: opacity .22s` for smooth toggle
+- Diamonds start hidden (`opacity: 0`) and fade in on toggle
+
+### JavaScript
+```javascript
+const state = { 'rel-id': false, ... };
+function toggle(id) { state[id] = !state[id]; apply(id); }
+function apply(id) {
+  document.getElementById('diamond-' + id)
+    .setAttribute('opacity', state[id] ? '1' : '0');
+  document.getElementById('btn-' + id)
+    .classList.toggle('active', state[id]);
+}
+function setAll(on) {
+  Object.keys(state).forEach(id => { state[id] = on; apply(id); });
+}
+```
+
+---
+
+## 7. HTML File Structure
+
+Always produce a single self-contained HTML file with:
+- IBM Plex Mono from Google Fonts
+- Embedded CSS for layout, panel styles, toggle animation
+- SVG diagram with: background + dot grid, zone separator, classes, enumerations, association lines, composition diamonds (opacity:0 default), legend bar
+- Optional sticky composition control panel on the left
+- Optional "Why Abstraction?" panel if inheritance is used
+
+---
+
+## 8. Legend Bar
+
+Always include at the bottom of the SVG:
+`[ plain line ] Association  [ ◆─── line ] Composition (◆ = whole end)  Multiplicity at both ends  italic = methods`
+
+---
+
+## 9. Output
+
+- Save to `/mnt/user-data/outputs/<system_name>_class_diagram.html`
+- Call `present_files` to share with user
+- Briefly describe: number of classes, enumerations, relationships, whether interactive panel is included
+- Do NOT reproduce the full SVG coordinate listing in chat
+
+---
+
+## 10. Common Pitfalls
+
+- **Prefer role enum over abstraction** — always document your reasoning when choosing inheritance
+- **Abstraction panel missing** — if abstract classes exist and the explanation panel is absent, add it
+- **Association class notation** — NEVER draw it as a plain class connected by a dependency arrow; ALWAYS use a dashed line from the midpoint of the association line
+- **Line passing through class body** — ALWAYS check that no polyline segment overlaps a class rectangle. After placing all classes, verify each association line's bounding coordinates do not fall within any class's (x, y, x+w, y+h). If they do, re-route to a different entry edge (e.g. right side instead of top) or detour around the outside.
+- **No enum dependency lines** — do NOT draw dashed arrows from enums to classes; the zone grouping is sufficient
+- **Stereotype readability** — when a class has a stereotype, ensure the header is tall enough (≥38px) for both stereotype and class name to be visible
+- Line crossings: route diagonals carefully; use L-shaped polylines when needed
+- Diamond placement: must sit exactly on the class boundary, not floating
+- Enum grouping: always separate from classes visually
+- Methods italic: never forget — it's the key visual distinction
+- Multiplicity both ends: never leave one end unlabeled
+- Font loading: always include Google Fonts import or fall back to `monospace`
+
+## Hebrew Language Guidelines (שפה מגדרית נייטרלית)
+
+When labels, names, actors, roles, or any text in the diagram are written in Hebrew, follow these rules:
+
+### Use Male Form as Default
+Always use the **male grammatical form** (זכר) when referring to people, roles, actors, classes, or participants — even when the role is traditionally associated with a specific gender.
+
+**Examples of correct usage:**
+- ✅ רופא (not אחות for a nurse role — use אח)
+- ✅ אח (nurse, male form)
+- ✅ מטופל (not מטופלת)
+- ✅ לקוח (not לקוחה)
+- ✅ מנהל (not מנהלת)
+- ✅ עובד (not עובדת)
+- ✅ משתמש (not משתמשת)
+- ✅ סטודנט (not סטודנטית)
+
+**Examples of stereotypic writing to avoid:**
+- ❌ רופא ואחות — implies doctor=male, nurse=female
+- ❌ מזכירה — use מזכיר instead
+- ❌ אחות — use אח instead
+
+### Rule Summary
+> When in doubt, use the male form. This ensures gender neutrality and avoids reinforcing occupational gender stereotypes in diagram content.