Update to Simulator.Company

{
  "description": "Simulator.Company graph structure specialist. Use when the user wants to build, edit, analyze, inspect, or ask questions about business process graphs, flowcharts, algorithms, actors (nodes), links (edges), or layers (visual views) in Simulator.Company.\nTrigger on any of these intents: — Creating: \"create graph\", \"build flowchart\", \"new diagram\", \"add actor\",\n  \"add block to graph\", \"create algorithm\", \"draw flowchart\", \"digital twin\",\n  \"create process on graph\", \"build process diagram\", \"FlowchartBlock\",\n  \"startStop\", \"predefinedProcess\".\n— Editing: \"edit graph\", \"update actor\", \"rename node\", \"change color\",\n  \"move actor\", \"add step to flowchart\", \"modify diagram\", \"restructure\n  process\", \"add edge\", \"remove link\", \"reorder steps\", \"update layer\".\n— Syncing: \"push graph\", \"pull graph\", \"sync graph\", \"push changes\",\n  \"apply edits to layer\".\n— Querying / analysis: \"what actors are on this layer\", \"show me the graph\",\n  \"who is connected to\", \"find actor\", \"list nodes\", \"describe the process\",\n  \"analyze the flowchart\", \"how many steps\", \"what links exist\",\n  \"search layer\", \"inspect actor\", \"get actor\", \"explore graph\".\n— Layer / connection operations: \"add to layer\", \"connect actors\",\n  \"link nodes\", \"organize on layer\", \"move actors between layers\",\n  \"explore graph connections\".\n\nCovers the full actor lifecycle (create, update, delete, search), all graph traversal operations, layer management, and FlowchartBlock diagram creation.\n",
  "included_files": [
    {
      "relative_path": "template.yaml",
      "size_in_bytes": 354
    }
  ],
  "name": "simulator-graph",
  "skill_md_contents": "---\nname: simulator-graph\ndescription: >\n  Simulator.Company graph structure specialist. Use when the user wants to\n  build, edit, analyze, inspect, or ask questions about business process\n  graphs, flowcharts, algorithms, actors (nodes), links (edges), or layers\n  (visual views) in Simulator.Company.\n\n  Trigger on any of these intents:\n  — Creating: \"create graph\", \"build flowchart\", \"new diagram\", \"add actor\",\n    \"add block to graph\", \"create algorithm\", \"draw flowchart\", \"digital twin\",\n    \"create process on graph\", \"build process diagram\", \"FlowchartBlock\",\n    \"startStop\", \"predefinedProcess\".\n  — Editing: \"edit graph\", \"update actor\", \"rename node\", \"change color\",\n    \"move actor\", \"add step to flowchart\", \"modify diagram\", \"restructure\n    process\", \"add edge\", \"remove link\", \"reorder steps\", \"update layer\".\n  — Syncing: \"push graph\", \"pull graph\", \"sync graph\", \"push changes\",\n    \"apply edits to layer\".\n  — Querying / analysis: \"what actors are on this layer\", \"show me the graph\",\n    \"who is connected to\", \"find actor\", \"list nodes\", \"describe the process\",\n    \"analyze the flowchart\", \"how many steps\", \"what links exist\",\n    \"search layer\", \"inspect actor\", \"get actor\", \"explore graph\".\n  — Layer / connection operations: \"add to layer\", \"connect actors\",\n    \"link nodes\", \"organize on layer\", \"move actors between layers\",\n    \"explore graph connections\".\n\n  Covers the full actor lifecycle (create, update, delete, search), all graph\n  traversal operations, layer management, and FlowchartBlock diagram creation.\n---\n\n> **Curated tool names (v2 server).** Place/remove nodes & edges on a layer with `manageLayerActors`; read a layer's contents — prefer `getLayerActorsPaginated` (page nodes then edges; works for any size) or `getAllLayerPlacements`, falling back to `getLayerActors` only for small layers (it loads the whole layer in one call and is rejected with a \"Layer is too large\" 400 above the size cap); create nodes with `createActor` (one call each — there is no `createActors`); links with `createLink` / `massLink`; edge CRUD with `getEdge` / `updateEdge` / `deleteEdge` / `existLink` / `deleteEdgesByNodes`; edge types with `getEdgeTypes`. Traverse from an actor with `getRelatedActors` (type = linked | parents | children; hierarchy link type by default; paginated/filterable/sortable), `getLinkedActors` (directly-linked actors across edge types, with `edgeTypes`/`withSystem`/`pinned` filters), and `getActorLinks` (every edge of an actor). Layer ops: `layerStats` (node/edge counts), `existLayerElement` (is a node/edge on a layer — dedup before placing), `moveActors` (move ≤10 actors between layers), `cleanGraphLayer` (wipe a layer — destructive). See `/simulator` for the full list.\n\n# Simulator.Company Graph Builder\n\nYou are a specialist in building graph-based business process structures in\nSimulator.Company using the `simulator` MCP server.\n\n> **Reading \"the nodes on a graph/layer\"?** Read THAT layer's placements with\n> `getLayerActorsPaginated(actorId=\"<layerActorId>\")` (paginated; works at any size) — do NOT\n> `searchActors`/`filterActors` across the workspace (that returns unrelated chats, reports and\n> other forms). When the user pastes a URL like\n> `.../graph/<graphActorId>/layers/<layerActorId>`, the layer `actorId` is the **last UUID, the\n> segment after `/layers/`**. See **Layer Operations** below for the full recipe.\n\n---\n\n## Core Concepts & Glossary\n\n| Term            | Description                                                                                          |\n|-----------------|------------------------------------------------------------------------------------------------------|\n| **Actor**       | Graph node. Created from a Form template. Has id, title, color, data fields.                         |\n| **Form**        | Actor template/type. Defines shape and behavior. All system form names are in the catalog below.     |\n| **Graph actor** | An actor with `formName=\"Graphs\"` — the logical container for a diagram.                             |\n| **Layer actor** | An actor with `formName=\"Layers\"` — the visual canvas where nodes are placed at (x, y).              |\n| **Graph file**  | A YAML file named `<layerId>.yaml` in the current working directory describing the full layer state. |\n| **laId**        | Layer Actor ID. Assigned by `manageLayerActors` when an actor is placed on a layer.                        |\n\n---\n\n## Primary Workflow — File-Based Graph Building\n\n> **This is the preferred approach for all graph creation and editing.**\n> Use the low-level MCP tools (createActor, manageLayerActors, etc.) only for\n> one-off queries or when specifically requested.\n\n### Step 1 — Create Graph + Layer actors\n\nEvery diagram needs two actors linked together. Do this once per new diagram.\n\n```\n// 1. Create the graph container\ncreateActor(formName=\"Graphs\", title=\"<diagram name>\")\n→ save returned id as graphId\n\n// 2. Create the visual canvas (layer)\ncreateActor(formName=\"Layers\", title=\"<diagram name>\")\n→ save returned id as layerId\n\n// 3. Link graph → layer\ncreateLink(source=\"<graphId>\", target=\"<layerId>\")\n```\n\nIf `layerId` is already known (from user message or context) — skip this step entirely.\n\n---\n\n### Step 2 — Prepare the Graph File\n\n**Option A — New empty layer:** write `<layerId>.yaml` from scratch:\n\n```yaml\nlayerId: \"<layerId>\"\nactors:\n  - id: start\n    title: \"Start\"\n    formName: \"Start / Stop\"\n    color: \"#17B26A\"\n    position:\n      x: 0\n      y: 0\n  - id: process1\n    title: \"Process Step\"\n    formName: \"Process\"\n    color: \"#539fdf\"\n    description: \"Does something important\"\n    position:\n      x: 0\n      y: 130\n  - id: end\n    title: \"End\"\n    formName: \"Start / Stop\"\n    color: \"#F04438\"\n    position:\n      x: 0\n      y: 260\nedges:\n  - source: start\n    target: process1\n  - source: process1\n    target: end\n```\n\n**Option B — Existing layer:** pull current state into a file, then edit it:\n\n```\npullGraphFile(layerId=\"<layerId>\")\n→ creates <layerId>.yaml with all current actors and edges\n→ open and edit the file as needed\n```\n\n---\n\n### Step 3 — Push the File to Server\n\n```\npushGraphFile(layerId=\"<layerId>\")\n```\n\nThe server will:\n\n- **Create** actors whose `id` is a local name (e.g. `start`, `process1`) → replaces local ids with server UUIDs in the\n  file\n- **Update** actors whose `id` is already a UUID — if title/color/description changed\n- **Delete from layer** actors present on server but missing from file\n- **Create** missing edges (links + layer placement)\n- **Delete from layer** edges present on server but missing from file\n- **Update positions** for actors whose `position` changed\n\nAfter push the file is updated in place with all server UUIDs.\n\n---\n\n### Editing an Existing Graph\n\n```\n// 1. Pull current state\npullGraphFile(layerId=\"<layerId>\")\n\n// 2. Edit <layerId>.yaml — add/remove/modify actors and edges\n\n// 3. Push changes\npushGraphFile(layerId=\"<layerId>\")\n```\n\n---\n\n## Styling edges — colour, dash, width, curve\n\nAn edge placement's `data.layerSettings` controls how the line renders, applied **when\nyou place the edge** via `manageLayerActors`:\n\n```\nmanageLayerActors(actorId=\"<layerId>\", items=[\n  { action:\"create\", data:{ id:\"<edgeId>\", type:\"edge\", laIdSource:<laA>, laIdTarget:<laB>,\n      layerSettings:{ lineStyle:\"dashed\", color:\"#E8924E\", width:2, curveStyle:\"straight\" } } }\n])\n```\n\n- `lineStyle` — `solid` | `dashed` | `dotted`\n- `curveStyle` — `curved` | `rounded` | `roundedDownward` | `straight`\n- `color` — 6-digit hex `#RRGGBB` (e.g. `#9AA5B1` grey, `#E8924E` orange) — no 3-digit shorthand, no alpha\n- `width` — stroke width, an integer ≥ 1 (e.g. `2`)\n- `routingPoints` — optional array of `{ w:number, d:number }` waypoints for manual edge routing\n\nThese are the pong-server edge `layerSettings` keys (`saveEdgeLayerSettingsSchema`); on\n`manageLayerActors` they ride through unvalidated, so use the canonical types above — an integer\n`width` and a 6-digit hex `color`. Use it to encode meaning in edges — coloured solid = data/structure\nflows, grey dashed = logical cross-links. To change an edge already on the layer, delete its placement\nand re-create it with the new `layerSettings` (re-creating without deleting first adds a duplicate).\n\n---\n\n## Custom Form Data — Populating `actors.data`\n\nWhen the user specifies a **custom `formId`** (or a non-system `formName`) for one or more actors, you **must** fetch the form schema before writing the YAML file or pushing to the server.\n\n### When to trigger\n\n- User explicitly provides a `formId` UUID for an actor.\n- User names a form that is **not** in the system Form Catalog above (i.e. it is a user-created form).\n- User says \"use form X for this actor\" where X is an ID or an unfamiliar name.\n\n### Step-by-step\n\n```\n// 1. Fetch form schema\ngetForm(formId=\"<formId>\")\n→ returns form object with fields list\n\n// 2. Inspect the returned fields array — each field has:\n//    { id, name, title, type, defaultValue, ... }\n\n// 3. Build actors.data from those fields:\n//    - Include every field that the user provided a value for.\n//    - For fields the user did NOT mention: include the field with its\n//      defaultValue if one exists; omit the field entirely otherwise.\n//    - Use the field's `name` (not `title`) as the key in data.\n\n// 4. Write the actor entry in the YAML with the populated data block.\n```\n\n### YAML example with custom form data\n\n```yaml\nactors:\n  - id: my_actor\n    title: \"My Custom Actor\"\n    formId: \"abc-123-uuid\"   # custom form — data was populated from getForm\n    color: \"#539fdf\"\n    position:\n      x: 0\n      y: 130\n    data:\n      status: \"active\"        # field name from form schema, value from user\n      priority: 1             # field name from form schema, value from user\n      category: \"\"            # field present in schema, no default, user left blank\n```\n\n### Rules\n\n- **Always call `getForm` before writing `data`** when a custom formId is involved — never guess field names.\n- If the form has no fields, omit `data` entirely.\n- Do **not** add `data` for system forms (those in the Form Catalog) — the server auto-injects their shape/view/blockId.\n- If the user specifies only some field values, fill the rest from `defaultValue`; omit fields with no default and no user value.\n- After `getForm`, confirm the field list with the user if the form has many fields and the user has not specified values — ask which fields matter.\n\n---\n\n## Text-label nodes\n\nRender an actor's `description` as borderless text (no node circle) by placing it with\n`isTextNode` in its `data.layerSettings` on `manageLayerActors`:\n\n```\ncreateActor(formId=3279, description=\"Section title\")          // the text lives in `description`\nmanageLayerActors(actorId=\"<layerId>\", items=[\n  { action:\"create\", data:{ id:\"<actorId>\", type:\"node\", position:{x:0,y:0},\n      layerSettings:{ isTextNode:true, textNodeScale:1.5, textWidth:320, textHeight:44 } } }\n])\n```\n\n- `isTextNode:true` — render the node as a text label\n- `textNodeScale` — font-size multiplier\n- `textWidth` / `textHeight` — text-box size in px. **Scale it to the text** — roughly\n  `16·scale` px per character wide and `28·scale` px per line tall — or large/long text wraps\n  and breaks mid-word.\n\nGood for section titles, axis labels and annotations on a graph. To change it, delete the\nplacement and re-create it with the new `layerSettings`.\n\n---\n\n## Graph File Format Reference\n\n```yaml\nlayerId: \"<uuid>\"           # layer actor UUID\n\nactors:\n  - id: local_name          # local id for new actors; UUID for existing ones\n    title: \"My Block\"\n    formName: \"Process\"     # use formName from the catalog (preferred over formId)\n    color: \"#539fdf\"        # hex color string — always set for flowchart blocks\n    description: \"...\"      # optional\n    picture: \"\"             # optional\n    position:\n      x: 0                  # horizontal position on layer\n      y: 130                # vertical position on layer\n\nedges:\n  - source: local_name_or_uuid   # references actor id field\n    target: local_name_or_uuid\n    source_title: \"My Block\"     # informational only, not sent to server\n    target_title: \"Other Block\"\n```\n\n**Rules:**\n\n- `id` values are local references used only within the file for edge wiring.\n  After `pushGraphFile` all local ids are replaced with server UUIDs.\n- Do **not** include `data` for system forms — the server auto-injects shape/view.\n- `formName` takes priority over `formId` when both are present.\n- `edges` reference actor `id` fields (local names work, they are resolved at push time).\n\n---\n\n## Custom image nodes — any drawing, icon or shape (napkin)\n\nTo put **any image** on a graph — a line, a circle, a rectangle, an icon, a logo, a\nhand-drawn shape, a small diagram, anything a PNG/SVG can hold — create an actor with a\n`pictureObject`: a custom image rendered AS the node body (the backend's \"napkin\"\nelement), instead of a standard form node. A divider line is just one use.\n\n```\ncreateActor(formId=3279, color=\"#F04438\", pictureObject={\n  img:    \"data:image/png;base64,iVBORw0KGgo…\",   // a PNG/SVG data URI\n  width:  800,                                     // display size on the canvas\n  height: 8,\n  type:   \"napkin\"\n}, contextLayerId=\"<layerId>\")\n```\n\n- `img` — the image as a data URI (e.g. a thin red PNG to draw a divider line).\n- `width` / `height` — display size in px. The image is anchored at its **centre** and\n  keeps the source's **aspect ratio** (set `width`; `height` follows), so for a thin line\n  make the source PNG wide-and-short.\n- `type: \"napkin\"` — the custom-image element kind.\n\nA classic use is an ADAM/EVE-style horizontal divider: a wide, short red dashed PNG\nplaced across the middle of the layer. Change a node's image later with the same\n`pictureObject` on `updateActor`.\n\n---\n\n## Layout Algorithm — Coordinate Calculation\n\n**Never hardcode coordinates.** Calculate using dagre/Sugiyama layout.\n\n### Node Sizes\n\n```\nSIZES = {\n  \"Start / Stop\":         { w: 200, h: 50  },\n  \"Process\":              { w: 200, h: 50  },\n  \"Predefined Process\":   { w: 200, h: 100 },\n  \"Decision\":             { w: 200, h: 100 },\n  \"Data\":                 { w: 200, h: 60  },\n  \"Document\":             { w: 200, h: 70  }\n}\ndefault:                  { w: 200, h: 50  }\n```\n\n### Rank Assignment (BFS from start node)\n\n```\nrank[start] = 0\nfor each edge source → target:\n  rank[target] = max(rank[target] ?? 0, rank[source] + 1)\n```\n\n### Gap Calculation\n\n```\nnodeSep(rank) = max(max_w_in_rank * 0.3, 60)    // horizontal gap between centers\nrankSep(r)    = max(max_h_in_rank(r) * 1.2, 80) // vertical gap between rows\n```\n\n### Y Coordinates (top → down)\n\n```\ny[rank_0] = 0\ny[rank_n] = y[rank_n-1] + max_h(rank_n-1)/2 + rankSep(rank_n-1) + max_h(rank_n)/2\n```\n\n### X Coordinates (center each row)\n\n```\nfor each rank with N nodes:\n  center_to_center = max_w_in_rank + nodeSep\n  total_span       = (N - 1) * center_to_center\n  x[node_i]        = -total_span / 2 + i * center_to_center\n```\n\n### Examples\n\n- **3 Start/Stop blocks in a row** (w=200, nodeSep=60, c2c=260) → x = [-260, 0, 260]\n- **Start/Stop(h=50) → Process(h=50)** → y[rank_1] = 0+25+80+25 = 130\n- **Process(h=50) → Decision(h=100)** → y[rank_2] = 130+25+80+50 = 285\n\n---\n\n## Complete Example: Build a Flowchart\n\n```\n// Step 1 — Create Graph + Layer (skip if layerId already known)\ncreateActor(formName=\"Graphs\", title=\"Order Processing\")  → graphId\ncreateActor(formName=\"Layers\", title=\"Order Processing\")  → layerId\ncreateLink(source=\"<graphId>\", target=\"<layerId>\")\n\n// Step 2 — Write <layerId>.yaml\n```\n\n```yaml\nlayerId: \"<layerId>\"\nactors:\n  - id: start\n    title: \"Start\"\n    formName: \"Start / Stop\"\n    color: \"#17B26A\"\n    position: { x: 0, y: 0 }\n  - id: validate\n    title: \"Validate Order\"\n    formName: \"Process\"\n    color: \"#539fdf\"\n    position: { x: 0, y: 130 }\n  - id: check\n    title: \"Valid?\"\n    formName: \"Decision\"\n    color: \"#F79009\"\n    position: { x: 0, y: 285 }\n  - id: process\n    title: \"Process Payment\"\n    formName: \"Process\"\n    color: \"#539fdf\"\n    position: { x: 260, y: 440 }\n  - id: error\n    title: \"Return Error\"\n    formName: \"Process\"\n    color: \"#F04438\"\n    position: { x: -260, y: 440 }\n  - id: end\n    title: \"End\"\n    formName: \"Start / Stop\"\n    color: \"#17B26A\"\n    position: { x: 0, y: 595 }\nedges:\n  - source: start\n    target: validate\n  - source: validate\n    target: check\n  - source: check\n    target: process\n  - source: check\n    target: error\n  - source: process\n    target: end\n  - source: error\n    target: end\n```\n\n```\n// Step 3 — Push to server\npushGraphFile(layerId=\"<layerId>\")\n// → all actors created, edges drawn, file updated with server UUIDs\n```\n\n---\n\n## Form Catalog — All Available Form Names\n\nPass `formName` to `createActor` or in the graph YAML file.\nThe server resolves the name to ID automatically.\n\n### Graph & Layer\n\n| formName   | Usage                       |\n|------------|-----------------------------|\n| `\"Graphs\"` | Graph container actor       |\n| `\"Layers\"` | Layer (visual canvas) actor |\n\n### Flowchart Blocks\n\n> Always set `color` (hex string) for flowchart blocks.\n\n| formName               | Description                     |\n|------------------------|---------------------------------|\n| `\"Start / Stop\"`       | Start or end node               |\n| `\"Process\"`            | Process step                    |\n| `\"Decision\"`           | Decision diamond                |\n| `\"Predefined Process\"` | Predefined / subroutine process |\n| `\"Document\"`           | Document shape                  |\n| `\"Data\"`               | Data parallelogram              |\n| `\"Documents\"`          | Multi-document stack            |\n| `\"Stored Data\"`        | Stored data shape               |\n| `\"Off-page Reference\"` | Off-page connector              |\n| `\"Preparation\"`        | Preparation / initialization    |\n| `\"API Call\"`           | API call block                  |\n| `\"Manual Input\"`       | Manual input                    |\n| `\"Delay\"`              | Delay block                     |\n| `\"Database\"`           | Database cylinder               |\n| `\"Manual Operation\"`   | Manual operation                |\n| `\"Terminator\"`         | Oval terminator                 |\n| `\"Root Node\"`          | Root node                       |\n| `\"Null\"`               | Universal generic node          |\n| `\"Flowchart\"`          | Nested flowchart reference      |\n\n### Diagram Types\n\n| formName             | Description              |\n|----------------------|--------------------------|\n| `\"Petri Net\"`        | Petri net diagram        |\n| `\"Sequence Diagram\"` | Sequence diagram         |\n| `\"Actor Graph\"`      | Actor graph              |\n| `\"Mind Map\"`         | Mind map                 |\n| `\"Corezoid\"`         | Corezoid process diagram |\n\n### Corezoid Nodes\n\n| formName                          | Description         |\n|-----------------------------------|---------------------|\n| `\"Corezoid Start\"`                | Entry point         |\n| `\"Corezoid API Call\"`             | External API call   |\n| `\"Corezoid Condition\"`            | Condition / routing |\n| `\"Corezoid Code\"`                 | Code execution      |\n| `\"Corezoid Copy Task\"`            | Copy task           |\n| `\"Corezoid Modify Task\"`          | Modify task         |\n| `\"Corezoid Sum\"`                  | Aggregation / sum   |\n| `\"Corezoid Delay\"`                | Time delay          |\n| `\"Corezoid Database Call\"`        | DB call             |\n| `\"Corezoid Waiting for Callback\"` | Async wait          |\n| `\"Corezoid Call a Process\"`       | Sub-process call    |\n| `\"Corezoid Reply to Process\"`     | Reply to caller     |\n| `\"Corezoid Queue\"`                | Queue node          |\n| `\"Corezoid Get from Queue\"`       | Dequeue             |\n| `\"Corezoid Set Parameters\"`       | Set task parameters |\n| `\"Corezoid End: Success\"`         | Success terminal    |\n| `\"Corezoid End: Error\"`           | Error terminal      |\n| `\"Corezoid GIT Call\"`             | GIT call            |\n\n### AWS Services\n\n| formName                               | formName                   | formName                       |\n|----------------------------------------|----------------------------|--------------------------------|\n| `\"EC2\"`                                | `\"Lambda\"`                 | `\"RDS\"`                        |\n| `\"App Runner\"`                         | `\"EKS Cloud\"`              | `\"EKS Distro\"`                 |\n| `\"EFS\"`                                | `\"Client VPN\"`             | `\"Elastic Container Registry\"` |\n| `\"Certificate Manager\"`                | `\"Simple Queue Service\"`   | `\"Inspector\"`                  |\n| `\"GuardDuty\"`                          | `\"Data Pipeline\"`          | `\"Kinesis\"`                    |\n| `\"Key Management Service\"`             | `\"DynamoDB\"`               | `\"Elastic Kubernetes Service\"` |\n| `\"Secrets Manager\"`                    | `\"Elastic Load Balancing\"` | `\"Route 53\"`                   |\n| `\"ElastiCache\"`                        | `\"CloudWatch\"`             | `\"Transfer Family\"`            |\n| `\"Managed Streaming for Apache Kafka\"` | `\"Amplify\"`                | `\"Budgets\"`                    |\n| `\"Simple Storage Service\"`             | `\"Transit Gateway\"`        | `\"Network Firewall\"`           |\n| `\"OpenSearch Service\"`                 | `\"WAF\"`                    | `\"Virtual Private Cloud\"`      |\n| `\"Simple Notification Service\"`        | `\"API Gateway\"`            | `\"Transcribe\"`                 |\n| `\"Athena\"`                             | `\"QuickSight\"`             | `\"CloudFront\"`                 |\n| `\"Global Accelerator\"`                 | `\"Backup\"`                 | `\"DocumentDB\"`                 |\n| `\"Glue\"`                               | `\"RDS on VMware\"`          |                                |\n\n### AI / ML\n\n| formName              | Description               |\n|-----------------------|---------------------------|\n| `\"GPT\"`               | GPT model node            |\n| `\"Anthropic\"`         | Anthropic model node      |\n| `\"Grok\"`              | Grok model node           |\n| `\"SLM\"`               | Small language model      |\n| `\"Devin\"`             | Devin AI agent            |\n| `\"Black box (Mind)\"`  | Opaque mind component     |\n| `\"Black box (LLM)\"`   | Opaque LLM component      |\n| `\"Black box (Actor)\"` | Opaque actor component    |\n| `\"Black box (Seq)\"`   | Opaque sequence component |\n| `\"Grey box (Actor)\"`  | Semi-transparent actor    |\n| `\"Grey box (Mind)\"`   | Semi-transparent mind     |\n| `\"Grey box (LLM)\"`    | Semi-transparent LLM      |\n| `\"Grey box (Seq)\"`    | Semi-transparent sequence |\n\n### UML / OOP\n\n| formName      | Description   |\n|---------------|---------------|\n| `\"Class\"`     | UML class     |\n| `\"Interface\"` | UML interface |\n| `\"Component\"` | UML component |\n| `\"Package\"`   | UML package   |\n| `\"Artifact\"`  | UML artifact  |\n\n### Other\n\n| formName             | Description                 |\n|----------------------|-----------------------------|\n| `\"Human\"`            | Human participant           |\n| `\"Node\"`             | Generic network node        |\n| `\"Branch Node\"`      | Branch point                |\n| `\"White box\"`        | Transparent white container |\n| `\"Place\"`            | Physical location           |\n| `\"Token\"`            | Token / badge               |\n| `\"Flag\"`             | Flag marker                 |\n| `\"Program\"`          | Program block               |\n| `\"Current Position\"` | Current position marker     |\n| `\"Transition\"`       | State transition            |\n| `\"Stubnet\"`          | Stub network                |\n| `\"Marketplace\"`      | Marketplace node            |\n\n---\n\n## Low-Level MCP Tools (one-off operations)\n\nUse these for targeted queries, not for building graphs (use the file workflow instead).\nCall tools with **named arguments** (the curated v2 tools take typed params — there is no\nsingle `body` blob). A **layer is addressed by its layer-actor UUID** — the `actorId`\nargument of the layer tools below (the same id the file workflow calls the `layerId`).\n\n### Actor Operations\n\n```\ncreateActor(formName=\"Process\", title=\"Step\", color=\"#539fdf\")   // one actor per call — there is no createActors\ngetActor(actorId=\"<actorId>\")\ngetActorByRef(formId=<formId>, ref=\"<ref>\")\nupdateActor(formId=<formId>, actorId=\"<actorId>\", title=\"Updated\")\ndeleteActor(actorId=\"<actorId>\")                                 // one at a time — there is no bulk-actor delete\n```\n\n### Link (edge) Operations\n\n```\n// Single link. edgeTypeId defaults to the workspace hierarchy type when omitted —\n// pass it only for a different edge type (see getEdgeTypes).\ncreateLink(source=\"<a>\", target=\"<b>\")                  → edgeId\n\n// Up to 50 links in one call; each object's edgeTypeId is optional (same hierarchy default).\nmassLink(links=[{\"source\":\"<a>\",\"target\":\"<b>\"}, ...])\n\n// massLink/createLink create the logical edge only. To also show an edge on a layer,\n// place it with manageLayerActors (actorId = the layer-actor UUID):\nmanageLayerActors(actorId=\"<layerActorId>\", items=[{\"action\":\"create\",\"data\":{\"id\":\"<edgeId>\",\"type\":\"edge\",\"laIdSource\":<laA>,\"laIdTarget\":<laB>}}])\n\n// Edge LINE STYLE — put it in the placed edge's data.layerSettings.lineStyle\n// (solid | dashed | dotted; omit → solid). Use distinct styles for distinct\n// edge meanings (e.g. dashed = dependency, dotted = hint, solid = hierarchy):\nmanageLayerActors(actorId=\"<layerActorId>\", items=[{\"action\":\"create\",\"data\":{\"id\":\"<edgeId>\",\"type\":\"edge\",\"laIdSource\":<laA>,\"laIdTarget\":<laB>,\"layerSettings\":{\"lineStyle\":\"dashed\"}}}])\n// To CHANGE an edge's style, DELETE its placement then create it again — re-creating\n// without deleting first adds a DUPLICATE placement (the line is drawn twice).\n\n// existLink REQUIRES edgeTypeId (unlike createLink) — pass it explicitly to find/dedupe an edge by its endpoints:\nexistLink(source=\"<a>\", target=\"<b>\", edgeTypeId=<id>)  → edge id if it exists\ngetEdge(edgeId=\"<edgeId>\")\nupdateEdge(edgeId=\"<edgeId>\", name=\"New label\", pinned=true)     // fields: name, linkedActorId, curveStyle, pinned\ndeleteEdge(edgeId=\"<edgeId>\")\ndeleteEdgesByNodes(links=[{\"source\":\"<a>\",\"target\":\"<b>\",\"edgeTypeId\":<id>}])   // bulk delete by endpoints (1-200); edgeTypeId required per object\n```\n\n### Layer Operations\n\n**Reading \"the nodes/actors on a graph\" means reading THAT LAYER's placements — never a\nworkspace-wide search.** `searchActors` / `filterActors` without a layer constraint scan the\nwhole workspace and return unrelated actors (chats, daily reports, other forms) — they are the\nWRONG tool for \"what's on this graph/layer\". Use the layer-read tools below, addressing the\nlayer by its layer-actor UUID.\n\n**Getting the layer UUID from a pasted URL.** Simulator graph URLs look like:\n\n```\nhttps://<host>/actors_graph/<workspaceId>/graph/<graphActorId>/layers/<layerActorId>\n                            └ workspace ┘        └ graph root ┘         └ THE LAYER ┘\n```\n\n- The layer `actorId` is the **last UUID — the segment after `/layers/`**. Read it with the\n  tools below (e.g. `getLayerActorsPaginated(actorId=\"<layerActorId>\")`).\n- If the path ends at `/graph/<id>/<mode>` (mode = `layers`|`actors`|`trees`) with no\n  `/layers/` segment, that `<id>` is the layer/graph-folder to open.\n- The UUID after `/graph/` is the graph ROOT actor (a `Graphs`-form actor), not the canvas of\n  nodes — don't read it expecting the layer's members.\n\n```\n// READING A LAYER — default to the paginated read; it works for a layer of ANY size.\n// Start with layerStats to learn the counts, then page nodes and edges:\nlayerStats(actorId=\"<layerActorId>\")                     // node/edge counts — call first\ngetLayerActorsPaginated(actorId=\"<layerActorId>\", type=\"nodes\", limit=50, offset=0)  // walk offset until a short/empty page\ngetLayerActorsPaginated(actorId=\"<layerActorId>\", type=\"edges\", limit=50, offset=0)  // then the edges\ngetAllLayerPlacements(layerId=\"<layerActorId>\")          // nodes-only one-shot shortcut (engine tool, any size)\nsearchLayerActors(actorId=\"<layerActorId>\", query=\"...\")\n\n// getLayerActors is a SMALL-LAYER shortcut only — it loads the whole layer (nodes + edges)\n// at once and the backend REJECTS it with a 400 (\"Layer is too large (… nodes, … edges,\n// total: …). Maximum allowed: N.\") once nodes+edges exceed the size cap (~300). Do not reach\n// for it first to read a layer; if you do and hit that error, switch to getLayerActorsPaginated\n// (do NOT give up). `filter` keeps each page small.\ngetLayerActors(actorId=\"<layerActorId>\")                 // whole layer in one call — small layers only\nexistLayerElement(actorId=\"<layerActorId>\", id=\"<actorOrEdgeId>\", type=\"actor\")  // is a node/edge on the layer — dedupe before placing\nmoveActors(sourceActorId=\"<layerA>\", targetActorId=\"<layerB>\", items=[{\"actorId\":\"<a1>\"}])  // ≤10 actors between layers\ncleanGraphLayer(actorId=\"<layerActorId>\")                // wipe the layer (actors remain) — destructive\n```\n\n### Graph Traversal\n\n```\ngetRelatedActors(type=\"linked\", actorId=\"<actorId>\")  // type: \"linked\"|\"parents\"|\"children\"; defaults to the hierarchy link type\ngetActorLinks(actorId=\"<actorId>\")                    // every edge of an actor\ngetLinkedActors(actorId=\"<actorId>\")                  // directly-linked actors across edge types\n\n// Related actors filtered/ranked by an account balance, in one query:\n// \"the actors related to X whose account N balance is > / < a value\".\nfilterActors(formId=<formId>, linkedToActorId=\"<anchorActorId>\",\n             accountNameId=\"<nameId>\", currencyId=<id>,\n             amountFrom=<min>, amountTo=<max>,        // amountFrom = balance >=, amountTo = balance <=\n             orderBy=\"balance\", orderValue=\"DESC\")    // omit linkedToActorId for a form-wide ranking\n// linkedToActorDirection=\"children\" keeps only the anchor's children (expand/collapse a node),\n// \"parents\" only its parents; omit / \"both\" = either direction (default).\n\n// Save tokens: every read/traversal tool above (getRelatedActors, getActor,\n// getLayerActors, searchLayerActors, searchActors, filterActors, ...) accepts an\n// optional `filter` field-selection arg — comma-separated fields to return, e.g.\n// filter=\"id,title,formId\" (dotted paths like data.status pick nested data fields).\n// The server returns only those fields. NOT a row filter (that's search / q).\ngetRelatedActors(type=\"children\", actorId=\"<actorId>\", filter=\"id,title,formId\")\n```\n\n---\n\n## Financial Operations\n\n> Accounts are a finance concern — see `/simulator-finance` for the full workflow. Quick reference:\n\n### Accounts\n\n```\ngetAccounts(actorId=\"<actor>\")\ngetAccount(accountId=\"<acc>\")\ncreateAccountPair(accountName=\"Balance\", currencyName=\"USD\")     // bootstrap: creates name + currency if missing AND grants pair access\ncreateAccount(actorId=\"<actor>\", nameId=\"<name>\", currencyId=\"<cur>\", accountType=\"default\")\nsetAccountAmount(accountId=\"<acc>\", amount=1000)                 // fixed-balance correction\ndeleteAccount(actorId=\"<actor>\", currencyId=\"<cur>\", nameId=\"<name>\", accountType=\"default\")\n```\n\n### Currencies & Account Names\n\n```\ngetCurrencies()\ncreateCurrency(name=\"USD\", symbol=\"$\", precision=2)\ngetAccountNames()\ncreateAccountName(name=\"Balance\", abbreviation=\"BAL\")\n```\n\n---\n\n## Key Rules\n\n- **File-based workflow is preferred** for building and editing graphs — write a YAML file, then `pushGraphFile`.\n- **Create Graph + Layer first**, then work with the layer's YAML file. Never skip the graph→layer link.\n- **`formName` takes priority over `formId`** in the YAML file and in `createActor` calls.\n- **Do NOT include `data`** in the YAML for system forms — the server auto-injects shape/view/blockId.\n- **For custom forms** (formId specified by user or formName not in the catalog): call `getForm(formId)` first, then build `actors.data` from the returned field schema using field `name` as keys.\n- **Always set `color`** (hex string) for flowchart blocks.\n- **Local `id` values** in the YAML are replaced with server UUIDs after `pushGraphFile`. Use short readable names (\n  `start`, `validate`, `end`) for new actors.\n- **`pullGraphFile` → edit → `pushGraphFile`** is the standard edit cycle for existing layers.\n- `laId` ≠ `actorId`. The file workflow handles laId management automatically.\n- Space actors ~200–300 px apart; use the layout algorithm for coordinates.\n- **To place a user/person on the graph, use their twin actor** — resolve it with\n  `getSystemActor(objType=\"user\", objId=<userId>)` and place that `actorId`. A bare `userId`\n  is not a graph node. (See `$CLAUDE_PLUGIN_ROOT/docs/entities/users.md`.)\n\n---\n\n## Reference Documents\n\n| Path                                                            | When to read                                   |\n|-----------------------------------------------------------------|------------------------------------------------|\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/actors.md`                   | Full actor property list and types             |\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/links.md`                    | Link/edge properties and type system           |\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/layers.md`                   | Layer types and behavior                       |\n| `$CLAUDE_PLUGIN_ROOT/docs/user-flows/graph-functionality.md`    | Graph building walkthrough with test scenarios |\n| `$CLAUDE_PLUGIN_ROOT/docs/user-flows/actor-graph-management.md` | Managing actors on graphs — practical patterns |\n"
}