> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Basics

> Turn Reasoning messages and their entity references into readable text for your users.

All Reasoning features use the same **ReasonMessage** format. Build one renderer
and reuse it for findings, summaries, and other Reasoning output.

## Message format

A message contains `text` and an `entities` array. Each entity has a `kind` and a
string `value`:

```json title="A Reasoning message" theme={null}
{
  "text": "{{0}} cannot work any shift because of {{1}}.",
  "entities": [
    { "kind": "EMPLOYEE_ID", "value": "employee-1" },
    { "kind": "RULE_LABEL", "value": "weekly-rest" }
  ]
}
```

Replace each `{{n}}` with the display value of `entities[n]`, resolving it by
`kind` using your application's data. For example, the message above could read:

> Alex Morgan cannot work any shift because of Weekly rest.

Indices belong to each message's own array. Replace every occurrence, including
repeated references. When `entities` is empty, display `text` directly.

## Entity reference types

| `kind` | Resolve `value` to |
| - | - |
| `SHIFT_ID` | The display name of the shift with this ID. |
| `EMPLOYEE_ID` | The display name of the employee with this ID. |
| `ROLE_ID` | The display name of the role with this ID. |
| `ATTRIBUTE_CATEGORY` | Your category label, such as “Qualification”. |
| `ATTRIBUTE_VALUE` | Your value label, such as “Registered nurse” for `RN`. |
| `RULE_LABEL` | A readable rule description, matched by exact, case-sensitive label. |
| `DATE` | A localized `YYYY-MM-DD` date, preserving the calendar date across timezones. |
| `DAY_INDEX` | A day label or date in a recurring schedule; `"0"` is the horizon's first day. |
| `TIME` | A time such as `07:00`, formatted for your user. |

> [!WARNING]
>
> Handle every entity reference type before showing Reasoning output to users,
> even if your first responses only contain a few types.

Render resolved values as text or links. Use readable fallbacks for missing
records, and avoid using generated prose to drive application logic.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.