@orderful/droid 0.47.0 → 0.48.0

package/.claude-plugin/plugin.json

@@ -23,6 +23,7 @@
     "./src/tools/droid/skills/droid/SKILL.md",
     "./src/tools/droid/skills/droid-bootstrap/SKILL.md",
     "./src/tools/edi-schema/skills/edi-schema/SKILL.md",
+    "./src/tools/excalidraw/skills/excalidraw/SKILL.md",
     "./src/tools/meeting/skills/meeting/SKILL.md",
     "./src/tools/pii/skills/pii/SKILL.md",
     "./src/tools/plan/skills/plan/SKILL.md",
@@ -41,6 +42,7 @@
     "./src/tools/comments/commands/comments.md",
     "./src/tools/droid/commands/setup.md",
     "./src/tools/edi-schema/commands/edi-schema.md",
+    "./src/tools/excalidraw/commands/excalidraw.md",
     "./src/tools/meeting/commands/meeting.md",
     "./src/tools/pii/commands/pii.md",
     "./src/tools/plan/commands/plan.md",

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @orderful/droid
 
+## 0.48.0
+
+### Minor Changes
+
+- [#299](https://github.com/Orderful/droid/pull/299) [`2c8ba4b`](https://github.com/Orderful/droid/commit/2c8ba4b222330bf6ade9b1fc4e727fe750a70203) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add excalidraw tool for generating Excalidraw diagrams in Obsidian brain vault
+
+### Patch Changes
+
+- [#300](https://github.com/Orderful/droid/pull/300) [`33b07c3`](https://github.com/Orderful/droid/commit/33b07c31ecc8f1d21661cc947e88a41555470206) Thanks [@frytyler](https://github.com/frytyler)! - Add --holistic flag to check commands (comments, brain, plan). When used, groups related comments into thematic clusters and responds cohesively instead of one-by-one, avoiding fractured responses when comments are part of the same train of thought.
+
 ## 0.47.0
 
 ### Minor Changes

package/dist/tools/brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions.",
   "author": {
     "name": "Orderful",

package/dist/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.4.1
+version: 0.4.2
 status: beta
 
 includes:

package/dist/tools/brain/skills/brain/SKILL.md

@@ -121,10 +121,12 @@ Full procedure: `references/workflows.md` § Adding
 
 ## Checking Comments
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
 Find `> @droid` comments in active doc and address each. Preserve original comment, add response below with `> @{user_mention}`.
 
+With `--holistic`: group related comments into thematic clusters and respond cohesively to each cluster instead of one-by-one. Unrelated comments still get individual responses. See `comments` skill for full holistic mode behaviour.
+
 Full procedure: `references/workflows.md` § Checking
 
 ## Cleaning Up Resolved Threads

package/dist/tools/brain/skills/brain/references/workflows.md

@@ -150,9 +150,11 @@ Detailed procedures for each brain operation.
 
 ## Checking
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
-**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` (or `/comments check --holistic`) instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+
+**Holistic mode (`--holistic`):** Pass the flag through to the comments skill. If using the fallback workflow below, apply the same principle: after step 4 (finding all comments), group related comments into thematic clusters and respond cohesively to each cluster at the last comment in the group. Unrelated comments get individual responses as normal.
 
 **Directionality:** The @mention is the **target**, not the author:
 

package/dist/tools/comments/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-comments",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
   "author": {
     "name": "Orderful",

package/dist/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.3.6
+version: 0.3.7
 status: beta
 
 includes:

package/dist/tools/comments/skills/comments/SKILL.md

@@ -82,6 +82,7 @@ When you find a `@droid` marker:
 
 - `/comments check` - Scan for AI markers and address each one
 - `/comments check {path}` - Scope to specific file or directory
+- `/comments check --holistic` - Read all comments, then respond cohesively to related clusters
 - `/comments cleanup` - Find resolved comment threads and remove them
 
 ## Behavior
@@ -101,6 +102,8 @@ When you find a `@droid` marker:
 
 #### Pass 2: Respond & Write
 
+**Default mode (no flag):** Respond to each comment individually, in order.
+
 1. For each comment, determine intent:
    - **Action request** ("do X", "add Y", "fix Z") → Execute the action
    - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`
@@ -109,6 +112,17 @@ When you find a `@droid` marker:
    - If `preserve_comments: true` → Keep the original `@droid` comment (add response below it)
    - If `preserve_comments: false` → Remove the original comment after addressing
 
+**Holistic mode (`--holistic`):** Respond cohesively to related comments instead of one-by-one.
+
+1. **Group related comments** — identify thematic clusters (comments exploring the same question, building on each other, or pulling in different directions on the same topic). Comments that are unrelated stay standalone.
+2. **For each cluster of related comments:**
+   - Synthesize the thread of thought — what is the user working through?
+   - Respond once at the **last comment in the cluster** with a cohesive answer that addresses the whole group
+   - Earlier comments in the cluster get a brief forward-reference: `> @{user_mention} Addressed below with the related comments.`
+   - The synthesized response should feel like engaging with a complete idea, not stitching together fragments
+3. **For standalone (unrelated) comments:** Respond individually, same as default mode
+4. **Handle `preserve_comments`** the same as default mode
+
 ### On `/comments cleanup`:
 
 1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved

package/dist/tools/excalidraw/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-excalidraw",
+  "version": "0.1.0",
+  "description": "Generate Excalidraw diagrams from conversation context and save them to your Obsidian brain vault. Requires brain tool configured, Obsidian, and the Excalidraw plugin.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "excalidraw"
+  ],
+  "skills": [
+    "./skills/excalidraw/SKILL.md"
+  ],
+  "commands": [
+    "./commands/excalidraw.md"
+  ]
+}

package/dist/tools/excalidraw/TOOL.yaml

@@ -0,0 +1,16 @@
+name: excalidraw
+description: "Generate Excalidraw diagrams from conversation context and save them to your Obsidian brain vault. Requires brain tool configured, Obsidian, and the Excalidraw plugin."
+version: 0.1.0
+status: experimental
+
+includes:
+  skills:
+    - name: excalidraw
+      required: true
+  commands:
+    - name: excalidraw
+      is_alias: false
+  agents: []
+
+dependencies:
+  - brain

package/dist/tools/excalidraw/commands/excalidraw.md

@@ -0,0 +1,34 @@
+---
+name: excalidraw
+description: "Generate Excalidraw diagrams in your Obsidian brain vault"
+argument-hint: "[{description} | check]"
+---
+
+# /excalidraw
+
+**User invoked:** `/excalidraw $ARGUMENTS`
+
+**Your task:** Invoke the **excalidraw skill** with these arguments.
+
+## Usage
+
+```
+/excalidraw {description}    # Generate a new diagram from context
+/excalidraw check            # Review changes in the active drawing
+```
+
+## Examples
+
+- `/excalidraw flow chart of the auth system` → Generate an auth flow diagram
+- `/excalidraw architecture for the orders service` → Generate a system architecture diagram
+- `/excalidraw ER diagram for orders and products` → Generate an entity relationship diagram
+- `/excalidraw check` → Read the active drawing and describe what's in it
+
+## Notes
+
+- Diagrams are saved to your Obsidian brain vault as `.excalidraw.md` files
+- Requires the brain tool configured with a `brain_dir`
+- Requires Obsidian with the Excalidraw plugin installed
+- See the **excalidraw skill** for complete documentation
+
+**Reserved keywords:** `check`

package/dist/tools/excalidraw/skills/excalidraw/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: excalidraw
+description: "Generate Excalidraw diagrams from conversation context and write them to the Obsidian brain vault. Use when user says 'draw this', 'diagram this flow', 'visualize this architecture', 'sketch this out', or '/excalidraw'. Also '/excalidraw check' to review changes in the active drawing."
+argument-hint: "[{description} | check]"
+allowed-tools: [Read, Write, Glob, Bash]
+---
+
+# Excalidraw
+
+Generate `.excalidraw.md` diagrams from conversation context — architecture diagrams, flow charts, system overviews, entity relationships. Files land in the brain vault and open directly in Obsidian's Excalidraw plugin.
+
+## Hard Dependencies
+
+This tool requires **all three** of the following:
+
+| Dependency | Why |
+|-----------|-----|
+| **brain tool configured** | Uses `brain_dir` for file placement |
+| **Obsidian** | Files use `.excalidraw.md` — Obsidian-specific format |
+| **Excalidraw plugin for Obsidian** | Required to render `.excalidraw.md` files |
+
+**Dependency check (run first, every time):**
+
+```bash
+droid config --get tools.brain
+```
+
+Parse the JSON output. If `brain_dir` is missing or empty, **stop and inform the user:**
+
+> The excalidraw tool requires the brain tool to be configured with a `brain_dir`. Run `droid config --set tools.brain.brain_dir=/path/to/vault` to configure it. You also need Obsidian with the Excalidraw plugin installed to open the generated files.
+
+Do not proceed until `brain_dir` is confirmed.
+
+## Commands
+
+**Reserved keywords:** `check`
+
+| Command | Action |
+|---------|--------|
+| `/excalidraw {description}` | Generate a new diagram from conversation context |
+| `/excalidraw check` | Review changes in the active drawing |
+
+## `/excalidraw {description}`
+
+1. **Check dependencies** — run `droid config --get tools.brain`, abort if `brain_dir` not set
+2. **Analyse context** — read the conversation to understand what to diagram. If unclear, ask what the user wants visualised
+3. **Pick a layout style** — flow chart, architecture, entity relationship, or concept map (see `references/element-templates.md` § Layout Styles)
+4. **Propose colour assignments** — before generating, present the user with a short table mapping each colour to a logical group in the diagram (e.g., "Blue = API services, Green = data stores, Orange = external systems"). Ask if they'd like to adjust. This ensures the legend is meaningful, not arbitrary.
+5. **Determine file placement:**
+   - If there's an active brain doc in the session, place the `.excalidraw.md` next to it (same directory, matching name prefix)
+   - Otherwise, place in `{brain_dir}/0-Inbox/diagrams/`
+6. **Create the target directory** if it doesn't exist:
+   ```bash
+   mkdir -p "{target_directory}"
+   ```
+7. **Generate the `.excalidraw.md` file** — see `references/format-spec.md` for the exact file format, `references/element-templates.md` for element JSON templates and the colour palette. **Always include a colour legend** in the bottom-left corner of the canvas (see `references/element-templates.md` § Colour Legend)
+8. **Write the file** using the Write tool
+9. **Emit an Obsidian link:**
+   ```
+   obsidian://open?vault={vault_name}&file={url-encoded-relative-path}
+   ```
+   Where `vault_name` = last path component of `brain_dir` (strip trailing slashes), and `relative_path` is the file path relative to `brain_dir`.
+
+## `/excalidraw check`
+
+1. **Find the active drawing** — the most recently discussed or generated `.excalidraw.md` file in the session. If none, search `{brain_dir}` for recently modified `.excalidraw.md` files and ask which one
+2. **Read the file** using the Read tool and parse the JSON from the `%%` block (that's the plugin's working copy)
+3. **Extract all elements** and build a mental model of the diagram:
+   - List all boxes/rectangles with their text content and colours
+   - List all arrows and what they connect
+   - List all standalone text labels
+   - Note spatial grouping (what's near what)
+4. **Summarise what you see** — describe the diagram in plain language
+5. **If you generated the original:** compare against what you wrote and call out what the user added, moved, removed, or changed
+6. **Offer next steps:** add more elements, reflect changes into a brain doc, or flesh out specific elements
+
+**Tips for Check:**
+- Focus on content and relationships, not pixel positions
+- Call out new elements by name: "You added a 'Redis Cache' box between the API and DB"
+- If the user added sticky notes, treat them like comments — respond to them
+- If the diagram diverged significantly, offer to regenerate with the new structure as baseline
+
+## File Placement Rules
+
+| Situation | Target directory |
+|-----------|-----------------|
+| Active brain doc in session | Same directory as the brain doc |
+| No active brain doc | `{brain_dir}/0-Inbox/diagrams/` |
+
+File name: use a kebab-case slug from the diagram description (e.g., `auth-flow.excalidraw.md`).
+
+## When NOT to Use
+
+- User wants a polished presentation diagram (suggest FigJam/Figma instead)
+- Simple lists or tables that don't benefit from spatial layout
+
+## Reference Files
+
+- `references/format-spec.md` — `.excalidraw.md` file format specification
+- `references/element-templates.md` — Element JSON templates, colour palette, sizing guidelines

package/dist/tools/excalidraw/skills/excalidraw/references/element-templates.md

@@ -0,0 +1,336 @@
+# Element Templates and Colour Palette
+
+## Common Properties (all elements)
+
+Every element must include these fields:
+
+```json
+{
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+**Element ID convention:** Increment `index` for each element: `"a0"`, `"a1"`, `"a2"`, etc. Use short unique alphanumeric strings for `id` fields (e.g., `"box_api"`, `"text_api"`, `"arrow_api_db"`).
+
+## Rectangle (container)
+
+```json
+{
+  "type": "rectangle",
+  "id": "box_unique_id",
+  "x": 0, "y": 0,
+  "width": 260, "height": 120,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "#d0ebff",
+  "fillStyle": "solid",
+  "strokeWidth": 2,
+  "roundness": { "type": 3 },
+  "boundElements": [
+    { "type": "text", "id": "text_for_this_box" }
+  ],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Text (bound to container)
+
+Bound text lives inside a rectangle. The `containerId` on the text and the matching `boundElements` on the rectangle must reference each other.
+
+```json
+{
+  "type": "text",
+  "id": "text_for_this_box",
+  "x": 10, "y": 10,
+  "width": 240, "height": 100,
+  "text": "Service Name\n\nHandles auth\nManages sessions",
+  "fontSize": 16,
+  "fontFamily": 1,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "containerId": "box_unique_id",
+  "originalText": "Service Name\n\nHandles auth\nManages sessions",
+  "autoResize": true,
+  "lineHeight": 1.25,
+  "hasTextLink": false,
+  "rawText": "",
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a1",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Text (standalone — titles, labels)
+
+Same as bound text but with `"containerId": null` and no parent rectangle reference.
+
+```json
+{
+  "type": "text",
+  "id": "title_text",
+  "x": 100, "y": 20,
+  "width": 400, "height": 40,
+  "text": "My Architecture Diagram",
+  "fontSize": 28,
+  "fontFamily": 1,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "containerId": null,
+  "originalText": "My Architecture Diagram",
+  "autoResize": true,
+  "lineHeight": 1.25,
+  "hasTextLink": false,
+  "rawText": "",
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Arrow
+
+For connected arrows, `startBinding` and `endBinding` must reference the source and target element IDs. The `points` array defines the arrow path relative to the arrow's `x`/`y` origin.
+
+```json
+{
+  "type": "arrow",
+  "id": "arrow_unique_id",
+  "x": 260, "y": 60,
+  "width": 80, "height": 0,
+  "strokeColor": "#868e96",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 2,
+  "roundness": { "type": 2 },
+  "startBinding": { "elementId": "source_box_id", "focus": 0, "gap": 5 },
+  "endBinding": { "elementId": "target_box_id", "focus": 0, "gap": 5 },
+  "startArrowhead": null,
+  "endArrowhead": "arrow",
+  "points": [[0, 0], [80, 0]],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a3",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+For vertical arrows, adjust `height` instead of `width` and set points accordingly (e.g., `[[0, 0], [0, 80]]`).
+
+## Sticky Note
+
+A sticky note is a rectangle with bound text that auto-resizes to fit content. Useful for annotations, callouts, and concept maps.
+
+```json
+{
+  "type": "rectangle",
+  "id": "note_unique_id",
+  "x": 0, "y": 0,
+  "width": 200, "height": 80,
+  "strokeColor": "#e8590c",
+  "backgroundColor": "#ffe8cc",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "roundness": { "type": 3 },
+  "customData": { "legacyTextWrap": true },
+  "boundElements": [
+    { "type": "text", "id": "note_text_id" }
+  ],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a4",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+With matching bound text (same pattern as bound text above, with `"containerId": "note_unique_id"`).
+
+## Colour Palette
+
+Use Excalidraw's built-in colours for consistency:
+
+| Purpose | `strokeColor` | `backgroundColor` |
+|---------|--------------|------------------|
+| Primary / highlighted | `#2f9e44` | `#b2f2bb` (green) |
+| Secondary | `#1971c2` | `#d0ebff` (blue) |
+| Tertiary | `#e8590c` | `#ffe8cc` (orange) |
+| Neutral / supporting | `#868e96` | `#e9ecef` (grey) |
+| Warning / attention | `#e03131` | `#ffc9c9` (red) |
+| Purple / alternate | `#6741d9` | `#d0bfff` (purple) |
+| Labels / arrows | `#868e96` | `transparent` |
+| Title text | `#1e1e1e` | `transparent` |
+
+**Colour grouping rule:** Use one colour per logical group (e.g., all API services blue, all data stores green). Before generating, propose the colour assignments to the user so they can adjust. This ensures the legend is meaningful, not arbitrary.
+
+## Colour Legend
+
+**Every diagram must include a colour legend.** Place it in the bottom-left corner of the canvas, below and to the left of the main diagram content.
+
+The legend is a vertical stack of small colour swatches (rectangles) with labels explaining what each colour represents in this specific diagram. Only include colours that are actually used.
+
+```
+┌──────────────────┐
+│  Legend           │  ← title text (fontSize: 16, bold)
+│                   │
+│  ■ API Services   │  ← small coloured rectangle + label
+│  ■ Data Stores    │
+│  ■ External       │
+│  ■ Infrastructure │
+└──────────────────┘
+```
+
+**Implementation:** Use a group of elements:
+- One standalone title text element ("Legend", fontSize: 16)
+- For each colour: a small rectangle (30x20px) + standalone text label to its right
+- Stack vertically with 8px gap between rows
+- Position below the main diagram content with ~60px margin
+
+Example swatch element:
+```json
+{
+  "type": "rectangle",
+  "id": "legend_swatch_blue",
+  "x": 100, "y": 600,
+  "width": 30, "height": 20,
+  "strokeColor": "#1971c2",
+  "backgroundColor": "#d0ebff",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "roundness": { "type": 3 }
+}
+```
+
+With a matching label:
+```json
+{
+  "type": "text",
+  "id": "legend_label_blue",
+  "x": 140, "y": 600,
+  "width": 120, "height": 20,
+  "text": "API Services",
+  "fontSize": 14,
+  "fontFamily": 1,
+  "textAlign": "left",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "containerId": null
+}
+```
+
+Repeat for each colour used in the diagram, incrementing y by 28px per row.
+
+## Sizing Guidelines
+
+| Element | Recommended size |
+|---------|-----------------|
+| Box width | 200–300px (varies by text length) |
+| Box height | 80–160px (varies by content lines) |
+| Horizontal gap between boxes | 80–120px |
+| Vertical gap between rows | 60–100px |
+| Title font size | 28 |
+| Box text font size | 16–20 |
+| Label font size | 14 |
+
+**Text width estimate:** ~8px per character at `fontSize: 16`
+
+**Arrow labels:** Place as standalone text near the arrow midpoint.
+
+## Layout Style Guidance
+
+### Flow Chart
+For processes, workflows, request lifecycles. Arrange top-to-bottom or left-to-right with directional arrows. Each step is a box; decisions can use diamond shapes (rotated rectangles).
+
+### Architecture Diagram
+For system components, services, layers. Use grouped boxes with labels, arrows showing data flow between services. Group related services with a larger background rectangle.
+
+### Entity Relationship
+For data models, schemas, relationships. Boxes represent entities with field lists inside. Lines (not arrows) show relationships; label the line with cardinality (1:N, etc.).
+
+### Concept Map
+For brainstorming, exploring ideas. Loose arrangement, grouped by theme. Connecting lines with labels, sticky notes for annotations. Less rigid than a flow chart.
+
+## Tips
+
+- Keep text concise — bullet points over paragraphs
+- Add a title text element at the top of the canvas
+- For large diagrams, organise in clear rows/columns — the user can rearrange in Excalidraw
+- Start elements at coordinates (100, 100) or higher to leave canvas margin