Update to Corezoid

{
  "description": "Creates and manages Corezoid dashboards — adds charts (column, pie, funnel, table), binds metrics to process nodes, configures real-time mode, and sets up drill-down linking between dashboards. Activate whenever a user asks to create a dashboard, add a chart, visualize process metrics, set up reporting for a Corezoid process, configure real-time monitoring, or asks what dashboards or charts exist. Also activate when the user wants to show task counts, completion rates, error rates, or any other process statistics visually in Corezoid.\n",
  "included_files": [],
  "name": "corezoid-dashboard-manager",
  "skill_md_contents": "---\nname: corezoid-dashboard-manager\ndescription: >\n  Creates and manages Corezoid dashboards — adds charts (column, pie, funnel, table), binds metrics\n  to process nodes, configures real-time mode, and sets up drill-down linking between dashboards.\n  Activate whenever a user asks to create a dashboard, add a chart, visualize process metrics,\n  set up reporting for a Corezoid process, configure real-time monitoring, or asks what\n  dashboards or charts exist. Also activate when the user wants to show task counts, completion\n  rates, error rates, or any other process statistics visually in Corezoid.\n---\n\n# Corezoid Dashboard Manager\n\n## How to call these tools\n\nEvery operation in this skill is an **action of the single `cz-dashboards` MCP tool** —\nthe individual names below are action strings, not tools of their own:\n\n```\ncz-dashboards {\"action\": \"add-chart\", \"args\": {\"dashboard_id\": 1234, \"name\": \"Errors\", \"chart_type\": \"column\", \"series\": \"[…]\"}}\n```\n\nArguments always go inside `args`; the shorthand used in the examples below — `add-chart(dashboard_id=1234, …)` — means exactly that call. When unsure about an action's\narguments, call `cz-dashboards {\"action\": \"<action>\", \"help\": true}` — it returns the\nfull schema and runs nothing.\n\n## What dashboards are\n\nA Corezoid dashboard visualizes **task counters in process nodes** — it shows how many tasks\nare accumulated in (or have passed through) specific nodes. The data comes directly from\nrunning processes, not from external databases.\n\nKey implication: processes must be deployed and have tasks flowing through them for data to appear.\n\n---\n\n## Actions of `cz-dashboards`\n\n| Action | Purpose |\n|--------|---------|\n| `create-dashboard` | Create a new dashboard, returns `obj_id` (= dashboard_id) |\n| `get-dashboard` | Get dashboard details including all charts and series |\n| `add-chart` | Add a chart to a dashboard, returns `obj_id` (hex chart ID) |\n| `get-chart` | Get a single chart with its series |\n| `modify-chart` | Modify an existing chart — always provide full series array |\n| `set-dashboard-layout` | Save chart positions on the grid — **required** to make charts visible |\n\n`pull-process` is a tool of its own (not an action): call it directly to pull the\nprocess JSON and find the node IDs a series points at.\n\n---\n\n## Workflow: Create a dashboard with charts\n\n### Step 1 — Identify the process (MANDATORY FIRST STEP)\n\n**Before doing anything else**, resolve the target process:\n\n1. Check whether the user already provided a process identifier — a file path, process name, or process ID — in the current message or conversation history.\n2. If no identifier is provided, ask:\n\n   > \"Which process(es) do you want to monitor? You can provide a file path (e.g. `123_payment.conv.json`), a process name, or a process ID.\"\n\n   Do **not** call any MCP tools until the user provides an identifier.\n3. If the user gave a **name or ID** (not a file path), search the local working directory for the matching `.conv.json` file using the `find` or `grep` Bash tools (the project is already pulled locally).\n4. Once the file path is known and the file exists locally, open and read it to find node IDs in `scheme.nodes[].id` — note the IDs of nodes you want to measure. End nodes are best as primary metric sources.\n\n   If the process is not available locally, fall back to:\n   ```\n   pull-process(process_id=<PROC_ID>)\n   ```\n\n5. Also clarify with the user (if not already clear):\n   - Which nodes represent the metrics they care about?\n   - What kind of visualization: comparison (column), proportions (pie), sequential drop-off (funnel), or tabular (table)?\n\n### Step 2 — Create the dashboard\n\n```\ncreate-dashboard(title=\"Payment Monitoring\", description=\"Real-time payment flow metrics\")\n```\n\nNote the returned `dashboard_id` — needed for adding charts.\n\n### Step 3 — Add charts\n\nOne chart per visualization. The `add-chart` action returns a hex `obj_id` for the chart — save it for `modify-chart` calls.\n\n```\nadd-chart(\n  dashboard_id=<dashboard_id>,\n  name=\"Payment Outcomes\",\n  chart_type=\"column\",\n  series='[{\"conv_id\": 123456, \"node_id\": \"507f1f77bcf86cd799439016\", \"title\": \"Success\"}, {\"conv_id\": 123456, \"node_id\": \"507f1f77bcf86cd799439017\", \"title\": \"Error\"}]'\n)\n```\n\nChart types:\n\n| Type | When to use |\n|------|------------|\n| `column` | Comparing values across nodes or time periods |\n| `pie` | Showing how tasks split across outcomes |\n| `funnel` | Visualizing sequential drop-off through a flow |\n| `table` | Tabular display of metric values |\n\n> **Critical:** Use `column` (NOT `bar`) — `bar` is not a valid Corezoid chart type.\n\n### Step 4 — Verify series after creation\n\nAfter creating a chart, call the `get-chart` action to verify that `series` is populated. If it's empty, use `modify-chart` to add the series.\n\n```\nget-chart(chart_id=<hex_obj_id>, dashboard_id=<dashboard_id>)\n```\n\nIf `series` is empty, call the `modify-chart` action with the full series array.\n\n### Step 5 — Save the dashboard layout (MANDATORY)\n\n**Charts are invisible until the grid layout is saved.** After all charts are created and have series, call the `set-dashboard-layout` action:\n\n```\nset-dashboard-layout(\n  dashboard_id=<dashboard_id>,\n  grid='[\n    {\"chart_id\":\"<hex1>\",\"x\":0,\"y\":0,\"width\":6,\"height\":4},\n    {\"chart_id\":\"<hex2>\",\"x\":6,\"y\":0,\"width\":6,\"height\":4},\n    {\"chart_id\":\"<hex3>\",\"x\":0,\"y\":4,\"width\":12,\"height\":4}\n  ]'\n)\n```\n\nGrid layout rules:\n- Grid is **12 columns wide**\n- `x` + `width` must not exceed 12\n- Standard chart: `width: 6, height: 4` (two charts per row)\n- Wide chart: `width: 12, height: 4` (full row)\n- Charts stack vertically by incrementing `y` (use the previous row's `height` as the next `y`)\n- `chart_id` is the hex `obj_id` returned by `add-chart`\n\n### Step 6 — Advise on real-time mode\n\nReal-time mode works ONLY for these node types:\n- **End nodes** (`obj_type: 2`) — tasks that finished the process\n- **Waiting for Callback** — tasks waiting for external HTTP callback\n- **Delay** — tasks paused for a time period\n- **Set State** — tasks in a named state\n\nIntermediate nodes (Code, API Call, Condition) pass tasks through instantly — real-time shows 0.\n\n---\n\n## Modifying charts — full payload required\n\nWhen modifying a chart, **always include the full `series` array**. Partial updates are NOT\nsupported — omitting any field returns a validation error.\n\n- `chart_id` — hex string from `add-chart` response (`obj_id`)\n- `chart_type` sets `obj_type` in the API — must be `\"column\"`, `\"pie\"`, `\"funnel\"`, or `\"table\"`\n\n```\nmodify-chart(\n  chart_id=\"6a043a89e552e86e908941aa\",\n  dashboard_id=136542,\n  name=\"Updated Chart Title\",\n  chart_type=\"column\",\n  series='[{\"conv_id\": 123456, \"node_id\": \"507f1f77bcf86cd799439016\", \"title\": \"Success\"}]'\n)\n```\n\n---\n\n## Dashboard grid layout\n\nCharts are positioned on a grid. Use `width` and `height` fields (NOT `w`/`h`) — using\n`w`/`h` causes a validation error. Standard sizes: `width: 6, height: 4`.\n\n---\n\n## Funnel chart — node ordering matters\n\nFor funnel charts, add metrics in the **same order as the process flow**:\n\n```json\n[\n  {\"conv_id\": 123, \"node_id\": \"start-node-id\", \"title\": \"Started\"},\n  {\"conv_id\": 123, \"node_id\": \"mid-node-id\",   \"title\": \"Processed\"},\n  {\"conv_id\": 123, \"node_id\": \"final-node-id\", \"title\": \"Completed\"}\n]\n```\n\nThe funnel visualizes drop-off from each step to the next.\n\n---\n\n## Best practices\n\n- Use **End nodes** as primary metric sources — they reliably accumulate completed tasks\n- For error rate charts: add both Final (success) and Error end nodes as metrics on one column chart\n- Name metrics descriptively — labels appear directly on charts\n- Create separate dashboards: one for real-time ops monitoring, one for historical reporting\n- Group all metrics from one business flow (e.g., payment processing) on a single dashboard\n- Always verify `series` after chart creation — empty series means the chart won't render\n- Always call the `set-dashboard-layout` action after all charts are ready — charts are invisible without it\n- For drill-down: create the high-level dashboard first, then the detail dashboard, then link charts\n\n---\n\n## Dashboard operations reference\n\n| Goal | Tool / operation |\n|------|-----------------|\n| Create dashboard | `create-dashboard` → returns `obj_id` (dashboard_id) |\n| View dashboard + charts list | `get-dashboard(dashboard_id=...)` |\n| Add chart | `add-chart` → returns `obj_id` (hex chart ID) |\n| Get chart details + series | `get-chart(chart_id=<hex>, dashboard_id=...)` |\n| Modify chart | `modify-chart(chart_id=<hex>, dashboard_id=..., ...)` |\n| **Make charts visible** | `set-dashboard-layout(dashboard_id=..., grid='[...]')` |\n| Get node IDs for series | `pull-process` → read `scheme.nodes[].id` |\n\n**ID types to remember:**\n- `dashboard_id` — integer (e.g. `136542`)\n- `chart_id` — hex string (e.g. `\"6a043a89e552e86e908941aa\"`)\n- `node_id` in series — 24-char hex string from `scheme.nodes[].id`\n"
}