Update to Simulator.Company

{
  "description": "Simulator.Company actor (record) specialist. Use when the user wants to create, update, read, search, or filter the *instances* of a form template (a.k.a. Account Template records) — i.e. data-bearing actors — and needs the `data` value protocol right. Activate when the user says \"create an actor\", \"add a record\", \"create a record from this template\", \"fill in a form\", \"update actor data\", \"find actors where field = …\", \"filter actors by balance\", \"создай актор\", \"заполни шаблон\", or \"добавь запись\". ALSO use this skill when the user asks what **processes / functions / Corezoid processes** an actor has or can call, or about an actor's **shared API keys / available functions** — call `getCorezoidProcesses`: \"what processes/functions can this actor call\", \"actor's connected processes\", \"actor's API keys\", \"available functions of the actor\", \"які процеси/функції доступні актору\", \"процеси актора\", \"функції актора\", \"ключі доступу актора\", \"какие процессы/функции у актора\", \"процессы актора\", \"доступные функции актора\". For graph/flowchart STRUCTURE (links, layers, FlowchartBlock diagrams) use `simulator-graph`; for designing the template itself use `simulator-forms`.\n",
  "included_files": [],
  "name": "simulator-actors",
  "skill_md_contents": "---\nname: simulator-actors\ndescription: >\n  Simulator.Company actor (record) specialist. Use when the user wants to create,\n  update, read, search, or filter the *instances* of a form template (a.k.a.\n  Account Template records) — i.e. data-bearing actors — and needs the `data`\n  value protocol right. Activate when the user says \"create an actor\", \"add a\n  record\", \"create a record from this template\", \"fill in a form\", \"update actor\n  data\", \"find actors where field = …\", \"filter actors by balance\", \"создай актор\",\n  \"заполни шаблон\", or \"добавь запись\". ALSO use this skill when the user asks what\n  **processes / functions / Corezoid processes** an actor has or can call, or about an\n  actor's **shared API keys / available functions** — call `getCorezoidProcesses`:\n  \"what processes/functions can this actor call\", \"actor's connected processes\",\n  \"actor's API keys\", \"available functions of the actor\", \"які процеси/функції доступні\n  актору\", \"процеси актора\", \"функції актора\", \"ключі доступу актора\", \"какие\n  процессы/функции у актора\", \"процессы актора\", \"доступные функции актора\". For\n  graph/flowchart STRUCTURE (links, layers, FlowchartBlock diagrams) use `simulator-graph`;\n  for designing the template itself use `simulator-forms`.\n---\n\n> **Curated tool names (v2 server):** `createActor`, `getActor`, `getActorByRef`,\n> `updateActor`, `setActorStatus`, `deleteActor`, `searchActors`, `filterActors`,\n> `searchLayerActors`, `getSystemActor`, `getCorezoidProcesses`. Call them by these exact names.\n>\n> **`getCorezoidProcesses(actorId)`** is THE tool for any question about an actor's\n> **processes / functions / available API integrations** — it returns the Corezoid processes\n> shared to the actor via its access API keys (what that actor can call). If the user asks\n> \"what functions/processes does this actor have\", \"what can this actor call\", or about the\n> actor's shared API keys, call `getCorezoidProcesses` — do not guess or use a graph-traversal tool.\n>\n> **`getSystemActor`** resolves the system \"twin\" actor of a workspace entity — pass\n> `objType=\"user\"`, `objId=\"<userId>\"` to get the actor representing a user (so you can attach\n> accounts to it or move value between users). Find the `userId` first with `searchUsers` /\n> `getUsers`. Money movement between users then goes through their twin actors' accounts via\n> **transfers** — see `simulator-finance`.\n\n# Simulator.Company Actor (Record) Specialist\n\nYou create and manage **actors** — the *instances* of a form template (Account\nTemplate). An actor's field values live in its `data` object. Getting the `data`\nshape right is the whole job, so this skill exists to make that mechanical.\n\n> **Relationship to the other skills**\n> - **`simulator-forms`** designs the *template* (`sections`/fields). Read it / a form\n>   first to learn the field `id`s.\n> - **`simulator-actors`** (this skill) creates/edits the *records* of that template.\n> - **`simulator-graph`** handles graph *structure* — links, layers, FlowchartBlock\n>   diagrams. If the user wants to wire actors together or place them on a layer, defer there.\n> - **`simulator-finance`** handles accounts/transactions on actors.\n\n## Workspace Context Check (MANDATORY FIRST STEP)\n\nVerify `accId` is known before any tool call. If not provided, ask:\n\n> Ask the user — **in their own language** (English, Ukrainian, or Russian) — which workspace to work in, i.e. for the Workspace ID (`accId`).\n\n`createActor` can also resolve a `formName` to its id, but only with a workspace set.\n\n---\n\n## The golden rule: `data` is keyed by field `id`\n\nAn actor's `data` is keyed by each form field's **`id`** (`item_<digits>`) — **not** by\nthe field `title` and **not** by its secondary `key`. So the first step of *every* actor\ncreate/update is:\n\n1. **Resolve the form.** `getForm(formId)` (or `searchForms` then `getForm`). Pass\n   `filter=\"id,title,sections\"` to keep it small.\n2. **Map each field you want to set** → its `id` and `class`.\n3. **Build `data`** using the per-class value shapes below.\n\n### Value shape by field class\n\n| Form field class / source | Value in `data` |\n|---|---|\n| `edit` text / password / email / phone | string — `\"dsdf@fsdf.com\"` |\n| `edit` int / float | number — `1` |\n| `check` | boolean — `true` |\n| `radio` | the selected option's `value` (string) — `\"o2\"` |\n| `select` (static `options`) | array of chosen option object(s) — `[{\"color\":\"#863434\",\"title\":\"one\",\"value\":\"s1\"}]` |\n| `select` → `layer`/`actorFilter`/`actorsBag`/`actors`/`formFilter` | `[{\"type\":\"actor\",\"title\":…,\"value\":\"<actor UUID>\"}]` (formFilter = the actors of a given form) |\n| `select` → `forms` | `[{\"type\":\"form\",\"title\":…,\"value\":<form id number>}]` |\n| `select` → `currencies` | `[{\"type\":\"currency\",\"title\":…,\"value\":<currency id number>}]` |\n| `select` → `accountNames` | `[{\"type\":\"accountName\",\"title\":…,\"value\":\"<account-name UUID>\"}]` |\n| `select` → `workspaceMembers` | `[{\"type\":\"workspaceMembers\",\"title\":…,\"value\":<user id number>}]` |\n| `select` → `api`/`corezoidSyncApi` | array of synced options (`[]` until synced) |\n| `multiSelect` | array — `[{\"title\":\"one\",\"value\":\"…\"},{\"title\":\"two\",\"value\":\"…\"}]` |\n| `calendar` | `{\"startDate\":…,\"endDate\":…,\"timeZoneOffset\":-180,\"sendInvite\":false}` (unix **seconds**) |\n| `upload` | array of file refs (`[]` when empty) |\n| `label` / `button` / `image` | **no entry** — display-only |\n\n> The `type` discriminator only appears on **dynamic** `select` values. Static\n> `select`/`multiSelect` values carry just `{title,value,color?}`. For a dynamic\n> `select`, the `value` must be a real referenced id (actor UUID / currency id /\n> account-name UUID / user id) — resolve it first (e.g. `getCurrencies`,\n> `getAccountNames`, `searchActors`) rather than guessing.\n\n> **Geolocation (top-level, not `data`).** An actor carries an optional position independent\n> of its form fields: `geoPosition` — `{\"lat\": <number>, \"lon\": <number>}` in WGS84 decimal\n> degrees, or `null` to clear — and `geoName` — a location name string, or `null`. Both are set\n> on `createActor`/`updateActor`. Latitude is hard-bounded to -90..90 (out of range is rejected),\n> longitude outside ±180 wraps cyclically, and coordinates round to 6 decimals; `lat`/`lon` are\n> set as a pair.\n\nFull reference: `$CLAUDE_PLUGIN_ROOT/docs/entities/actors.md` and `…/forms.md`.\n\n### Multiform actors (`__form__<formId>:<itemId>`)\n\nAn actor can instantiate **several forms at once** (a *multiform* actor; the linked form\ntree is called a **UAT**). Its `data` then carries fields from more than one form, namespaced\nby a key prefix:\n\n- Fields of the actor's **root** `formId` (the one you pass to `createActor`/`updateActor`) →\n  the **plain** field `id`, e.g. `\"name\"`.\n- Fields owned by **another** form → **`__form__<thatFormId>:<itemId>`**.\n\n```json\n// data for an actor created under its root form, with one field from form 16951\n{\n  \"name\": \"Kulo Oleksandr\",\n  \"__form__16951:position\": \"Software engineer\"\n}\n```\n\nThe prefix changes only the **key** — the value still follows the per-class shapes above.\nNotes:\n- To learn `<thatFormId>`'s field ids, `getForm(<thatFormId>)` just like the root form.\n- **Discover the tree** with `getFormsTree(accId, formId)` / `getLinkedForms(typeLink, formId)`\n  (see `simulator-forms`) to find which forms a multiform actor spans before writing its `data`.\n- Attaching the *set* of forms to an actor (`PUT /actors/actor_forms`) is still **not** a curated\n  tool — but you can already write/read multiform `data` via `createActor`/`updateActor`/`getActor`.\n\n#### Creating under the tree when asked for a CHILD (leaf) form\n\nIn a UAT workspace, an actor can only be created under the **root** form of the tree — not\nunder an arbitrary leaf. So when the user says *\"create an actor for form X\"* and\n`getForm(X)` returns a **non-empty `parentId`** (X is a nested/child form), do **not** call\n`createActor(formId=X, …)` — the backend rejects it with **`400: Form <id> is not UAT`**.\n\nInstead:\n\n1. **Walk up `parentId`** from X to the root form of the UAT tree (`getForm` repeatedly until\n   `parentId` is empty).\n2. **Call `createActor` with `formId` = the root.**\n3. Put the **root's own fields** under their plain id (`\"name\"`), and the **requested child\n   form's fields** under the `__form__<childFormId>:<itemId>` prefix.\n\n```json\n// Request: \"create an actor for form Employee (16951)\", where Employee.parentId = People (16950)\n// → create under the ROOT People (16950), not under Employee:\ncreateActor(formId=16950, title=\"Olena Kovalenko\", data={\n  \"name\": \"Olena Kovalenko\",                            // People (root) field\n  \"__form__16951:position\": \"Senior Backend Engineer\"   // Employee (child) field\n})\n```\n\n> **Do NOT** flip the child form to `uat` status via `setFormStatus` to \"work around\" the\n> error — that mutates the shared template for everyone. Use the **root** form as the\n> `formId` instead.\n\n---\n\n## Create an actor\n\n```\ncreateActor(\n  formId=42,                       # or formName=\"Car\" (resolved via the workspace)\n  title=\"Toyota Camry 2023\",\n  color=\"#409547\",                 # optional\n  ref=\"car-toyota-camry-2023\",     # optional, unique per form\n  contextLayerId=\"<layer UUID>\",   # optional — place it on a layer\n  data={\n    \"item_make\":  \"Toyota\",\n    \"item_model\": \"Camry\",\n    \"item_year\":  2023,\n    \"item_active\": true,\n    \"item_cond\":  [ {\"title\":\"excellent\",\"value\":\"c1\"} ],\n    \"item_owner\": [ {\"type\":\"workspaceMembers\",\"title\":\"Alex Kulo\",\"value\":1} ]\n  })\n```\n\n- Provide **`formId`** (number) or **`formName`** (string, resolved to its id).\n- Omit fields you are not setting; never invent `item_*` keys not present in the form.\n- Display-only fields (`label`/`button`/`image`) get no `data` entry.\n\n## Read an actor\n\n```\ngetActor(actorId=\"<UUID>\", filter=\"id,title,data\")           # by UUID\ngetActorByRef(formId=42, ref=\"car-…\", filter=\"id,title,data\") # by (form, ref)\n```\n\nUse `filter` to fetch only the fields you need — actor `data` can be large.\n\n## Update an actor\n\n```\nupdateActor(\n  formId=42, actorId=\"<UUID>\",\n  data={ \"item_year\": 2024, \"item_active\": false })   # only these keys change\n```\n\n`updateActor` is a **partial** update of `data` — keys you include are replaced, the rest\nare untouched. You can also set `title`/`description`/`color`/`status`/`ref`. To clear a\nmulti-value field, send `[]`.\n\n**Re-key by `ref`.** `updateActor(formId, actorId, ref=\"…\")` sets or changes the actor's\nexternal reference — a stable business key, **unique per form** — the same key `createActor`\naccepts, but now editable after creation. Then address the actor by its key instead of its\nUUID: `getActorByRef(formId, ref)`. Omit `ref` to leave it unchanged.\n\n**Embed a smart form (script) in an actor.** Set `appId` (on `createActor` / `updateActor`)\nto a Smart Form (CDU/Script app) actor id — the actor's card then renders/runs that smart\nform; `appSettings` `{autorun, expired, users, groups, fullWidth}` tunes it. See\n`simulator-smart-forms`.\n\n**Rich `description` (BBCode).** An actor's `description` renders **BBCode** — chips like\n`[actor=<otherActorId>]Label[/actor]` (nested actor card) and `[application=<smartFormId>]Label[/application]`\n(smart-form chip), plus formatting (`[b]`, `[color=…]`, `[h2]`, `[ul][*]…[/ul]`, `[url=…]`) and\n`[md]…[/md]` for markdown. Fetch the environment's exact tag set with **`getBbcodeTags`**.\n**BBCode is processed only OUTSIDE `[md]` blocks.** The reverse matters too: a `description` is rendered as **BBCode by default, not markdown**, so any markdown you write (`##`, `-`, `**bold**`, tables) MUST be wrapped in `[md]…[/md]` or it shows as literal text — applies to every `createActor`/`updateActor` `description`, Events actors (chats/meetings/tasks) included (e.g. `description=\"[md]## Agenda\\n- item[/md]\"`). See `docs/entities/reactions.md` → \"Embedding\".\n\n## Holes — empty placeholder nodes\n\nA **hole** is an empty placeholder slot on a graph, rendered as a hollow node: it marks a\nposition in the structure that is **not yet filled**. A hole becomes a normal actor once it is\nfilled with data — ideal for laying out a template / \"company DNA\" graph up front and turning\neach slot into a real actor as the data arrives.\n\n```\ncreateActor(formId=3279, title=\"Budget\", hole=true)        # create a hole\nupdateActor(formId=3279, actorId=\"<UUID>\", hole=true)      # turn an existing actor into a hole\nupdateActor(formId=3279, actorId=\"<UUID>\", hole=false)     # fill it — hole → normal actor\n```\n\n- `hole` is a top-level **boolean** on `createActor` / `updateActor`; omit it → default `false`.\n- It is independent of `status` and `data` (a hole can still carry a `title`). `hole=false`\n  alone flips a hole back to a normal node.\n- Place a hole on a layer like any node (e.g. `manageLayerActors` — see `simulator-graph`).\n\n## Status & delete\n\n```\nsetActorStatus(actorId=\"<UUID>\", status=\"verified\")\ndeleteActor(actorId=\"<UUID>\")     # irreversible — confirm with the user first\n```\n\n---\n\n## Search & filter\n\n### `searchActors` — free-text across the workspace\n```\nsearchActors(accId=\"ws_xxx\", query=\"camry\", limit=20, filter=\"id,title,formId\")\n```\nBest for \"find the actor named …\". Run before `createActor` to avoid duplicates.\n\n### `filterActors` — list/rank a form's actors, optionally by an account balance\n```\n# All actors of a form, newest first\nfilterActors(formId=42, orderBy=\"updated_at\", withStats=true)\n\n# Data-field filter on the actor data\nfilterActors(formId=42, q=\"status=active\", status=\"verified,pending\")\n\n# Rank by an account's CURRENT balance, scoped to one anchor actor's neighbours\nfilterActors(\n  formId=42,\n  linkedToActorId=\"<anchor UUID>\",   # only actors linked to this one (both directions)\n  accountNameId=\"<account-name UUID>\",\n  currencyId=9,\n  amountFrom=1000,                    # balance >= 1000\n  orderBy=\"balance\", orderValue=\"DESC\",\n  withStats=true)\n\n# Only the CHILD actors of a node (e.g. expand/collapse a node's children)\nfilterActors(formId=42, linkedToActorId=\"<anchor UUID>\", linkedToActorDirection=\"children\")\n# ...or only its parents: linkedToActorDirection=\"parents\"; omit / \"both\" = either direction (default)\n```\n\n- `q` filters on actor **data** fields; `search` does full-text on the title; `status`\n  filters by status.\n- Balance filtering is **current balance only**. For turnover over a period, read each\n  actor's accounts with `getAccounts(actorId, from, to)` (a `simulator-finance` task).\n- Returned balances are real decimal values — do **not** divide by `10^precision`.\n\n### `searchLayerActors` — search within one layer\n```\nsearchLayerActors(actorId=\"<layer UUID>\", query=\"camry\")\n```\n\n---\n\n## End-to-end example\n\n```\n# 1. Resolve the template and its field ids\nsearchForms(accId=\"ws_xxx\", q=\"Car\")          → formId 42\ngetForm(formId=42, filter=\"id,title,sections\") → field ids: item_make, item_year, …\n\n# 2. Avoid a duplicate\nsearchActors(accId=\"ws_xxx\", query=\"Camry 2023\")\n\n# 3. Create the record\ncreateActor(formId=42, title=\"Toyota Camry 2023\",\n  data={ \"item_make\":\"Toyota\", \"item_model\":\"Camry\", \"item_year\":2023 })\n\n# 4. (optional) attach an account — see simulator-finance\ncreateAccount(actorId=\"<new UUID>\", nameId=\"<aname>\", currencyId=1, accountType=\"fact\")\n```\n\n## Reference Documents\n\n| Path | When to read |\n|---|---|\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/actors.md` | Actor `data` protocol + per-class value shapes |\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/forms.md` | Field-class catalogue / dynamic select sources |\n| `$CLAUDE_PLUGIN_ROOT/docs/entities/search.md` | Search & filter internals |\n\n## Tips\n\n- Always `getForm` first — `data` keys are the form's field `id`s, not titles.\n- If a form has a `parentId`, it's a **leaf** of a UAT tree — create the actor under the **root** form and put the leaf's fields under `__form__<childId>:<field>`. Symptom of using the wrong root: `400: Form <id> is not UAT`.\n- Dynamic-`select` values reference real ids; resolve them, don't guess.\n- `createActor` accepts `formName` (resolved in the active workspace) when you don't have the id.\n- `updateActor` is partial; `deleteActor` is irreversible — confirm first.\n- For wiring actors into a graph (links/layers/flowcharts) use `simulator-graph`.\n- `getCorezoidProcesses(actorId)` lists the Corezoid processes shared to an actor via its access API keys — i.e. the functions/processes that actor can call.\n"
}