corezoid-dashboard-manager

# Corezoid Dashboard Manager

## What dashboards are

A Corezoid dashboard visualizes **task counters in process nodes** — it shows how many tasks
are accumulated in (or have passed through) specific nodes. The data comes directly from
running processes, not from external databases.

Key implication: processes must be deployed and have tasks flowing through them for data to appear.

---

## MCP Tools Reference

| Tool | Purpose |
|------|---------|
| `create-dashboard` | Create a new dashboard, returns `obj_id` (= dashboard_id) |
| `get-dashboard` | Get dashboard details including all charts and series |
| `add-chart` | Add a chart to a dashboard, returns `obj_id` (hex chart ID) |
| `get-chart` | Get a single chart with its series |
| `modify-chart` | Modify an existing chart — always provide full series array |
| `set-dashboard-layout` | Save chart positions on the grid — **required** to make charts visible |
| `pull-process` | Pull process JSON to find node IDs for series |

---

## Workflow: Create a dashboard with charts

### Step 1 — Identify the process (MANDATORY FIRST STEP)

**Before doing anything else**, resolve the target process:

1. Check whether the user already provided a process identifier — a file path, process name, or process ID — in the current message or conversation history.
2. If no identifier is provided, ask:

   > "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."

   Do **not** call any MCP tools until the user provides an identifier.
3. 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).
4. 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.

   If the process is not available locally, fall back to:
   ```
   pull-process(process_id=<PROC_ID>)
   ```

5. Also clarify with the user (if not already clear):
   - Which nodes represent the metrics they care about?
   - What kind of visualization: comparison (column), proportions (pie), sequential drop-off (funnel), or tabular (table)?

### Step 2 — Create the dashboard

```
create-dashboard(title="Payment Monitoring", description="Real-time payment flow metrics")
```

Note the returned `dashboard_id` — needed for adding charts.

### Step 3 — Add charts

One chart per visualization. The `add-chart` tool returns a hex `obj_id` for the chart — save it for `modify-chart` calls.

```
add-chart(
  dashboard_id=<dashboard_id>,
  name="Payment Outcomes",
  chart_type="column",
  series='[{"conv_id": 123456, "node_id": "507f1f77bcf86cd799439016", "title": "Success"}, {"conv_id": 123456, "node_id": "507f1f77bcf86cd799439017", "title": "Error"}]'
)
```

Chart types:

| Type | When to use |
|------|------------|
| `column` | Comparing values across nodes or time periods |
| `pie` | Showing how tasks split across outcomes |
| `funnel` | Visualizing sequential drop-off through a flow |
| `table` | Tabular display of metric values |

> **Critical:** Use `column` (NOT `bar`) — `bar` is not a valid Corezoid chart type.

### Step 4 — Verify series after creation

After creating a chart, call `get-chart` to verify that `series` is populated. If it's empty, use `modify-chart` to add the series.

```
get-chart(chart_id=<hex_obj_id>, dashboard_id=<dashboard_id>)
```

If `series` is empty, call `modify-chart` with the full series array.

### Step 5 — Save the dashboard layout (MANDATORY)

**Charts are invisible until the grid layout is saved.** After all charts are created and have series, call `set-dashboard-layout`:

```
set-dashboard-layout(
  dashboard_id=<dashboard_id>,
  grid='[
    {"chart_id":"<hex1>","x":0,"y":0,"width":6,"height":4},
    {"chart_id":"<hex2>","x":6,"y":0,"width":6,"height":4},
    {"chart_id":"<hex3>","x":0,"y":4,"width":12,"height":4}
  ]'
)
```

Grid layout rules:
- Grid is **12 columns wide**
- `x` + `width` must not exceed 12
- Standard chart: `width: 6, height: 4` (two charts per row)
- Wide chart: `width: 12, height: 4` (full row)
- Charts stack vertically by incrementing `y` (use the previous row's `height` as the next `y`)
- `chart_id` is the hex `obj_id` returned by `add-chart`

### Step 6 — Advise on real-time mode

Real-time mode works ONLY for these node types:
- **End nodes** (`obj_type: 2`) — tasks that finished the process
- **Waiting for Callback** — tasks waiting for external HTTP callback
- **Delay** — tasks paused for a time period
- **Set State** — tasks in a named state

Intermediate nodes (Code, API Call, Condition) pass tasks through instantly — real-time shows 0.

---

## Modifying charts — full payload required

When modifying a chart, **always include the full `series` array**. Partial updates are NOT
supported — omitting any field returns a validation error.

- `chart_id` — hex string from `add-chart` response (`obj_id`)
- `chart_type` sets `obj_type` in the API — must be `"column"`, `"pie"`, `"funnel"`, or `"table"`

```
modify-chart(
  chart_id="6a043a89e552e86e908941aa",
  dashboard_id=136542,
  name="Updated Chart Title",
  chart_type="column",
  series='[{"conv_id": 123456, "node_id": "507f1f77bcf86cd799439016", "title": "Success"}]'
)
```

---

## Dashboard grid layout

Charts are positioned on a grid. Use `width` and `height` fields (NOT `w`/`h`) — using
`w`/`h` causes a validation error. Standard sizes: `width: 6, height: 4`.

---

## Funnel chart — node ordering matters

For funnel charts, add metrics in the **same order as the process flow**:

```json
[
  {"conv_id": 123, "node_id": "start-node-id", "title": "Started"},
  {"conv_id": 123, "node_id": "mid-node-id",   "title": "Processed"},
  {"conv_id": 123, "node_id": "final-node-id", "title": "Completed"}
]
```

The funnel visualizes drop-off